Package sprouts.impl

Interface SproutsFactory

All Known Implementing Classes:
Sprouts
public interface SproutsFactory
Creates instances of the various types of the Sprouts library, like its persistent data structures (see Tuple, Association, ValueSet) or reactive properties (Val, Var, Vals, Vars).
This interface allows you to plug in your own implementations of the Sprouts properties and collections, through the Sprouts.setFactory(SproutsFactory) method.

All other (static) factory methods on the various Sprouts types delegate to this API for instantiation. So please be careful when plugging a custom implementation!

  • 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.
    Pattern
    idPattern()
    The regex Pattern used to validate property ids.
    <T extends @Nullable Object, B extends @NonNull Object>
    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 extends @Nullable Object, B extends @NonNull Object>
    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 extends @Nullable Object, B extends @Nullable Object>
    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 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.
    default <T> Maybe<T>
    maybeOf(Maybe<T> toBeCopied)
    Creates a non-empty Maybe copy from the supplied Maybe.
    default <T> Maybe<T>
    maybeOf(T item)
    Creates a Maybe instance from a non-nullable item.
    default <T> Maybe<@Nullable T>
    maybeOfNull(Class<T> type)
    Creates a Maybe instance of the given type with a null item.
    default <T> Maybe<@Nullable T>
    maybeOfNullable(Class<T> type, @Nullable T item)
    Creates a nullable Maybe instance of the given type with the specified item.
    default <T extends @Nullable Object>
    Maybe<@Nullable T>
    maybeOfNullable(Maybe<T> toBeCopied)
    Creates a potentially empty Maybe copy from the supplied Maybe, which may or may not contain a null item.
    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.
    default <T> Tuple<T>
    tupleOf(Maybe<T> first, Maybe<T>... rest)
    Creates an immutable tuple of non-nullable items from one or more non-nullable items wrapped by Maybe properties.
    <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... items)
    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.
    default <T> Tuple<@Nullable T>
    tupleOfNullable(Class<T> type, Maybe<@Nullable T>... maybes)
    Creates an immutable tuple of nullable items from the supplied type and varargs items.
    default <T> Tuple<@Nullable T>
    tupleOfNullable(Maybe<@Nullable T> first, Maybe<@Nullable T>... rest)
    Creates an immutable tuple of nullable items from the supplied items.
    <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 extends @Nullable Object>
    Val<@Nullable T>
    valOfNullable(Val<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<@Nullable T>
    varOfNull(Class<T> type)
    Creates an empty Var instance (storing a null item) of the given type.
    <T> Var<@Nullable 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<@Nullable T>
    varsOfNullable(Class<T> type, Iterable<Var<@Nullable 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 extends @Nullable Object, U extends @Nullable Object>
    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 extends @Nullable Object>
    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 extends @Nullable Object>
    Viewables<T>
    viewOf(Vals<T> source)
    Creates a Viewables instance of the given Vals.
    <T extends @Nullable Object, U extends @Nullable Object>
    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 extends @Nullable Object, 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 extends @Nullable Object, U extends @Nullable Object>
    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.

  • Method Details

    • delegateOf

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

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

      Event event()
      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.
      Returns:
      A new Event instance with the default executor.

    • eventOf

      Event eventOf(Event.Executor executor)
      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.
      Parameters:
      executor - The executor to be used for the event. It must not be null.
      Returns:
      A new Event instance with the specified executor.

    • maybeOfNullable

      default <T> Maybe<@Nullable T> maybeOfNullable(Class<T> type, @Nullable T item)
      Creates a nullable Maybe instance of the given type with the specified item.
      Type Parameters:
      T - The type of the item to be wrapped in the Maybe.
      Parameters:
      type - The type of the item to be wrapped in the Maybe. It must not be null.
      item - The item to be wrapped in the Maybe. It can be null.
      Returns:
      A Maybe instance containing the item, or an empty Maybe if the item is null.

    • maybeOfNull

      default <T> Maybe<@Nullable T> maybeOfNull(Class<T> type)
      Creates a Maybe instance of the given type with a null item. The Maybe.isEmpty() method of the returned instance will always return true, indicating that the Maybe does not contain a value.
      Type Parameters:
      T - The type of the item to be wrapped in the Maybe.
      Parameters:
      type - The type of the item to be wrapped in the Maybe. It must not be null.
      Returns:
      A Maybe instance containing a null item.

    • maybeOf

      default <T> Maybe<T> maybeOf(T item)
      Creates a Maybe instance from a non-nullable item. The Maybe.isPresent() method of the returned instance will always return true, indicating that the Maybe contains a value.
      Type Parameters:
      T - The type of the item to be wrapped in the Maybe.
      Parameters:
      item - The item to be wrapped in the Maybe. It must not be null.
      Returns:
      A Maybe instance containing the item.

    • maybeOf

      default <T> Maybe<T> maybeOf(Maybe<T> toBeCopied)
      Creates a non-empty Maybe copy from the supplied Maybe. The supplied Maybe 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 Maybe contains a value. The returned instance is effectively an immutable copy of the supplied Maybe.
      Type Parameters:
      T - The type of the item to be wrapped in the Maybe.
      Parameters:
      toBeCopied - The Maybe instance to be copied. It must not be null and it also must not contain a null value.
      Returns:
      A new Maybe instance containing the value from the given Maybe.

    • maybeOfNullable

      default <T extends @Nullable Object> Maybe<@Nullable T> maybeOfNullable(Maybe<T> toBeCopied)
      Creates a potentially empty Maybe copy from the supplied Maybe, which may or may not contain a null item. The returned instance is effectively an immutable copy of the supplied Maybe.
      Type Parameters:
      T - The type of the item to be wrapped in the Maybe.
      Parameters:
      toBeCopied - The Maybe instance to be copied.
      Returns:
      A new Maybe instance containing the value from the given Maybe, or an empty Maybe if the value is null.
      Throws:
      NullPointerException - if toBeCopied is null. (However, the item in the supplied Maybe can be null.)

    • valOfNullable

      <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. The resulting property may or may not be empty (see Maybe.isEmpty().
      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.
      Throws:
      NullPointerException - if type is null.

    • valOfNull

      <T> Val<@Nullable T> valOfNull(Class<T> type)
      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.
      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

      <T> Val<T> valOf(T item)
      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.
      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.
      Throws:
      NullPointerException - if item is null.

    • valOf

      <T> Val<T> valOf(Val<T> toBeCopied)
      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.
      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.
      Throws:
      NullPointerException - if toBeCopied is null.

    • valOfNullable

      <T extends @Nullable Object> Val<@Nullable T> valOfNullable(Val<T> toBeCopied)
      Creates a nullable Val instance of the given type by copying the value from another Val.
      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.
      Throws:
      NullPointerException - if toBeCopied is null.

    • viewOf

      <T extends @Nullable Object> Viewable<T> viewOf(Val<T> source)
      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.
      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.
      Throws:
      NullPointerException - if source is null.

    • viewOf

      <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. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • viewOfNullable

      <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. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • viewOf

      <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. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • viewOfNullable

      <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. You may register observers on the resulting viewable to receive updates when the values of either of the two Val instances change.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • viewOf

      <T extends @Nullable Object> Viewables<T> viewOf(Vals<T> source)
      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.
      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.
      Throws:
      NullPointerException - if source is null.

    • viewOf

      <T extends @Nullable Object, 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. 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.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • viewOf

      <T extends @Nullable Object, U extends @Nullable Object> 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.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • viewOf

      <T extends @Nullable Object, U extends @Nullable Object> 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. 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.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • viewOfNullable

      <T extends @Nullable Object, U extends @Nullable Object> 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.
      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.
      Throws:
      NullPointerException - if any of the supplied parameters are null.

    • lensOf

      <T extends @Nullable Object, B extends @NonNull Object> 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. We recommend using record types for T and B to reliably ensure value semantics.
      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

      <T extends @Nullable Object, B extends @NonNull Object> 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. If you want to create a lens property which can store null values, use the 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.
      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

      <T extends @Nullable Object, B extends @Nullable Object> 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 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.

      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

      <T> Var<@Nullable 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. 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 varOf(Class, Object) instead of this method.
      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.
      Throws:
      NullPointerException - if type is null.

    • varOfNull

      <T> Var<@Nullable T> varOfNull(Class<T> type)
      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 varOf(Class, Object) instead of this method.
      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.
      Throws:
      NullPointerException - if type is null.

    • varOf

      <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.
      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.
      Throws:
      NullPointerException - if item is null.

    • varOf

      <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. 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.
      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.
      Throws:
      NullPointerException - if type or item is null.

    • valsOf

      <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.
      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.
      Throws:
      NullPointerException - if type is null.

    • valsOf

      <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. A property list can store multiple Val properties wrapping non-nullable items of the specified type.
      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.
      Throws:
      NullPointerException - if type or vars is null.

    • valsOf

      <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. 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 valsOfNullable(Class, Val...) instead of this method.
      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.
      Throws:
      NullPointerException - if first or any item in rest is null.

    • valsOf

      <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. 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 valsOfNullable(Class, Object...) instead of this method.
      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.
      Throws:
      NullPointerException - if first or rest is null, or if any item in rest is null.

    • valsOf

      <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. 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 valsOfNullable(Class, Object...) instead of this method.
      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.
      Throws:
      NullPointerException - if type or items is null.

    • valsOf

      <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. A property list can store multiple Val properties wrapping non-nullable items of the specified type.
      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.
      Throws:
      NullPointerException - if type or properties is null.

    • valsOf

      <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. A property list can store multiple Val properties wrapping non-nullable items of the specified type.
      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.
      Throws:
      NullPointerException - if type or vals is null.

    • valsOfNullable

      <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. 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 valsOf(Class) instead of this method.
      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.
      Throws:
      NullPointerException - if type is null.

    • valsOfNullable

      <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. So every Val property in the resulting Vals is permitted to hold a null reference and may therefore report Maybe.isEmpty() as true.
      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.
      Throws:
      NullPointerException - if type or vals is null, or if any of the Val properties in vals array is null. (Note that the items in the Val properties are permitted to be null!)

    • valsOfNullable

      <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. 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 valsOf(Class, Object...) instead of this method.
      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.
      Throws:
      NullPointerException - if type or the items array is null.

    • valsOfNullable

      <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. 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 valsOf(Class, Val...) instead of this method.
      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.
      Throws:
      NullPointerException - if first or rest is null, as well as if any item in rest is null.

    • valsOfNullable

      <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. A property list can store multiple Val properties wrapping nullable items of the specified type.
      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.
      Throws:
      NullPointerException - if type or vals is null.

    • varsOf

      <T> Vars<T> varsOf(Class<T> type, Var<T>... vars)
      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.
      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.
      Throws:
      NullPointerException - if type is null, or vars is null.
      IllegalArgumentException - if any property allows null.

    • varsOf

      <T> Vars<T> varsOf(Class<T> type)
      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.
      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.
      Throws:
      NullPointerException - if type is null.

    • varsOf

      <T> Vars<T> varsOf(Var<T> first, Var<T>... rest)
      Creates a list of non-nullable properties from one or more non-nullable properties.
      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.
      Throws:
      NullPointerException - if first is null, or rest is null.
      IllegalArgumentException - if any property allows null.

    • varsOf

      <T> Vars<T> varsOf(T first, T... rest)
      Creates a list of non-nullable properties from one or more non-null values.
      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.
      Throws:
      NullPointerException - if first is null, or rest is null.
      IllegalArgumentException - if any value in rest is null.

    • varsOf

      <T> Vars<T> varsOf(Class<T> type, T... items)
      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.
      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.
      Throws:
      NullPointerException - if type is null, or items is null.

    • varsOf

      <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. This factory method requires that the type be specified because the compiler cannot infer the type from a potentially empty iterable.
      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.
      Throws:
      NullPointerException - if type is null, or vars is null.
      IllegalArgumentException - if any property in vars allows null.

    • varsOfNullable

      <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. This factory method requires that the type be specified because the compiler cannot infer the type from the null values.
      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.
      Throws:
      NullPointerException - if type is null, or vars is null.

    • varsOfNullable

      <T> Vars<@Nullable T> varsOfNullable(Class<T> type)
      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.
      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.
      Throws:
      NullPointerException - if type is null.

    • varsOfNullable

      <T> Vars<@Nullable T> varsOfNullable(Class<T> type, @Nullable T... values)
      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.
      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

      <T> Vars<@Nullable T> varsOfNullable(Var<@Nullable T> first, Var<@Nullable T>... rest)
      Creates a list of nullable properties from the supplied properties.
      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.

    • varsOfNullable

      <T> Vars<@Nullable T> varsOfNullable(Class<T> type, Iterable<Var<@Nullable T>> vars)
      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.
      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

      <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. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty vararg array.
      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.
      Throws:
      NullPointerException - if type is null, or vec is null.
      IllegalArgumentException - if any Maybe allows null.

    • tupleOf

      <T> Tuple<T> tupleOf(Class<T> type)
      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.
      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.
      Throws:
      NullPointerException - if type is null.

    • tupleOf

      default <T> Tuple<T> tupleOf(Maybe<T> first, Maybe<T>... rest)
      Creates an immutable tuple of non-nullable items from one or more non-nullable items wrapped by Maybe properties.
      Type Parameters:
      T - the type of the items in the tuple.
      Parameters:
      first - the first Maybe to add to the new Tuple instance.
      rest - the remaining items to add to the new Tuple instance.
      Returns:
      a new Tuple instance.
      Throws:
      NullPointerException - if first is null, or rest is null.
      IllegalArgumentException - if any Maybe allows null.

    • tupleOf

      <T> Tuple<T> tupleOf(T first, T... rest)
      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.
      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.
      Throws:
      NullPointerException - if first is null, or rest is null.
      IllegalArgumentException - if any value in rest is null.

    • tupleOf

      Tuple<Float> tupleOf(float... floats)
      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.
      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.
      Throws:
      NullPointerException - if floats is null.

    • tupleOf

      Tuple<Double> tupleOf(double... doubles)
      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.
      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.
      Throws:
      NullPointerException - if doubles is null.

    • tupleOf

      Tuple<Integer> tupleOf(int... ints)
      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.
      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.
      Throws:
      NullPointerException - if ints is null.

    • tupleOf

      Tuple<Byte> tupleOf(byte... bytes)
      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.
      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.
      Throws:
      NullPointerException - if bytes is null.

    • tupleOf

      Tuple<Long> tupleOf(long... longs)
      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.
      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.
      Throws:
      NullPointerException - if longs is null.

    • tupleOf

      <T> Tuple<T> tupleOf(Class<T> type, T... items)
      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.
      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.
      Throws:
      NullPointerException - if type is null, or items is null.

    • tupleOf

      <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. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty iterable.
      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.
      Throws:
      NullPointerException - if type is null, or vec is null.
      IllegalArgumentException - if any Maybe in vec allows null.

    • tupleOfNullable

      default <T> Tuple<@Nullable T> tupleOfNullable(Class<T> type, Maybe<@Nullable T>... maybes)
      Creates an immutable tuple of nullable items from the supplied type and varargs items. This factory method requires the type to be specified, because the compiler cannot infer the type from the null values.
      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. The items may be nullable items, but they may not be null themselves.
      Returns:
      a new Tuple instance.
      Throws:
      NullPointerException - if type is null, or vec is null.

    • tupleOfNullable

      <T> Tuple<@Nullable T> tupleOfNullable(Class<T> type)
      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.
      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.
      Throws:
      NullPointerException - if type is null.

    • tupleOfNullable

      <T> Tuple<@Nullable T> tupleOfNullable(Class<T> type, @Nullable T... items)
      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.
      Type Parameters:
      T - the type of the values.
      Parameters:
      type - the type of the items in the tuple.
      items - The items to be stored by the new Tuple instance. The values may be null.
      Returns:
      a new Tuple instance.

    • tupleOfNullable

      default <T> Tuple<@Nullable T> tupleOfNullable(Maybe<@Nullable T> first, Maybe<@Nullable T>... rest)
      Creates an immutable tuple of nullable items from the supplied items.
      Type Parameters:
      T - the type of the items in the tuple.
      Parameters:
      first - the first Maybe to add to the new Tuple instance.
      rest - the remaining items to add to the new Tuple instance.
      Returns:
      a new Tuple instance.

    • tupleOfNullable

      <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. This factory method requires the type to be specified, because the compiler cannot infer the type from a potentially empty iterable.
      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

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

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

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

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

      <E> ValueSet<E> valueSetOf(Class<E> type)
      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.
      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

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

      <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. 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)
    );
      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

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

    • defaultId

      String defaultId()
      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.
      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

      Pattern idPattern()
      The regex Pattern used to validate property ids. All ids must match this pattern.
      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

      Channel defaultChannel()
      The default channel used for change events. This channel is used to give events a chanel when no channel is explicitly specified.
      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

      Channel defaultObservableChannel()
      The default channel used for Observable events, registered through the Observable.subscribe(Observer) method.
      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

      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. 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.
      Returns:
      A constant which serves as a sort of logging channel used on all logging sites of the sprouts library.