org.codefx.libfx.listener.handle

Class ListenerHandleBuilder<O,L>

java.lang.Object

org.codefx.libfx.listener.handle.ListenerHandleBuilder<O,L>

Type Parameters:

O - the type of the observable instance (e.g ObservableValue or ObservableMap) to which the listener will be added

L - the type of the listener which will be added to the observable

public final class ListenerHandleBuilder<O,L>
extends Object

A builder for a ListenerHandle. Note that it is abstract enough to be used for all kinds of observable/listener relation and not just for those occurring in JavaFX.

The created handle manages whether the listener is currently attached. The functions specified to onAttach(BiConsumer) and onDetach(BiConsumer) are only called when necessary. This is the case

• if attach is called when the listener is not currently added to the observable
• if detach is called when the listener is currently added to the observable

This implies that they can be stateless functions which simply add and remove the listener. The functions are called with the observable and listener specified during construction.

The ListenerHandle returned by this builder is not yet attached, i.e. it does not initially call the functions given to onAttach or onDetach.

Example

A typical use looks like this:

 Property<String> textProperty;
 ChangeListener<String> textListener;

 ListenerHandle textListenerHandle = ListenerHandleBuilder
        .from(textProperty, textListener)
        .onAttach((property, listener) -> property.addListener(listener))
        .onDetach((property, listener) -> property.removeListener(listener))
        .build();
 

Or, with method references:

 Property<String> textProperty;
 ChangeListener<String> textListener;

 ListenerHandle textListenerHandle = ListenerHandleBuilder
        .from(textProperty, textListener)
        .onAttach(Property::addListener))
        .onDetach(Property::removeListener)
        .build();
 

Method Summary

Modifier and Type	Method and Description
ListenerHandle	buildAttached() Creates a new listener handle and attaches the listener.
ListenerHandle	buildDetached() Creates a new, initially detached listener handle.
static <O,L> ListenerHandleBuilder<O,L>	from(O observable, L listener) Creates a builder for a generic ListenerHandle.
ListenerHandleBuilder<O,L>	onAttach(BiConsumer<? super O,? super L> add) Sets the function which is executed when the built ListenerHandle must add the listener because attach was called.
ListenerHandleBuilder<O,L>	onDetach(BiConsumer<? super O,? super L> remove) Sets the function which is executed when the built ListenerHandle must remove the listener because detach was called.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

from

public static <O,L> ListenerHandleBuilder<O,L> from(O observable,
                                                    L listener)

Creates a builder for a generic ListenerHandle.

Type Parameters:

O - the type of the observable instance (e.g ObservableValue or ObservableMap) to which the listener will be added

L - the type of the listener which will be added to the observable

Parameters:

observable - the observable instance to which the listener will be added

listener - the listener which will be added to the observable

Returns:

a ListenerHandleBuilder for a ListenerHandle.

onAttach

public ListenerHandleBuilder<O,L> onAttach(BiConsumer<? super O,? super L> add)

Sets the function which is executed when the built ListenerHandle must add the listener because attach was called.

Because the built handle manages whether the listener is currently attached, the function is only called when necessary, i.e. when attach is called when the listener is currently not added to the observable.

Parameters:

add - the BiConsumer called on attach; the arguments for the function are the observable and listener specified during this builder's construction

Returns:

this builder for fluent calls

onDetach

public ListenerHandleBuilder<O,L> onDetach(BiConsumer<? super O,? super L> remove)

Sets the function which is executed when the built ListenerHandle must remove the listener because detach was called.

Because the built handle manages whether the listener is currently attached, the function is only called when necessary, i.e. when detach is called when the listener is currently added to the observable.

Parameters:

remove - the BiConsumer called on detach; the arguments for the function are the observable and listener specified during this builder's construction

Returns:

this builder for fluent calls

buildAttached

public ListenerHandle buildAttached()
                             throws IllegalStateException

Creates a new listener handle and attaches the listener. This will only succeed if onAttach(BiConsumer) and onDetach(BiConsumer) have been called.

Returns:

a new ListenerHandle; initially attached

Throws:

IllegalStateException - if onAttach(BiConsumer) or onDetach(BiConsumer) have not been called

buildDetached

public ListenerHandle buildDetached()
                             throws IllegalStateException

Creates a new, initially detached listener handle. This will only succeed if onAttach(BiConsumer) and onDetach(BiConsumer) have been called.

Returns:

a new ListenerHandle; initially detached

Throws:

IllegalStateException - if onAttach(BiConsumer) or onDetach(BiConsumer) have not been called