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: Do not depend on classes inside this package! Everything in this package should be considered 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 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 null safe view on a thing which may or may not exist, and it serves as a general blue-print for nomadic types like the Result type.
MissingItemException	A checked 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 that is executed when a sprouts Observable is triggered, usually in the form of an Event or property, like Val, Var, Vals or Vars.
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 a value 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 obtaining the value wrapped by the result.
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.
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 property such as Val and Var.
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.
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 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 which can be observed for changes using Actions registered through the Viewables.onChange(Action) method.
WeakAction<O,D>	A weak action is an extension of the Action interface which defines a method for clearing the action and a method for retrieving the owner of the action.
WeakObserver<O>	A weak observer is an extension of the Observer interface which defines a method for clearing its state (setting it to null) and a method for retrieving the owner of the observer.