Module org.praxislive.code
Package org.praxislive.code.userapi

Class Ref<T>

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() use strings.init(ArrayList::new);.

Can also be used with Out and AuxOut annotations to provide output ports to share the Ref value with Ref.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 with Ref.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 final class 
    Ref.ChangeEvent<T>
    Event passed to onChangeHandler 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 a Ref 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 a Ref 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

    Modifier and Type
    Method
    Description
    Ref<T>
    apply(Consumer<? super T> consumer)
    Pass the value to the provided Consumer function.
    <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, or clear 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, or other.
    protected void
    reset()
     
    Ref<T>
    set(T value)
    Set the value.
    Ref<T>
    setAsync(Async<T> async)
    Set the value from completion of the provided Async.
    Ref<T>
    unbind()
    Clear all bindings added via bind(java.util.function.BiConsumer, java.util.function.BiConsumer, java.lang.Object) from this Ref.
    protected void
    valueChanged(T currentValue, T previousValue)
     

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Ref

      public Ref()

  • Method Details

    • 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 calling init 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 any onReset and onDispose handlers called.
      Parameters:
      function -
      Returns:
      this

    • set

      public Ref<T> set(T value)
      Set the value. This is a shortcut equivalent to calling ref.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 provided Async. 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

    • 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 V
      unbinder - the function to unbind the value, usually a method reference on T that accepts a value V
      bindee - the value, usually a lambda or method reference
      Returns:
      this

    • unbind

      public Ref<T> unbind()
      Clear all bindings added via bind(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, or other.

      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 provided Ref.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, or clear has been explicitly called.
      Parameters:
      onDisposeHandler - handler to dispose ref value
      Returns:
      this

    • dispose

      protected void dispose()

    • reset

      protected void reset()

    • valueChanged

      protected void valueChanged(T currentValue, T previousValue)

    • log

      protected abstract void log(Exception ex)