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

Class Ref<T>

  • Type Parameters:
    T - 
    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);

    Most methods will throw an Exception if init() has not been called with a Supplier function.

    • Constructor Summary

      Constructors 
      Constructor Description
      Ref()  

    • 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

      • asyncCompute

        public <K> Ref<T> asyncCompute​(K key,
                               Function<K,​? extends T> function)
        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 removal on reset or disposal. This also allows for the easy removal 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.
        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

      • 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 -
        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 -
        Returns:
        this

      • dispose

        protected void dispose()

      • reset

        protected void reset()

      • log

        protected abstract void log​(Exception ex)