Package sprouts.impl

Class Sprouts

java.lang.Object
sprouts.impl.Sprouts
All Implemented Interfaces:
SproutsFactory
public final class Sprouts extends Object implements SproutsFactory
Exposes an API for configuring the SproutsFactory, which serves implementations of the various property types in the Sprouts library, like Event, Val, Var, Vals and Vars. The methods implemented here are used by the various factory methods of the sprouts API like Var.of(Object), Vals.of(Object, Object[])...
So technically speaking, this is a configurable singleton, so be careful when using it as it effectively maintains global + mutable state!

You can also configure general library defaults here, like a library global logging marker (see loggingMarker()).

  • Method Summary

    Modifier and Type
    Method
    Description
    <K, V> Association<K,V>
    associationOf(Class<K> keyType, Class<V> valueType)
    Creates a new association between keys and values with the given key and value types.
    <K, V> Association<K,V>
    associationOfLinked(Class<K> keyType, Class<V> valueType)
    Creates a new linked association between keys and values with the given key and value types, where the order of key-value pairs in this type of association is based on the order in which the pairs are added to the association.
    <K extends Comparable<K>, V>
    Association<K,V>
    associationOfSorted(Class<K> keyType, Class<V> valueType)
    Creates a new association between keys and values with the given key and value types, where the keys are sorted in natural order.
    <K, V> Association<K,V>
    associationOfSorted(Class<K> keyType, Class<V> valueType, Comparator<K> comparator)
    Creates a new association between keys and values with the given key and value types, where the key-value pairs are sorted using the supplied comparator.
    Channel
    defaultChannel()
    The default channel used for change events.
    String
    defaultId()
    The default id for properties which do not have an id explicitly specified.
    Channel
    defaultObservableChannel()
    The default channel used for Observable events, registered through the Observable.subscribe(Observer) method.
    <T> ValDelegate<T>
    delegateOf(Val<T> source, Channel channel, SingleChange change, @Nullable T newValue, @Nullable T oldValue)
    Creates a delegate for when a Val/Var property changes its value or is explicitly triggered to propagate the event to all derived Viewable instances and their Actions.
    <T> ValsDelegate<T>
    delegateOf(Vals<T> source, SequenceChange changeType, int index, Vals<T> newValues, Vals<T> oldValues)
    Creates a delegate for when a Vals/Vars property list to be specifically designed as a context object passed to Actions registered on Viewables, like for example through the Viewable.onChange(Channel, Action) method.
    Event
    event()
    A factory method to create a new Event instance.
    Event
    eventOf(Event.Executor executor)
    A factory method to create a new Event instance with the given executor.
    static SproutsFactory
    factory()
    A SproutsFactory is used by the various factory methods of this API like Var.of(Object), Vals.of(Object, Object[])...
    Pattern
    idPattern()
    The regex Pattern used to validate property ids.
    <T, B> Var<B>
    lensOf(Var<T> source, B nullObject, Lens<T,B> lens)
    A factory method for creating a Lens based Var property, which is a zoomed in handle to a field variable of a non-null Class of a non-nullable type B that is a member part of the source property item type T.
    The resulting Var can be mutated, and the changes will be propagated to the source property value through the lens.
    If the item in the source property value T is null, then the resulting Var will use the provided nullObject as a default value.
    <T, B> Var<B>
    lensOf(Var<T> source, Lens<T,B> lens)
    A factory method for creating a Lens based Var property, which is a zoomed in handle to a field variable of a non-null Class of a non-nullable type B that is a member part of the source property item type T.
    The resulting Var can be mutated, and the changes will be propagated to the source property value through the lens.
    Both T and B are expected to be data types with value semantics, meaning they should be immutable and have proper equals and hashCode implementations.
    <T, B> Var<B>
    lensOfNullable(Class<B> type, Var<T> source, Lens<T,B> lens)
    A factory method for creating a Lens based Var property, which is a zoomed in handle to a field variable of a non-null Class of a nullable type B that is a member part of the source property item type T.
    If you want to create a lens property which can never store null values, use the SproutsFactory.lensOf(Var, Object, Lens) factory method instead.
    The resulting Var can be mutated, and the changes will be propagated to the source property value through the lens.
    org.slf4j.Marker
    loggingMarker()
    Many features in Sprouts are designed to preserve the control flow of your application by catching exceptions and then logging them.
    static void
    setFactory(SproutsFactory factory)
    Sets the factory to be used by the various factory methods of this API like Var.of(Object), Vals.of(Object, Object[])...
    void
    setLoggingMarker(org.slf4j.Marker marker)
    You may want to set this to filter logging done by Sprouts, which is typically a type of log that is contains exceptions caused by bugs and failed sanity checks.
    Tuple<Byte>
    tupleOf(byte... bytes)
    Creates an immutable tuple of non-nullable items from a primitive array of bytes.
    Tuple<Double>
    tupleOf(double... doubles)
    Creates an immutable, non-nullable Tuple<Double> from a primitive array of doubles.
    Tuple<Float>
    tupleOf(float... floats)
    Creates an immutable, non-nullable Tuple<Float> from a primitive array of floats.
    Tuple<Integer>
    tupleOf(int... ints)
    Creates an immutable tuple of non-nullable items from a primitive array of integers.
    Tuple<Long>
    tupleOf(long... longs)
    Creates an immutable tuple of non-nullable items from a primitive array of longs.
    <T> Tuple<T>
    tupleOf(Class<T> type)
    Creates an empty tuple of non-nullable items from the supplied type.
    <T> Tuple<T>
    tupleOf(Class<T> type, Iterable<T> iterable)
    Creates an immutable tuple of non-nullable items from the supplied type and iterable of values.
    <T> Tuple<T>
    tupleOf(Class<T> type, Maybe<T>... maybes)
    Creates an immutable tuple of non-nullable items from the supplied type and vararg values.
    <T> Tuple<T>
    tupleOf(Class<T> type, T... items)
    Creates an immutable tuple of non-nullable items from the supplied type and values.
    <T> Tuple<T>
    tupleOf(T first, T... rest)
    Creates an immutable tuple of non-nullable items from one or more non-null items.
    <T> Tuple<@Nullable T>
    tupleOfNullable(Class<T> type)
    Creates an empty tuple of nullable items from the supplied type.
    <T> Tuple<@Nullable T>
    tupleOfNullable(Class<T> type, @Nullable T... values)
    Creates an immutable tuple of nullable items from the supplied type and values.
    <T> Tuple<@Nullable T>
    tupleOfNullable(Class<T> type, Iterable<@Nullable T> iterable)
    Creates an immutable tuple of nullable items from the supplied type and iterable of values.
    <T> Val<T>
    valOf(Val<T> toBeCopied)
    Creates a non-empty Val copy from the supplied Val.
    <T> Val<T>
    valOf(T item)
    Creates a non-null Val instance of the given non-null item.
    <T> Val<@Nullable T>
    valOfNull(Class<T> type)
    Creates an empty Val property from the given type class.
    <T> Val<@Nullable T>
    valOfNullable(Class<T> type, @Nullable T item)
    Creates a new Val property from a type class and an item which may or may not be null.
    <T> Val<@Nullable T>
    valOfNullable(Val<@Nullable T> toBeCopied)
    Creates a nullable Val instance of the given type by copying the value from another Val.
    <T> Vals<T>
    valsOf(Class<T> type)
    A factory method which creates an empty Vals instance dedicated to hold properties storing non-nullable items of the specified type.
    <T> Vals<T>
    valsOf(Class<T> type, Iterable<Val<T>> properties)
    Creates a Vals property list from a type class and an iterable of Val properties, each wrapping a non-nullable item of the specified type.
    <T> Vals<T>
    valsOf(Class<T> type, Val<T>... vars)
    This factory method creates a Vals instance from a type class and an array of Val properties, each wrapping a non-nullable item of the specified type.
    <T> Vals<T>
    valsOf(Class<T> type, Vals<T> vals)
    Creates a Vals property list of the given type with the specified items from another Vals instance.
    <T> Vals<T>
    valsOf(Class<T> type, T... items)
    A factory method for creating a Vals property list from a type class and an array of items, which are all instances of the given type and may not be null.
    <T> Vals<T>
    valsOf(Val<T> first, Val<T>... rest)
    A factory method for creating a Vals property list from one or more Val properties, which are all instances of the same type and may not be null.
    <T> Vals<T>
    valsOf(T first, T... rest)
    A factory method for creating a Vals property list from one or more items, which are all instances of the same type and may not be null.
    <T> Vals<@Nullable T>
    valsOfNullable(Class<T> type)
    This factory method instantiates an empty Vals instance from a type class of a nullable type T.
    <T> Vals<@Nullable T>
    valsOfNullable(Class<T> type, @Nullable T... items)
    Creates a Vals property list of Val properties from a type class and an array of items, which are all instances of the given type or null.
    <T> Vals<@Nullable T>
    valsOfNullable(Class<T> type, Val<@Nullable T>... vals)
    Creates a Vals property list of Val properties from a type class and an array of properties, holding nullable items which are all instances of the given type or null.
    <T> Vals<@Nullable T>
    valsOfNullable(Class<T> type, Vals<@Nullable T> vals)
    This factory method creates a Vals property list from a type class representing a nullable type T and another Vals instance, which contains nullable items being compatible with the specified type T.
    <T> Vals<@Nullable T>
    valsOfNullable(Val<@Nullable T> first, Val<@Nullable T>... rest)
    Creates a Vals property list of Val properties from one or more Val properties, which are all instances of the same type and may hold null values.
    <E> ValueSet<E>
    valueSetOf(Class<E> type)
    Creates a new value set specifically for holding elements of the supplied type.
    <E> ValueSet<E>
    valueSetOfLinked(Class<E> type)
    Creates a new value set specifically for holding elements of the supplied type, and where the order of the elements is defined by the insertion order.
    <E extends Comparable<? super E>>
    ValueSet<E>
    valueSetOfSorted(Class<E> type)
    Creates a new value set specifically for holding elements of the supplied type, elements are sorted based on the natural ordering of the elements (which are expected to implement Comparable).
    <E> ValueSet<E>
    valueSetOfSorted(Class<E> type, Comparator<E> comparator)
    Creates a new value set specifically for holding elements of the supplied type, but with an explicit order defined by the supplied comparator.
    <T, V extends T>
    Var<T>
    varOf(Class<T> type, V item)
    Creates a Var property instance of the given non-nullable type with the specified non-null item.
    <T> Var<T>
    varOf(T item)
    Creates a Var property instance from a given non-nullable item, where the Maybe.type() is inferred from the type of the item.
    <T> Var<T>
    varOfNull(Class<T> type)
    Creates an empty Var instance (storing a null item) of the given type.
    <T> Var<T>
    varOfNullable(Class<T> type, @Nullable T item)
    Creates a Var property instance from a given non-null Class of a nullable type and as well as an item of that type, which therefore may be null.
    <T> Vars<T>
    varsOf(Class<T> type)
    Creates an empty list of non-nullable properties from the supplied type.
    <T> Vars<T>
    varsOf(Class<T> type, Iterable<Var<T>> vars)
    Creates a list of non-nullable properties from the supplied type and iterable of values.
    <T> Vars<T>
    varsOf(Class<T> type, Var<T>... vars)
    Creates a list of non-nullable properties from the supplied type and vararg values.
    <T> Vars<T>
    varsOf(Class<T> type, T... items)
    Creates a list of non-nullable properties from the supplied type and values.
    <T> Vars<T>
    varsOf(Var<T> first, Var<T>... rest)
    Creates a list of non-nullable properties from one or more non-nullable properties.
    <T> Vars<T>
    varsOf(T first, T... rest)
    Creates a list of non-nullable properties from one or more non-null values.
    <T> Vars<@Nullable T>
    varsOfNullable(Class<T> type)
    Creates an empty list of nullable properties from the supplied type.
    <T> Vars<@Nullable T>
    varsOfNullable(Class<T> type, @Nullable T... values)
    Creates a list of nullable properties from the supplied type and values.
    <T> Vars<T>
    varsOfNullable(Class<T> type, Iterable<Var<T>> vars)
    Creates a list of nullable properties from the supplied type and iterable of values.
    <T> Vars<@Nullable T>
    varsOfNullable(Class<T> type, Var<@Nullable T>... vars)
    Creates a list of nullable properties from the supplied type and varargs properties.
    <T> Vars<@Nullable T>
    varsOfNullable(Var<@Nullable T> first, Var<@Nullable T>... rest)
    Creates a list of nullable properties from the supplied properties.
    <T extends @Nullable Object, U extends @Nullable Object, R>
    Viewable<R>
    viewOf(Class<R> type, Val<T> first, Val<U> second, BiFunction<T,U,R> combiner)
    Creates a non-nullable Viewable instance of the given type which is a composite of two Val instances whose values are combined using the specified combiner function.
    <T, U> Viewable<T>
    viewOf(Class<T> type, Val<U> source, Function<U,T> mapper)
    Creates a mapped Viewable instance of the given type which is a view of the value of the specified source Val mapped to a different type using the provided mapper function.
    You can register observers on the returned Viewable to receive updates when the value of the source property changes.
    <T> Viewable<T>
    viewOf(Val<T> source)
    Creates a Viewable instance of the given Val.
    <T extends @Nullable Object, U extends @Nullable Object>
    Viewable<@NonNull T>
    viewOf(Val<T> first, Val<U> second, BiFunction<T,U,@NonNull T> combiner)
    Creates a non-null Viewable instance which is a composite of two Val instances whose values are combined using the specified combiner function.
    <T> Viewables<T>
    viewOf(Vals<T> source)
    Creates a Viewables instance of the given Vals.
    <T, U> Viewable<U>
    viewOf(U nullObject, U errorObject, Val<T> source, Function<T,@Nullable U> mapper)
    Creates a Viewable instance where he item of a supplied source Val is mapped to a different (non-null) type using the provided mapper function as well as an error and null object in case the source value is null or an error occurs during mapping.
    You can register Actions or Observers on the returned Viewable to receive updates when the value of the source property changes.
    <T, U> Viewables<U>
    viewOf(U nullObject, U errorObject, Vals<T> source, Function<T,@Nullable U> mapper)
    Creates a mapped Viewables instance of the given Vals with specified null and error objects.
    <T extends @Nullable Object, U extends @Nullable Object, R>
    Viewable<@Nullable R>
    viewOfNullable(Class<R> type, Val<T> first, Val<U> second, BiFunction<T,U,@Nullable R> combiner)
    Creates a nullable Viewable instance of the given type which is a composite of two Val instances whose values are combined using the specified combiner function.
    <T, U> Viewable<@Nullable U>
    viewOfNullable(Class<U> type, Val<T> source, Function<T,@Nullable U> mapper)
    Creates a Viewable instance of the given nullable type which is a view of the value of the specified source Val mapped to a different (nullable) type using the provided mapper function.
    You can register observers on the returned Viewable to receive updates when the value of the source property changes.
    <T extends @Nullable Object, U extends @Nullable Object>
    Viewable<@Nullable T>
    viewOfNullable(Val<T> first, Val<U> second, BiFunction<T,U,@Nullable T> combiner)
    Creates a nullable Viewable instance which is a composite of two Val instances whose values are combined using the specified combiner function.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface sprouts.impl.SproutsFactory

    maybeOf, maybeOf, maybeOfNull, maybeOfNullable, maybeOfNullable, tupleOf, tupleOfNullable, tupleOfNullable

  • Method Details

    • factory

      public static SproutsFactory factory()
      A SproutsFactory is used by the various factory methods of this API like Var.of(Object), Vals.of(Object, Object[])... to create instances of these properties.
      You can plug in your own factory implementation through the setFactory(SproutsFactory) method, where you can then serve your own implementations of the various property types in the Sprouts library.
      Returns:
      The default factory for creating instances of the various property types in the Sprouts library.

    • setFactory

      public static void setFactory(SproutsFactory factory)
      Sets the factory to be used by the various factory methods of this API like Var.of(Object), Vals.of(Object, Object[])... to create instances of these properties.
      You can use a custom SproutsFactory to instantiate and serve your own implementations of the various property types in the Sprouts library.

      WARNING: This is a global + mutable state, so be careful when using it
      as it will have global side effects on the various factory methods of this API.

      Parameters:
      factory - The factory to be used by the various factory methods of this API.
      Throws:
      NullPointerException - if the factory is null.

    • delegateOf

      public <T> ValDelegate<T> delegateOf(Val<T> source, Channel channel, SingleChange change, @Nullable T newValue, @Nullable T oldValue)
      Description copied from interface: SproutsFactory
      Creates a delegate for when a Val/Var property changes its value or is explicitly triggered to propagate the event to all derived Viewable instances and their Actions.
      Specified by:
      delegateOf in interface SproutsFactory
      Type Parameters:
      T - The item type of the property for which the delegate is created.
      Parameters:
      source - The source property for which the delegate is created.
      channel - The channel on which the change event was triggered (see Val.fireChange(Channel)).
      change - The type of change that occurred in the property, which may also be SingleChange.NONE if the change was triggered explicitly without any actual change in the value.
      newValue - The new value of the property after the change.
      oldValue - The old value of the property before the change.
      Returns:
      A delegate for the given Val property.

    • delegateOf

      public <T> ValsDelegate<T> delegateOf(Vals<T> source, SequenceChange changeType, int index, Vals<T> newValues, Vals<T> oldValues)
      Description copied from interface: SproutsFactory
      Creates a delegate for when a Vals/Vars property list to be specifically designed as a context object passed to Actions registered on Viewables, like for example through the Viewable.onChange(Channel, Action) method.
      Specified by:
      delegateOf in interface SproutsFactory
      Type Parameters:
      T - The type of the property for which the delegate is created.
      Parameters:
      source - The source property for which the delegate is created.
      changeType - The type of change that occurred in the property.
      index - The (start) index at which the change occurred.
      newValues - The new values of the property after the change.
      oldValues - The old values of the property before the change.
      Returns:
      A delegate for the given Vals property.

    • event

      public Event event()
      Description copied from interface: SproutsFactory
      A factory method to create a new Event instance. An Event can be triggered using the Event.fire() method, and it will notify all Actions registered on Observers derived from the Event instance through the Event.observable() method.
      Specified by:
      event in interface SproutsFactory
      Returns:
      A new Event instance with the default executor.

    • eventOf

      public Event eventOf(Event.Executor executor)
      Description copied from interface: SproutsFactory
      A factory method to create a new Event instance with the given executor. An Event can be triggered using the Event.fire() method, and it will notify all Actions registered on Observers derived from the Event instance through the Event.observable() method.
      Specified by:
      eventOf in interface SproutsFactory
      Parameters:
      executor - The executor to be used for the event. It must not be null.
      Returns:
      A new Event instance with the specified executor.

    • valOfNullable

      public <T> Val<@Nullable T> valOfNullable(Class<T> type, @Nullable T item)
      Description copied from interface: SproutsFactory
      Creates a new Val property from a type class and an item which may or may not be null. The resulting property may or may not be empty (see Maybe.isEmpty().
      Specified by:
      valOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Val property.
      Parameters:
      type - The type of the item to be wrapped in the Val, which must not be null.
      item - The item to be wrapped in the Val. It can be null.
      Returns:
      A Val instance containing the item, or an empty Val if the item is null.

    • valOfNull

      public <T> Val<@Nullable T> valOfNull(Class<T> type)
      Description copied from interface: SproutsFactory
      Creates an empty Val property from the given type class. The Maybe.isEmpty() method of the returned instance will always return true, indicating that the Val does not contain a value.
      Specified by:
      valOfNull in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Val.
      Parameters:
      type - The type of the item to be wrapped in the Val. It must not be null.
      Returns:
      An immutable and empty Val instance containing a null item.

    • valOf

      public <T> Val<T> valOf(T item)
      Description copied from interface: SproutsFactory
      Creates a non-null Val instance of the given non-null item. The Maybe.isPresent() method of the returned instance will always return true, indicating that the Val does contain a value.
      Specified by:
      valOf in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Val.
      Parameters:
      item - The item to be wrapped in the Val. It must not be null.
      Returns:
      An immutable and non-empty Val instance containing the item.

    • valOf

      public <T> Val<T> valOf(Val<T> toBeCopied)
      Description copied from interface: SproutsFactory
      Creates a non-empty Val copy from the supplied Val. The supplied Val must not contain a null item. So if the factory call was successful, then the Maybe.isPresent() method of the returned instance will always return true, indicating that the Val contains a value. The returned instance is effectively an immutable copy of the supplied Val.
      Specified by:
      valOf in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Val.
      Parameters:
      toBeCopied - The Val instance to be copied. It must not be null and it must not contain a null value.
      Returns:
      A new Val instance containing the value from the given Val.

    • valOfNullable

      public <T> Val<@Nullable T> valOfNullable(Val<@Nullable T> toBeCopied)
      Description copied from interface: SproutsFactory
      Creates a nullable Val instance of the given type by copying the value from another Val.
      Specified by:
      valOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Val.
      Parameters:
      toBeCopied - The Val instance to be copied. It must not be null, however, the value in the Val can be null.
      Returns:
      A new Val instance containing the value from the given Val, or an empty Val if the value is null.

    • viewOf

      public <T> Viewable<T> viewOf(Val<T> source)
      Description copied from interface: SproutsFactory
      Creates a Viewable instance of the given Val. You can register observers on the returned Viewable to receive updates when the value of the Val changes.
      Specified by:
      viewOf in interface SproutsFactory
      Type Parameters:
      T - The type of the item in the Val.
      Parameters:
      source - The source Val for which the view is created.
      Returns:
      A Viewable instance that wraps the given Val. The source may not be null.

    • viewOf

      public <T extends @Nullable Object, U extends @Nullable Object> Viewable<@NonNull T> viewOf(Val<T> first, Val<U> second, BiFunction<T,U,@NonNull T> combiner)
      Description copied from interface: SproutsFactory
      Creates a non-null Viewable instance which is a composite of two Val instances whose values are combined using the specified combiner function. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      Specified by:
      viewOf in interface SproutsFactory
      Type Parameters:
      T - The type of the first Val value.
      U - The type of the second Val value.
      Parameters:
      first - The first Val to be combined into a Viewable composite.
      second - The second Val to be combined into a Viewable composite.
      combiner - The function that combines the values of the two Val instances into a single value.
      Returns:
      A Viewable instance that combines the values of the two Val instances using the specified combiner function.

    • viewOfNullable

      public <T extends @Nullable Object, U extends @Nullable Object> Viewable<@Nullable T> viewOfNullable(Val<T> first, Val<U> second, BiFunction<T,U,@Nullable T> combiner)
      Description copied from interface: SproutsFactory
      Creates a nullable Viewable instance which is a composite of two Val instances whose values are combined using the specified combiner function. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      Specified by:
      viewOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the first Val value.
      U - The type of the second Val value.
      Parameters:
      first - The first Val to be combined into a Viewable composite.
      second - The second Val to be combined into a Viewable composite.
      combiner - The function that combines the values of the two Val instances into a single value.
      Returns:
      A Viewable instance that combines the values of the two Val instances using the specified combiner function.

    • viewOf

      public <T extends @Nullable Object, U extends @Nullable Object, R> Viewable<R> viewOf(Class<R> type, Val<T> first, Val<U> second, BiFunction<T,U,R> combiner)
      Description copied from interface: SproutsFactory
      Creates a non-nullable Viewable instance of the given type which is a composite of two Val instances whose values are combined using the specified combiner function. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      Specified by:
      viewOf in interface SproutsFactory
      Type Parameters:
      T - The type of the first Val value.
      U - The type of the second Val value.
      R - The type of the resulting Viewable.
      Parameters:
      type - The type of the resulting Viewable.
      first - The first Val to be combined into a Viewable composite.
      second - The second Val to be combined into a Viewable composite.
      combiner - The function that combines the values of the two Val instances into a single value.
      Returns:
      A Viewable instance that combines the values of the two Val instances using the specified combiner function.

    • viewOfNullable

      public <T extends @Nullable Object, U extends @Nullable Object, R> Viewable<@Nullable R> viewOfNullable(Class<R> type, Val<T> first, Val<U> second, BiFunction<T,U,@Nullable R> combiner)
      Description copied from interface: SproutsFactory
      Creates a nullable Viewable instance of the given type which is a composite of two Val instances whose values are combined using the specified combiner function. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      Specified by:
      viewOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the first Val value.
      U - The type of the second Val value.
      R - The type of the resulting Viewable.
      Parameters:
      type - The type of the resulting Viewable.
      first - The first Val to be combined into a Viewable composite.
      second - The second Val to be combined into a Viewable composite.
      combiner - The function that combines the values of the two Val instances into a single value.
      Returns:
      A Viewable instance that combines the values of the two Val instances using the specified combiner function.

    • viewOf

      public <T> Viewables<T> viewOf(Vals<T> source)
      Description copied from interface: SproutsFactory
      Creates a Viewables instance of the given Vals. You can register observers on the returned Viewables to receive updates when the items in the Vals change.
      Specified by:
      viewOf in interface SproutsFactory
      Type Parameters:
      T - The type of the items in the Vals.
      Parameters:
      source - The source Vals for which the view is created.
      Returns:
      A Viewables instance that wraps the given Vals.

    • viewOf

      public <T, U> Viewable<T> viewOf(Class<T> type, Val<U> source, Function<U,T> mapper)
      Description copied from interface: SproutsFactory
      Creates a mapped Viewable instance of the given type which is a view of the value of the specified source Val mapped to a different type using the provided mapper function.
      You can register observers on the returned Viewable to receive updates when the value of the source property changes.
      Specified by:
      viewOf in interface SproutsFactory
      Type Parameters:
      T - The type parameter to which the source value will be mapped in the resulting Viewable.
      U - The type of the value in the source Val.
      Parameters:
      type - The type class to which the source value will be mapped into the resulting Viewable.
      source - The source Val for which the view is created.
      mapper - The function that maps the source value to the resulting value in the Viewable.
      Returns:
      A Viewable instance which is a view of the specified source Val mapped to the given type.

    • viewOf

      public <T, U> Viewables<U> viewOf(U nullObject, U errorObject, Vals<T> source, Function<T,@Nullable U> mapper)
      Description copied from interface: SproutsFactory
      Creates a mapped Viewables instance of the given Vals with specified null and error objects. This is useful when you want to provide default values for the Viewables when the source property contains a null value or an error occurs during mapping.
      Specified by:
      viewOf in interface SproutsFactory
      Type Parameters:
      T - The type of the items in the Vals.
      U - The type of the items in the resulting Viewables.
      Parameters:
      nullObject - The default value to be used when the source value is null.
      errorObject - The default value to be used when an error occurs during mapping.
      source - The source Vals for which the view is created.
      mapper - The function that maps the source value to the resulting value.
      Returns:
      A Viewables instance that wraps the given Vals with specified null and error objects.

    • viewOf

      public <T, U> Viewable<U> viewOf(U nullObject, U errorObject, Val<T> source, Function<T,@Nullable U> mapper)
      Description copied from interface: SproutsFactory
      Creates a Viewable instance where he item of a supplied source Val is mapped to a different (non-null) type using the provided mapper function as well as an error and null object in case the source value is null or an error occurs during mapping.
      You can register Actions or Observers on the returned Viewable to receive updates when the value of the source property changes. This method is useful when you want a mapped Viewable with a default/fallback values in case the source property contains a null value or an error occurs during mapping.
      Specified by:
      viewOf in interface SproutsFactory
      Type Parameters:
      T - The type of the item in the source Val to be mapped. It can be nullable.
      U - The type of the item to map to in the resulting Viewable. It may never be null in the resulting Viewable.
      Parameters:
      nullObject - The default value to be used when the source value is null.
      errorObject - The default value to be used when an error occurs during mapping.
      source - The source Val for which the view is created.
      mapper - The function that maps the source value to the resulting value in the Viewable returned by this method.
      Returns:
      A Viewable instance that dynamically maps the source value or alternatively uses the specified null and error objects.

    • viewOfNullable

      public <T, U> Viewable<@Nullable U> viewOfNullable(Class<U> type, Val<T> source, Function<T,@Nullable U> mapper)
      Description copied from interface: SproutsFactory
      Creates a Viewable instance of the given nullable type which is a view of the value of the specified source Val mapped to a different (nullable) type using the provided mapper function.
      You can register observers on the returned Viewable to receive updates when the value of the source property changes.
      Specified by:
      viewOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type parameter to which the source value will be mapped in the resulting Viewable. It can be nullable.
      U - The type of the value in the source Val. It can also be nullable.
      Parameters:
      type - The type class to which the source value will be mapped into the resulting Viewable. This argument may not be null (Although the resulting Viewable can contain null values).
      source - The source Val for which the view is created.
      mapper - The function that maps the source value to the resulting value in the Viewable.
      Returns:
      A Viewable instance which is a view of the specified source Val mapped to the given (nullable) type.

    • lensOf

      public <T, B> Var<B> lensOf(Var<T> source, Lens<T,B> lens)
      Description copied from interface: SproutsFactory
      A factory method for creating a Lens based Var property, which is a zoomed in handle to a field variable of a non-null Class of a non-nullable type B that is a member part of the source property item type T.
      The resulting Var can be mutated, and the changes will be propagated to the source property value through the lens.
      Both T and B are expected to be data types with value semantics, meaning they should be immutable and have proper equals and hashCode implementations. We recommend using record types for T and B to reliably ensure value semantics.
      Specified by:
      lensOf in interface SproutsFactory
      Type Parameters:
      T - The type of the source property value, which is expected to be non-nullable.
      B - The type of the field in the source property value T, which can be nullable.
      Parameters:
      source - The source Var from which the lens is created.
      lens - The lens that defines how to access the field of type B in the source property value T.
      Returns:
      A Var instance that represents the field of type B in the source property value T.

    • lensOf

      public <T, B> Var<B> lensOf(Var<T> source, B nullObject, Lens<T,B> lens)
      Description copied from interface: SproutsFactory
      A factory method for creating a Lens based Var property, which is a zoomed in handle to a field variable of a non-null Class of a non-nullable type B that is a member part of the source property item type T.
      The resulting Var can be mutated, and the changes will be propagated to the source property value through the lens.
      If the item in the source property value T is null, then the resulting Var will use the provided nullObject as a default value. If you want to create a lens property which can store null values, use the SproutsFactory.lensOfNullable(Class, Var, Lens) method instead.
      Both T and B are expected to be data types with value semantics, meaning they should be immutable and have proper equals and hashCode implementations. We recommend using record types for T and B to reliably ensure value semantics.
      Specified by:
      lensOf in interface SproutsFactory
      Type Parameters:
      T - The type of the source property value, which is expected to be non-nullable.
      B - The type of the field in the source property value T, which can be nullable.
      Parameters:
      source - The source Var from which the lens is created.
      nullObject - The default value to be used when the source value is null.
      lens - The lens that defines how to access the field of type B in the source property value T. This lens property may never store null values.
      Returns:
      A Var instance that represents the field of type B in the source property value T.

    • lensOfNullable

      public <T, B> Var<B> lensOfNullable(Class<B> type, Var<T> source, Lens<T,B> lens)
      Description copied from interface: SproutsFactory
      A factory method for creating a Lens based Var property, which is a zoomed in handle to a field variable of a non-null Class of a nullable type B that is a member part of the source property item type T.
      If you want to create a lens property which can never store null values, use the SproutsFactory.lensOf(Var, Object, Lens) factory method instead.
      The resulting Var can be mutated, and the changes will be propagated to the source property value through the lens.

      Both T and B are expected to be data types with value semantics, so they should be immutable and have proper equals and hashCode implementations. We recommend using record types for T and B to reliably ensure value semantics.

      Specified by:
      lensOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the source property value, which is expected to be non-nullable.
      B - The type of the field in the source property value T, which can be nullable.
      Parameters:
      type - The type of the resulting Var.
      source - The source Var from which the lens is created.
      lens - The lens that defines how to access the field of type B in the source property value T.
      Returns:
      A Var instance that represents the field of type B in the source property value T.

    • varOfNullable

      public <T> Var<T> varOfNullable(Class<T> type, @Nullable T item)
      Description copied from interface: SproutsFactory
      Creates a Var property instance from a given non-null Class of a nullable type and as well as an item of that type, which therefore may be null. The resulting property is nullable, meaning it can hold a value of the given type or be null. If you want to create a property which can never hold null values, use SproutsFactory.varOf(Class, Object) instead of this method.
      Specified by:
      varOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Var.
      Parameters:
      type - The type of the item to be wrapped in the Var, which must not be null.
      item - The item to be wrapped in the Var. It can be null.
      Returns:
      A Var instance containing the item, or an empty Var if the item is null.

    • varOfNull

      public <T> Var<T> varOfNull(Class<T> type)
      Description copied from interface: SproutsFactory
      Creates an empty Var instance (storing a null item) of the given type. If you want to create a property which can never hold null values, use SproutsFactory.varOf(Class, Object) instead of this method.
      Specified by:
      varOfNull in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Var.
      Parameters:
      type - The type of the item to be wrapped in the Var, which must not be null.
      Returns:
      A Var instance containing a null item.

    • varOf

      public <T> Var<T> varOf(T item)
      Description copied from interface: SproutsFactory
      Creates a Var property instance from a given non-nullable item, where the Maybe.type() is inferred from the type of the item.
      Specified by:
      varOf in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Var.
      Parameters:
      item - The item to be wrapped in the Var. It must not be null.
      Returns:
      A Var instance containing the item.

    • varOf

      public <T, V extends T> Var<T> varOf(Class<T> type, V item)
      Description copied from interface: SproutsFactory
      Creates a Var property instance of the given non-nullable type with the specified non-null item. The resulting property is non-nullable, meaning it can only hold a value of the given type and cannot be null. The supplied item must be a subtype of the specified type.
      Specified by:
      varOf in interface SproutsFactory
      Type Parameters:
      T - The type of the item to be wrapped in the Var.
      V - The type of the item to be wrapped in the Var, which must be a subtype of T.
      Parameters:
      type - The type of the item to be wrapped in the Var.
      item - The item to be wrapped in the Var. It must not be null and it must be a subtype of the specified type.
      Returns:
      A non-nullable Var instance containing the item.

    • valsOf

      public <T> Vals<T> valsOf(Class<T> type)
      Description copied from interface: SproutsFactory
      A factory method which creates an empty Vals instance dedicated to hold properties storing non-nullable items of the specified type.
      Specified by:
      valsOf in interface SproutsFactory
      Type Parameters:
      T - The type of the items to be wrapped in the Vals.
      Parameters:
      type - The type of the items to be wrapped in the Vals. It must not be null.
      Returns:
      A Vals instance that can hold items of the specified type.

    • valsOf

      public <T> Vals<T> valsOf(Class<T> type, Val<T>... vars)
      Description copied from interface: SproutsFactory
      This factory method creates a Vals instance from a type class and an array of Val properties, each wrapping a non-nullable item of the specified type. A property list can store multiple Val properties wrapping non-nullable items of the specified type.
      Specified by:
      valsOf in interface SproutsFactory
      Type Parameters:
      T - The non-nullable type of the items to be wrapped in the Vals.
      Parameters:
      type - The type of the items to be wrapped in the Vals. It must not be null.
      vars - An array of Val properties to be wrapped in the Vals. Properties in the array cannot be null, and their items also cannot be null.
      Returns:
      A Vals instance that can hold the specified items of the given type.

    • valsOf

      public <T> Vals<T> valsOf(Val<T> first, Val<T>... rest)
      Description copied from interface: SproutsFactory
      A factory method for creating a Vals property list from one or more Val properties, which are all instances of the same type and may not be null. The Vals.type() is inferred from the type of the first properties Maybe.type(). If you want to create a property list which can hold nulls, use SproutsFactory.valsOfNullable(Class, Val...) instead of this method.
      Specified by:
      valsOf in interface SproutsFactory
      Type Parameters:
      T - The type of the items to be wrapped in the Vals.
      Parameters:
      first - The first Val to be wrapped in the Vals. It must not be null and it must not contain a null item (Val.allowsNull() must return false).
      rest - Additional Val items to be wrapped in the Vals. They are not permitted to be null, and they also may not contain null items (Val.allowsNull() must return false).
      Returns:
      A Vals instance that can hold the specified items of the inferred type.

    • valsOf

      public <T> Vals<T> valsOf(T first, T... rest)
      Description copied from interface: SproutsFactory
      A factory method for creating a Vals property list from one or more items, which are all instances of the same type and may not be null. The Vals.type() is inferred from the type of the first item. If you want to create a property list which can hold nulls, use SproutsFactory.valsOfNullable(Class, Object...) instead of this method.
      Specified by:
      valsOf in interface SproutsFactory
      Type Parameters:
      T - The type of the items to be wrapped in the Vals.
      Parameters:
      first - The first item to be wrapped in the Vals. It must not be null.
      rest - Additional items to be wrapped in the Vals. They can be null.
      Returns:
      A Vals instance that can hold the specified items of the inferred type.

    • valsOf

      public <T> Vals<T> valsOf(Class<T> type, T... items)
      Description copied from interface: SproutsFactory
      A factory method for creating a Vals property list from a type class and an array of items, which are all instances of the given type and may not be null. The resulting Vals can hold multiple values of the specified type. If you want to create a property list which can hold null references, use SproutsFactory.valsOfNullable(Class, Object...) instead of this method.
      Specified by:
      valsOf in interface SproutsFactory
      Type Parameters:
      T - The type of the items to be wrapped in the Vals.
      Parameters:
      type - The type class of the items to be wrapped in the Vals. It must not be null.
      items - An array of items to be wrapped in the Vals. The items themselves cannot be null.
      Returns:
      A Vals instance that can hold the specified items of the given type.

    • valsOf

      public <T> Vals<T> valsOf(Class<T> type, Iterable<Val<T>> properties)
      Description copied from interface: SproutsFactory
      Creates a Vals property list from a type class and an iterable of Val properties, each wrapping a non-nullable item of the specified type. A property list can store multiple Val properties wrapping non-nullable items of the specified type.
      Specified by:
      valsOf in interface SproutsFactory
      Type Parameters:
      T - The non-nullable type of the items to be wrapped in the Vals.
      Parameters:
      type - The type of the items to be wrapped in the Vals. It must not be null.
      properties - An iterable of Val properties to be wrapped in the Vals. Properties in the iterable cannot be null, and their items cannot be null.
      Returns:
      A Vals instance that can hold the specified items of the given type.

    • valsOf

      public <T> Vals<T> valsOf(Class<T> type, Vals<T> vals)
      Description copied from interface: SproutsFactory
      Creates a Vals property list of the given type with the specified items from another Vals instance. A property list can store multiple Val properties wrapping non-nullable items of the specified type.
      Specified by:
      valsOf in interface SproutsFactory
      Type Parameters:
      T - The non-nullable type of the items to be wrapped in the Vals.
      Parameters:
      type - The type of the items to be wrapped in the Vals. It must not be null.
      vals - The items to be wrapped in the Vals. Items in properties of the Vals are not permitted to be null.
      Returns:
      A Vals instance that can hold the specified items of the given (non-nullable) type.

    • valsOfNullable

      public <T> Vals<@Nullable T> valsOfNullable(Class<T> type, Val<@Nullable T>... vals)
      Description copied from interface: SproutsFactory
      Creates a Vals property list of Val properties from a type class and an array of properties, holding nullable items which are all instances of the given type or null. So every Val property in the resulting Vals is permitted to hold a null reference and may therefore report Maybe.isEmpty() as true.
      Specified by:
      valsOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the items to be wrapped in the Vals.
      Parameters:
      type - The type class of the nullable items to be wrapped in the Vals. It must not be null.
      vals - An array of Vals to be wrapped in the Vals. The properties themselves cannot be null, but the items they hold can be null.
      Returns:
      A Vals instance that can hold the specified items of the given type, including null values.

    • valsOfNullable

      public <T> Vals<@Nullable T> valsOfNullable(Class<T> type)
      Description copied from interface: SproutsFactory
      This factory method instantiates an empty Vals instance from a type class of a nullable type T. The resulting Vals can hold multiple properties wrapping either instances of the specified type T or null references. If you want to create a property list which can never hold nulls, use SproutsFactory.valsOf(Class) instead of this method.
      Specified by:
      valsOfNullable in interface SproutsFactory
      Type Parameters:
      T - The nullable type of the items to be wrapped in the Vals.
      Parameters:
      type - The type class of the nullable items to be wrapped in the Vals. It must not be null.
      Returns:
      A Vals instance that can hold items of the specified nullable type.

    • valsOfNullable

      public <T> Vals<@Nullable T> valsOfNullable(Class<T> type, @Nullable T... items)
      Description copied from interface: SproutsFactory
      Creates a Vals property list of Val properties from a type class and an array of items, which are all instances of the given type or null. Every Val property in the resulting Vals is permitted to hold a null reference, in which case it will report Maybe.isEmpty() as true. If you want to create a property list which can never hold nulls, use SproutsFactory.valsOf(Class, Object...) instead of this method.
      Specified by:
      valsOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the items to be wrapped in the Vals.
      Parameters:
      type - The type class of the nullable items to be wrapped in the Vals. It must not be null.
      items - An array of items to be wrapped in the Vals. The items themselves can be null, but the array is not permitted to be null itself.
      Returns:
      A Vals instance that can hold the specified items of the given type, including null values.

    • valsOfNullable

      public <T> Vals<@Nullable T> valsOfNullable(Val<@Nullable T> first, Val<@Nullable T>... rest)
      Description copied from interface: SproutsFactory
      Creates a Vals property list of Val properties from one or more Val properties, which are all instances of the same type and may hold null values. The Vals.type() is inferred from the type of the first properties Maybe.type(). If you want to create a property list which can never hold nulls, use SproutsFactory.valsOf(Class, Val...) instead of this method.
      Specified by:
      valsOfNullable in interface SproutsFactory
      Type Parameters:
      T - The type of the items to be wrapped in the Vals.
      Parameters:
      first - The first Val to be wrapped in the Vals. It must not be null and it may contain a null item (Val.allowsNull() may return true).
      rest - Additional Val items to be wrapped in the Vals. They are not permitted to be null, but they may contain null items (Val.allowsNull() may return true).
      Returns:
      A Vals instance that can hold the specified items of the inferred type, including nullable values.

    • valsOfNullable

      public <T> Vals<@Nullable T> valsOfNullable(Class<T> type, Vals<@Nullable T> vals)
      Description copied from interface: SproutsFactory
      This factory method creates a Vals property list from a type class representing a nullable type T and another Vals instance, which contains nullable items being compatible with the specified type T. A property list can store multiple Val properties wrapping nullable items of the specified type.
      Specified by:
      valsOfNullable in interface SproutsFactory
      Type Parameters:
      T - The nullable type of the items to be wrapped in the Vals.
      Parameters:
      type - The type of the items to be wrapped in the Vals. It must not be null.
      vals - The items to be wrapped in the Vals. Items in properties of the Vals are permitted to be null.
      Returns:
      A Vals instance that can hold the specified items of the given (nullable) type.

    • varsOfNullable

      public <T> Vars<T> varsOfNullable(Class<T> type, Iterable<Var<T>> vars)
      Description copied from interface: SproutsFactory
      Creates a list of nullable properties from the supplied type and iterable of values. This factory method requires that the type be specified because the compiler cannot infer the type from a potentially empty iterable.
      Specified by:
      varsOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      type - the type of the properties.
      vars - the iterable of values.
      Returns:
      a new Vars instance.

    • tupleOf

      public <T> Tuple<T> tupleOf(Class<T> type, Maybe<T>... maybes)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of non-nullable items from the supplied type and vararg values. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty vararg array.
      Specified by:
      tupleOf in interface SproutsFactory
      Type Parameters:
      T - the type of the items in the tuple.
      Parameters:
      type - the type of the items in the tuple.
      maybes - the items to add to the new Tuple instance.
      Returns:
      a new Tuple instance.

    • tupleOf

      public <T> Tuple<T> tupleOf(Class<T> type)
      Description copied from interface: SproutsFactory
      Creates an empty tuple of non-nullable items from the supplied type. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty vararg array.
      Specified by:
      tupleOf in interface SproutsFactory
      Type Parameters:
      T - the type of the items in the tuple.
      Parameters:
      type - the type of the items in the tuple. This is used to check if the item is of the correct type.
      Returns:
      a new Tuple instance.

    • tupleOf

      public <T> Tuple<T> tupleOf(T first, T... rest)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of non-nullable items from one or more non-null items. At least one non-null item must be provided to this factory method.
      Specified by:
      tupleOf in interface SproutsFactory
      Type Parameters:
      T - the type of the values.
      Parameters:
      first - the first value to add to the new Tuple instance.
      rest - the remaining values to add to the new Tuple instance.
      Returns:
      a new Tuple instance.

    • tupleOf

      public Tuple<Float> tupleOf(float... floats)
      Description copied from interface: SproutsFactory
      Creates an immutable, non-nullable Tuple<Float> from a primitive array of floats. The returned tuple will contain the floats as a single dense array of primitives.
      Note that in order to guarantee immutability, the array of floats is copied.
      Specified by:
      tupleOf in interface SproutsFactory
      Parameters:
      floats - The floats to use as a basis for the new tuple.
      Returns:
      a new Tuple instance backed by a single primitive array of floats.

    • tupleOf

      public Tuple<Double> tupleOf(double... doubles)
      Description copied from interface: SproutsFactory
      Creates an immutable, non-nullable Tuple<Double> from a primitive array of doubles. The returned tuple will contain the doubles as a single dense array of primitives.
      Note that in order to guarantee immutability, the array of doubles is copied.
      Specified by:
      tupleOf in interface SproutsFactory
      Parameters:
      doubles - The doubles to use as a basis for the new tuple.
      Returns:
      a new Tuple instance backed by a single primitive array of doubles.

    • tupleOf

      public Tuple<Integer> tupleOf(int... ints)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of non-nullable items from a primitive array of integers. The returned tuple will contain the integers as a single dense array of primitives.
      Note that in order to guarantee immutability, the array of integers is copied.
      Specified by:
      tupleOf in interface SproutsFactory
      Parameters:
      ints - The integers to use as a basis for the new tuple.
      Returns:
      a new Tuple instance backed by a single primitive array of integers.

    • tupleOf

      public Tuple<Byte> tupleOf(byte... bytes)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of non-nullable items from a primitive array of bytes. The returned tuple will contain the bytes as a single dense array of primitives.
      Note that in order to guarantee immutability, the array of bytes is copied.
      Specified by:
      tupleOf in interface SproutsFactory
      Parameters:
      bytes - The bytes to use as a basis for the new tuple.
      Returns:
      a new Tuple instance backed by a single primitive array of bytes.

    • tupleOf

      public Tuple<Long> tupleOf(long... longs)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of non-nullable items from a primitive array of longs. The returned tuple will contain the longs as a single dense array of primitives.
      Note that in order to guarantee immutability, the array of longs is copied.
      Specified by:
      tupleOf in interface SproutsFactory
      Parameters:
      longs - The longs to use as a basis for the new tuple.
      Returns:
      a new Tuple instance backed by a single primitive array of longs.

    • tupleOf

      public <T> Tuple<T> tupleOf(Class<T> type, T... items)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of non-nullable items from the supplied type and values. This factory method requires the type to be specified, because the compiler cannot infer the type from the values.
      Specified by:
      tupleOf in interface SproutsFactory
      Type Parameters:
      T - the type of the values.
      Parameters:
      type - the type of the items in the tuple.
      items - the values to be wrapped by items and then added to the new Tuple instance. The values may not be null.
      Returns:
      a new Tuple instance.

    • tupleOf

      public <T> Tuple<T> tupleOf(Class<T> type, Iterable<T> iterable)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of non-nullable items from the supplied type and iterable of values. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty iterable.
      Specified by:
      tupleOf in interface SproutsFactory
      Type Parameters:
      T - the type of the items in the tuple.
      Parameters:
      type - the type of the items in the tuple.
      iterable - the iterable of values.
      Returns:
      a new Tuple instance.

    • tupleOfNullable

      public <T> Tuple<@Nullable T> tupleOfNullable(Class<T> type)
      Description copied from interface: SproutsFactory
      Creates an empty tuple of nullable items from the supplied type. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty vararg array.
      Specified by:
      tupleOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the items in the tuple.
      Parameters:
      type - the type of the items in the tuple. This is used to check if the item is of the correct type.
      Returns:
      a new Tuple instance.

    • tupleOfNullable

      public <T> Tuple<@Nullable T> tupleOfNullable(Class<T> type, @Nullable T... values)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of nullable items from the supplied type and values. This factory method requires the type to be specified, because the compiler cannot infer the type from the null values.
      Specified by:
      tupleOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the values.
      Parameters:
      type - the type of the items in the tuple.
      values - The items to be stored by the new Tuple instance. The values may be null.
      Returns:
      a new Tuple instance.

    • tupleOfNullable

      public <T> Tuple<@Nullable T> tupleOfNullable(Class<T> type, Iterable<@Nullable T> iterable)
      Description copied from interface: SproutsFactory
      Creates an immutable tuple of nullable items from the supplied type and iterable of values. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty iterable.
      Specified by:
      tupleOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the items in the tuple.
      Parameters:
      type - the type of the items in the tuple.
      iterable - the iterable of values.
      Returns:
      a new Tuple instance.

    • associationOf

      public <K, V> Association<K,V> associationOf(Class<K> keyType, Class<V> valueType)
      Description copied from interface: SproutsFactory
      Creates a new association between keys and values with the given key and value types. An association knows the types of its keys and values, and so you can only put keys and values of the defined types into the association. This creates an empty association primed without any order of their key-value pairs.
      Specified by:
      associationOf in interface SproutsFactory
      Type Parameters:
      K - The type of the keys in the association, which must be immutable.
      V - The type of the values in the association, which should be immutable.
      Parameters:
      keyType - The type of the keys in the association.
      valueType - The type of the values in the association.
      Returns:
      A new association between keys and values.

    • associationOfLinked

      public <K, V> Association<K,V> associationOfLinked(Class<K> keyType, Class<V> valueType)
      Description copied from interface: SproutsFactory
      Creates a new linked association between keys and values with the given key and value types, where the order of key-value pairs in this type of association is based on the order in which the pairs are added to the association. An association always knows the types of its keys and values, and so you can only put keys and values of the defined types into the association.
      Specified by:
      associationOfLinked in interface SproutsFactory
      Type Parameters:
      K - The type of the keys in the association, which must be immutable.
      V - The type of the values in the association, which should be immutable.
      Parameters:
      keyType - The type of the keys in the association.
      valueType - The type of the values in the association.
      Returns:
      A new linked association between keys and values, where the order of key-value pairs is preserved in the order they are added.

    • associationOfSorted

      public <K, V> Association<K,V> associationOfSorted(Class<K> keyType, Class<V> valueType, Comparator<K> comparator)
      Description copied from interface: SproutsFactory
      Creates a new association between keys and values with the given key and value types, where the key-value pairs are sorted using the supplied comparator. An association knows the types of its keys and values, and so you can only put keys and values of the defined types into the association.
      Specified by:
      associationOfSorted in interface SproutsFactory
      Type Parameters:
      K - The type of the keys in the association, which must be immutable.
      V - The type of the values in the association, which should be immutable.
      Parameters:
      keyType - The type of the keys in the association.
      valueType - The type of the values in the association.
      comparator - The comparator to use for sorting the keys in the association.
      Returns:
      A new sorted association between keys and values.

    • associationOfSorted

      public <K extends Comparable<K>, V> Association<K,V> associationOfSorted(Class<K> keyType, Class<V> valueType)
      Description copied from interface: SproutsFactory
      Creates a new association between keys and values with the given key and value types, where the keys are sorted in natural order. An association knows the types of its keys and values, and so you can only put keys and values of the defined types into the association.
      Specified by:
      associationOfSorted in interface SproutsFactory
      Type Parameters:
      K - The type of the keys in the association, which must be immutable.
      V - The type of the values in the association, which should be immutable.
      Parameters:
      keyType - The type of the keys in the association.
      valueType - The type of the values in the association.
      Returns:
      A new sorted association between keys and values.

    • valueSetOf

      public <E> ValueSet<E> valueSetOf(Class<E> type)
      Description copied from interface: SproutsFactory
      Creates a new value set specifically for holding elements of the supplied type. A value set knows the types of its elements, and so you can only add elements which are of the same type or a subtype of the type of the value set.
      Specified by:
      valueSetOf in interface SproutsFactory
      Type Parameters:
      E - The type of the elements in the value set, which must be an immutable value type.
      Parameters:
      type - The type of the elements in the value set.
      Returns:
      A new value set specific to the given element type.

    • valueSetOfLinked

      public <E> ValueSet<E> valueSetOfLinked(Class<E> type)
      Description copied from interface: SproutsFactory
      Creates a new value set specifically for holding elements of the supplied type, and where the order of the elements is defined by the insertion order. Which means that during iteration over the value set, the elements will be returned in the order they were added. A value set knows the types of its elements, and so you can only add elements which are of the same type or a subtype of the type of the value set.
      Specified by:
      valueSetOfLinked in interface SproutsFactory
      Type Parameters:
      E - The type of the elements in the value set, which must be an immutable value type.
      Parameters:
      type - The type of the elements in the value set.
      Returns:
      A new linked value set specific to the given element type.

    • valueSetOfSorted

      public <E> ValueSet<E> valueSetOfSorted(Class<E> type, Comparator<E> comparator)
      Description copied from interface: SproutsFactory
      Creates a new value set specifically for holding elements of the supplied type, but with an explicit order defined by the supplied comparator. A value set knows the types of its elements and values, and so you can only add elements which are of the same type or a subtype of the type of the value set.
      Here is an example demonstrating how this method may be used to create a set with string elements sorted by their length:
      
    ValueSet.ofSorted(
       String.class,
       Comparator.comparing(String::length)
    );
      Specified by:
      valueSetOfSorted in interface SproutsFactory
      Type Parameters:
      E - The type of the elements in the value set, which must be an immutable value type.
      Parameters:
      type - The type of the elements in the value set.
      comparator - The comparator to use for sorting the elements in the value set.
      Returns:
      A new sorted value set specific to the given element type.

    • valueSetOfSorted

      public <E extends Comparable<? super E>> ValueSet<E> valueSetOfSorted(Class<E> type)
      Description copied from interface: SproutsFactory
      Creates a new value set specifically for holding elements of the supplied type, elements are sorted based on the natural ordering of the elements (which are expected to implement Comparable). A value set knows the types of its elements and values, and so you can only add elements which are of the same type or a subtype of the specified element type of the value set.
      Specified by:
      valueSetOfSorted in interface SproutsFactory
      Type Parameters:
      E - The type of the elements in the value set, which must be an immutable value type.
      Parameters:
      type - The type of the elements in the value set.
      Returns:
      A new sorted value set specific to the given element type.

    • varsOf

      public <T> Vars<T> varsOf(Class<T> type, Var<T>... vars)
      Description copied from interface: SproutsFactory
      Creates a list of non-nullable properties from the supplied type and vararg values. This factory method requires that the type be specified because the compiler cannot infer the type from a potentially empty vararg array.
      Specified by:
      varsOf in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      type - the type of the properties.
      vars - the properties to add to the new Vars instance.
      Returns:
      a new Vars instance.

    • varsOf

      public <T> Vars<T> varsOf(Class<T> type)
      Description copied from interface: SproutsFactory
      Creates an empty list of non-nullable properties from the supplied type. This factory method requires that the type be specified because the compiler cannot infer the type from a potentially empty vararg array.
      Specified by:
      varsOf in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      type - the type of the properties. This is used to check if the item is of the correct type.
      Returns:
      a new Vars instance.

    • varsOf

      public <T> Vars<T> varsOf(Var<T> first, Var<T>... rest)
      Description copied from interface: SproutsFactory
      Creates a list of non-nullable properties from one or more non-nullable properties.
      Specified by:
      varsOf in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      first - the first property to add to the new Vars instance.
      rest - the remaining properties to add to the new Vars instance.
      Returns:
      a new Vars instance.

    • varsOf

      public <T> Vars<T> varsOf(T first, T... rest)
      Description copied from interface: SproutsFactory
      Creates a list of non-nullable properties from one or more non-null values.
      Specified by:
      varsOf in interface SproutsFactory
      Type Parameters:
      T - the type of the values.
      Parameters:
      first - the first value to add to the new Vars instance.
      rest - the remaining values to add to the new Vars instance.
      Returns:
      a new Vars instance.

    • varsOf

      public <T> Vars<T> varsOf(Class<T> type, T... items)
      Description copied from interface: SproutsFactory
      Creates a list of non-nullable properties from the supplied type and values. This factory method requires that the type be specified because the compiler cannot infer the type from the values.
      Specified by:
      varsOf in interface SproutsFactory
      Type Parameters:
      T - the type of the values.
      Parameters:
      type - the type of the properties.
      items - the values to be wrapped by properties and then added to the new Vars instance. The values may not be null.
      Returns:
      a new Vars instance.

    • varsOf

      public <T> Vars<T> varsOf(Class<T> type, Iterable<Var<T>> vars)
      Description copied from interface: SproutsFactory
      Creates a list of non-nullable properties from the supplied type and iterable of values. This factory method requires that the type be specified because the compiler cannot infer the type from a potentially empty iterable.
      Specified by:
      varsOf in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      type - the type of the properties.
      vars - the iterable of values.
      Returns:
      a new Vars instance.

    • varsOfNullable

      public <T> Vars<@Nullable T> varsOfNullable(Class<T> type, Var<@Nullable T>... vars)
      Description copied from interface: SproutsFactory
      Creates a list of nullable properties from the supplied type and varargs properties. This factory method requires that the type be specified because the compiler cannot infer the type from the null values.
      Specified by:
      varsOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      type - the type of the properties.
      vars - the properties to add to the new Vars instance. The properties may be nullable properties, but they may not be null themselves.
      Returns:
      a new Vars instance.

    • varsOfNullable

      public <T> Vars<@Nullable T> varsOfNullable(Class<T> type)
      Description copied from interface: SproutsFactory
      Creates an empty list of nullable properties from the supplied type. This factory method requires that the type be specified because the compiler cannot infer the type from a potentially empty vararg array.
      Specified by:
      varsOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      type - the type of the properties. This is used to check if the item is of the correct type.
      Returns:
      a new Vars instance.

    • varsOfNullable

      public <T> Vars<@Nullable T> varsOfNullable(Class<T> type, @Nullable T... values)
      Description copied from interface: SproutsFactory
      Creates a list of nullable properties from the supplied type and values. This factory method requires that the type be specified because the compiler cannot infer the type from the null values.
      Specified by:
      varsOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the values.
      Parameters:
      type - the type of the properties.
      values - the values to be wrapped by properties and then added to the new Vars instance. The values may be null.
      Returns:
      a new Vars instance.

    • varsOfNullable

      public <T> Vars<@Nullable T> varsOfNullable(Var<@Nullable T> first, Var<@Nullable T>... rest)
      Description copied from interface: SproutsFactory
      Creates a list of nullable properties from the supplied properties.
      Specified by:
      varsOfNullable in interface SproutsFactory
      Type Parameters:
      T - the type of the properties.
      Parameters:
      first - the first property to add to the new Vars instance.
      rest - the remaining properties to add to the new Vars instance.
      Returns:
      a new Vars instance.

    • defaultId

      public String defaultId()
      Description copied from interface: SproutsFactory
      The default id for properties which do not have an id explicitly specified. The id of a property is used to identify it in the system or as part of a view model and convert it into other data formats like key/value based data stores.
      Specified by:
      defaultId in interface SproutsFactory
      Returns:
      The default id for properties which do not have an id explicitly specified. This must never return null and it is recommended to be a constant or cached object due to this method being called frequently.

    • idPattern

      public Pattern idPattern()
      Description copied from interface: SproutsFactory
      The regex Pattern used to validate property ids. All ids must match this pattern.
      Specified by:
      idPattern in interface SproutsFactory
      Returns:
      The regex Pattern used to validate property ids. This must never return null and it is recommended to be a constant or cached object due to this method being called frequently.

    • defaultChannel

      public Channel defaultChannel()
      Description copied from interface: SproutsFactory
      The default channel used for change events. This channel is used to give events a chanel when no channel is explicitly specified.
      Specified by:
      defaultChannel in interface SproutsFactory
      Returns:
      The default channel used for change events. This must never return null and it is recommended to be a constant or cached object due to this method being called frequently.

    • defaultObservableChannel

      public Channel defaultObservableChannel()
      Description copied from interface: SproutsFactory
      The default channel used for Observable events, registered through the Observable.subscribe(Observer) method.
      Specified by:
      defaultObservableChannel in interface SproutsFactory
      Returns:
      The default channel used for change events. This must never return null and it is recommended to be a constant or cached object due to this method being called frequently.

    • loggingMarker

      public org.slf4j.Marker loggingMarker()
      Description copied from interface: SproutsFactory
      Many features in Sprouts are designed to preserve the control flow of your application by catching exceptions and then logging them. This typically happens in a Result or Var property when a user Action fails...
      This method configures a Slf4j Marker to be used by Sprouts at all places where logging is being done. You can then use this marker to identify and filter these log entries.
      Specified by:
      loggingMarker in interface SproutsFactory
      Returns:
      A constant which serves as a sort of logging channel used on all logging sites of the sprouts library.

    • setLoggingMarker

      public void setLoggingMarker(org.slf4j.Marker marker)
      You may want to set this to filter logging done by Sprouts, which is typically a type of log that is contains exceptions caused by bugs and failed sanity checks. So you may want to filter that using this marker...
      Parameters:
      marker - The Slf4j Marker constant which should be used for all logging that occurs in Sprouts.