- java.lang.Object
-
- org.praxislive.code.userapi.Ref<T>
-
- Type Parameters:
T
- type of reference
public abstract class Ref<T> extends Object
A generic object holder for safely passing references between different iterations of code.Use with
Inject
eg.@Inject Ref<List<String>> strings;
Then in init() / setup() usestrings.init(ArrayList::new);
.Can also be used with
Out
andAuxOut
annotations to provide output ports to share the Ref value withRef.Input
input ports on other components.A Ref field on a container can additionally be annotated with
Ref.Publish
to share the value with direct child Ref fields annotated withRef.Subscribe
.Many methods will throw an Exception if init() has not been called with a Supplier function, even if the value has been set
The default dispose handler checks if the referenced value is
AutoCloseable
and automatically closes it.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Ref.ChangeEvent<T>
Event passed toonChangeHandler
when the Ref value changes.static interface
Ref.Initializer<T>
A functional type for initializing a Ref, used by Providers.static class
Ref.Input<T>
A field type for Ref input ports.static class
Ref.Provider
Providers initialize Ref instances so that the underlying value can be used directly as the injected field type.static interface
Ref.Publish
Annotation to be used on aRef
field on a container, to allow Ref fields of direct child components to subscribe and bind to the values of the published Ref.static interface
Ref.Subscribe
Annotation to be used on aRef
field to bind its values to the values of the published Ref in the direct parent container.
-
Constructor Summary
Constructors Constructor Description Ref()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description Ref<T>
apply(Consumer<? super T> consumer)
Pass the value to the provided Consumer function.<K> Ref<T>
asyncCompute(K key, Function<K,? extends T> function)
Deprecated.<V> Ref<T>
bind(BiConsumer<? super T,V> binder, BiConsumer<? super T,V> unbinder, V bindee)
Bind something (usually a callback / listener) to the reference, providing for automatic attachment and removal on reference change, reset or disposal.Ref<T>
clear()
Disposes the value and clears initialization.Ref<T>
compute(Function<? super T,? extends T> function)
Transform the value using the supplied function.protected void
dispose()
T
get()
Return the value.Ref<T>
ifPresent(Consumer<? super T> consumer)
Pass the value to the provided Consumer function if one exists.Ref<T>
init(Supplier<? extends T> supplier)
Initialize the reference, calling the supplier function if a value is needed.protected abstract void
log(Exception ex)
Ref<T>
onChange(Consumer<Ref.ChangeEvent<T>> onChangeHandler)
Provide a function to handle changes in the Ref value.Ref<T>
onDispose(Consumer<? super T> onDisposeHandler)
Provide a function to run on the value whenever the value is being disposed of, either because the Ref has been removed from the code, the root is being stopped, orclear
has been explicitly called.Ref<T>
onReset(Consumer<? super T> onResetHandler)
Provide a function to run on the value whenever the Ref is reset - eg.T
orElse(T other)
Returns the ref value if present, orother
.protected void
reset()
Ref<T>
set(T value)
Set the value.Ref<T>
setAsync(Async<T> async)
Set the value from completion of the providedAsync
.Ref<T>
unbind()
Clear all bindings added viabind(java.util.function.BiConsumer, java.util.function.BiConsumer, java.lang.Object)
from this Ref.protected void
valueChanged(T currentValue, T previousValue)
-
-
-
Method Detail
-
init
public Ref<T> init(Supplier<? extends T> supplier)
Initialize the reference, calling the supplier function if a value is needed.The supplier may return null, although this is not recommended.
- Parameters:
supplier
-- Returns:
- this
-
get
public T get()
Return the value. The Ref must be initialized by callinginit
first.- Returns:
- value
-
clear
public Ref<T> clear()
Disposes the value and clears initialization. Before using the Ref again it must be re-initialized.- Returns:
- this
-
apply
public Ref<T> apply(Consumer<? super T> consumer)
Pass the value to the provided Consumer function. The value must be initialized first.- Parameters:
consumer
-- Returns:
- this
-
compute
public Ref<T> compute(Function<? super T,? extends T> function)
Transform the value using the supplied function. Either an existing or new value may be returned. If a new value is returned, the value will be replaced and anyonReset
andonDispose
handlers called.- Parameters:
function
-- Returns:
- this
-
set
public Ref<T> set(T value)
Set the value. This is a shortcut equivalent to callingref.init(() -> value).compute(old -> value)
.- Parameters:
value
- ref value- Returns:
- this
-
setAsync
public Ref<T> setAsync(Async<T> async)
Set the value from completion of the providedAsync
. If the Async is already completed, the value will be set before return. Calls to other methods that set the Ref value will cancel the pending set.- Parameters:
async
- async value to set- Returns:
- this
-
asyncCompute
@Deprecated public <K> Ref<T> asyncCompute(K key, Function<K,? extends T> function)
Deprecated.Run an intensive or time consuming function as a background task to update the value. The function should be self-contained and try not to capture or access any state from the component. Use the key argument to pass in data required to compute the new value - ideally not the current contents of the Ref unless it is immutable or thread-safe.- Type Parameters:
K
- type of key value- Parameters:
key
- a key value used by the function to calculate the new valuefunction
- an intensive or time-consuming function- Returns:
- this
-
bind
public <V> Ref<T> bind(BiConsumer<? super T,V> binder, BiConsumer<? super T,V> unbinder, V bindee)
Bind something (usually a callback / listener) to the reference, providing for automatic attachment and removal on reference change, reset or disposal. This also allows for the easy management of listeners that are lambdas or method references, without the need to keep a reference to them.The binder and unbinder arguments will usually be method references for the add and remove listener methods. The bindee will usually be the listener, often as a lambda or method reference.
This method does not require the reference to have been initialized. If the reference is available, the bindee will be attached during this method call. If the reference is not available, the bindee will be queued for attachment when the reference is set.
- Type Parameters:
V
- the type of the value to bind to the reference, usually a callback / listener- Parameters:
binder
- the function to bind the value, usually a method reference on T that accepts a value Vunbinder
- the function to unbind the value, usually a method reference on T that accepts a value Vbindee
- the value, usually a lambda or method reference- Returns:
- this
-
unbind
public Ref<T> unbind()
Clear all bindings added viabind(java.util.function.BiConsumer, java.util.function.BiConsumer, java.lang.Object)
from this Ref.- Returns:
- this
-
ifPresent
public Ref<T> ifPresent(Consumer<? super T> consumer)
Pass the value to the provided Consumer function if one exists.Unlike
apply
this may be safely called prior to initialization.- Parameters:
consumer
-- Returns:
- this
-
orElse
public T orElse(T other)
Returns the ref value if present, orother
.This method may be safely called prior when the ref has not been initialized. If the ref has been initialized to
null
then the other value will be returned.- Parameters:
other
- value to return if not initialized or null- Returns:
- value or other
-
onChange
public Ref<T> onChange(Consumer<Ref.ChangeEvent<T>> onChangeHandler)
Provide a function to handle changes in the Ref value. The providedRef.ChangeEvent
gives access to the current and previous values, if available.- Parameters:
onChangeHandler
- handler of change event- Returns:
- this
-
onReset
public Ref<T> onReset(Consumer<? super T> onResetHandler)
Provide a function to run on the value whenever the Ref is reset - eg. when the Ref is passed from one iteration of code to the next.- Parameters:
onResetHandler
- handler to reset ref value- Returns:
- this
-
onDispose
public Ref<T> onDispose(Consumer<? super T> onDisposeHandler)
Provide a function to run on the value whenever the value is being disposed of, either because the Ref has been removed from the code, the root is being stopped, orclear
has been explicitly called.- Parameters:
onDisposeHandler
- handler to dispose ref value- Returns:
- this
-
dispose
protected void dispose()
-
reset
protected void reset()
-
log
protected abstract void log(Exception ex)
-
-