Class 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.

    • Constructor Detail

      • Ref

        public Ref()
    • 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 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
      • 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 value
        function - 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 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
      • 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)