Package sprouts

@NullMarked package sprouts

This is the main package for the Sprouts property collections library designed to provide all necessary tools to implement common architectural design patterns like MVVM, MVI, MVL, based on data oriented programming principles (immutability, value objects, lenses, circular data flow, etc.).

It was designed in conjunction with the SwingTree GUI Framework, which has native support for binding to the Sprouts properties.

We recommended using Sprouts as a tool for bridging the gap between place oriented programming and data oriented programming, which is especially useful in GUI programming, where data oriented / functional programming principles are hard to apply due to the inherently place oriented nature of GUI components.
Sprouts allows you to create lens based properties that make value object based view models interoperate with your GUI components or other kinds of views.
This is best achieved using the MVI (Model-View-Intent) and MVL (Model-View-Lens) patterns.

Here an example demonstrating how to create a set of bindable properties from a basic record based modelling scenario:
View Models:

    public record Address(
        String street, String city, int postalCode
    ) {
        public Address withStreet(String street) {
            return new Address(street, city, postalCode);
        }
        public Address withCity(String city) {
            return new Address(street, city, postalCode);
        }
        public Address withPostalCode(int postalCode) {
            return new Address(street, city, postalCode);
        }
    }
  

    public record Person(
        String forename, String surname, Address address
    ) {
        public Person withForename(String forename) {
            return new Person(forename, surname, address);
        }
        public Person withSurname(String surname) {
            return new Person(forename, surname, address);
        }
        public Person withAddress(Address address) {
            return new Person(forename, surname, address);
        }
    }
  

View:

    public final class PersonView {

        public static void main(String[] args) {
            Person person = new Person("John", "Doe", new Address("Main Street", "Springfield", 12345));
            Var<Person> applicationState = Var.of(person);
            var view = new PersonView(applicationState);
            // show view
        }

        public PersonView(Var<Person> vm) {
            Var<String> forename = vm.zoomTo(Person::forename, Person::withForename);
            Var<String> surname = vm.zoomTo(Person::surname, Person::withSurname);
            Val<String> fullName = vm.viewAsString( person -> person.forename() + " " + person.surname() );
            Var<Address> address = vm.zoomTo(Person::address, Person::withAddress);
            Var<String> street = address.zoomTo(Address::street, Address::withStreet);
            Var<String> city = address.zoomTo(Address::city, Address::withCity);
            Var<Integer> postalCode = address.zoomTo(Address::postalCode, Address::withPostalCode);
            // Use mutable properties in the views GUI...
        }
    }
  

For more usage information check out this page, where you can browse the living documentation of the Sprouts API.
Also check out the SwingTree GUI Framework for more example code using the Sprouts properties natively.

Related Packages

Package	Description
sprouts.impl	WARNING: This is considered an internal package. Do not depend on classes inside this package! Almost everything in this package is being treated as library-private.

Class	Description
Action<D>	A functional interface for observing state changes and performing some action in response.
Association<K,V>	Defines an association between keys and values as an immutable value object where the values are accessed by the keys in a map-like fashion.
Channel	This is a marker interface for property event channels.
Event	An event is something that can be triggered and reacted to, through Observables created by the Event.observable() method.
Event.Executor	The "event executor" is responsible for executing a given Runnable when an Event is triggered.
From	An implementation of the Channel marker interface which is used to identify the source of a change in a Var or Val property.
HasId<I>	This is a sort of marker interface for Var/Val property item types, which tells the property that it wants to use the object returned by the HasId.id() method as a unique identifier for its item when determining the ValDelegate.change() type.
Lens<A extends @Nullable Object,B extends @Nullable Object>	The Lens interface defines an access and update operation on an individual part of a nested and immutable data structure.
Maybe<T>	The Maybe interface represents a thing of a specific Maybe.type() which may or may not exist, and it serves as a null safe blue-print for nomadic types like the Result type.
MissingItemException	A checked exception thrown when an item is missing from a Maybe object, which may also be a Val, Var or Result.
MissingItemRuntimeException	A non-checked runtime exception thrown when an item is missing from a Maybe object.
Observable	This represents an event that can be observed but not triggered.
Observer	An observer is a callback function stored inside a Viewable, Viewables or more generally Observable, and it is typically invoked when an Event is triggered, or a property, like Val, Var, Vals or Vars, experienced a state change. So if you want to observe an event or properties using an observer, then you have to create Observable "views" using the following methods, among others: Event.observable() Val.view() Val.view() Vals.view() Vals.view()
Pair<F extends @Nullable Object,S extends @Nullable Object>	An immutable value object representing a pair of two generic values.
Problem	A problem is a wrapper for information describing an issue that can be reported and attached to a Result.
Result<V>	A Result is very similar to an Optional in that it can either contain an item or not, with the difference being that a result can also contain a list of Problems which describe what went wrong in the process of getting the item wrapped by the result.
ResultItemSupplier<T extends @Nullable Object>	Supplier of a Result's item, which may throw a RuntimeException or checked Exception when used to supply a result item during an invocation of the Result.ofTry(Class, ResultItemSupplier) factory method. This is a functional interface only intended to be used for the result pattern.
ResultRunAttempt	Similar to ResultItemSupplier, but used for running an operation that does not return a value.
SequenceChange	Describes how a Vars instance was mutated.
SingleChange	A set of constants that describe how a property item has changed.
Subscriber	A subscriber may either be an Observer or an Action and it is used as a marker interface to allow for both types to be identified, grouped and used interchangeably. A subscriber is specifically designed to be stored in a Viewable, Viewables or more generally Observable, typically to serve as a simple change listener. This interface does not have any methods and is only used for type checking or to remove any kind of change listener from an observable, through Observable.unsubscribe(Subscriber)!
Tuple<T extends @Nullable Object>	An immutable collection of ordered items of the same type T (see Tuple.type()), whose items can be iterated over and accessed through their indices. This class can be thought of as an immutable array with an API designed for functional programming and robust handling of null values.
Val<T extends @Nullable Object>	A read only wrapper around an item which can be mapped to a weakly referenced Viewable to then be observed for changes using Actions registered through the Viewable.onChange(Channel, Action) method, where the Channel is used to distinguish between changes from different sources (usually application layers like the view model or the view). Use Val.view() to access a simple no-op live view of the item of this property and register change listeners on it to react to state changes.
ValDelegate<T>	A context object passed to the various types of change listeners registered on a Viewable, derived from a Var or Val property.
Vals<T extends @Nullable Object>	A read only API of a list of read-only viewed properties that can be observed, iterated over, mapped, filtered, turned into a stream, and more.
ValsDelegate<T>	A context object passed to the various types of change listeners registered in property lists such as Vals and Vars.
ValueSet<E>	An immutable collection of non-null elements that contains no duplicates, meaning that it can never contain a pair of elements e1 and e2 such that e1.equals(e2).
Var<T extends @Nullable Object>	A mutable wrapper for an item which can also be mapped to a weakly referencedViewable to be observed for changes using Actions registered through the Viewable.onChange(Channel, Action) method, where the Channel is used to distinguish between changes from different sources (usually application layers like the view model or the view). Use Val.view() to access a simple no-op live view of the item of this property and register change listeners on it to react to state changes.
Vars<T extends @Nullable Object>	A mutable list of mutable properties designed for MVVM, that can be observed for changes through a Vals.view() by registering Subscriber types on it like Observers and Actions.
Version	This is a value object representing a unique ID consisting of two numbers, a lineage and succession, allowing you to identify something and also determine the order in which something was created and updated.
Viewable<T>	A read-only live view on a delegated item derived from a Var or Val, which can be observed for changes using Actions registered through the Viewable.onChange(Channel, Action) method, where the Channel is used to distinguish between changes from different sources (usually application layers like the view model or the view).
Viewables<T>	A read-only live view on a delegated list of items derived from a Vars or Vals, which can be observed for changes using Actions registered through the onChange(Action) method.