Package sprouts

Interface Lens<A extends @Nullable Object,B extends @Nullable Object>

Type Parameters:
A - The parent type with the field of type B to be focused on.
B - The type of the field to be focused on in the parent type A.
public interface 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. A lens can also be composed with other lenses to focus on more deeply nested parts. This design concept is part of the functional programming paradigm, and it emulates mutable properties (getter and setter) in an immutable world using a getter and more importantly a wither methods (a function that returns a new structure with target field being updated).

So a Lenses encapsulate two essential operations:

  • getter: Extracts a specific field from a parent type.
  • wither: Produces a new instance of the parent with an updated field, preserving immutability.

Usage Example:


 record Person(String name, Address address) {}
 record Address(String street, String city) {}

 Lens<Person, Address> addressLens = Lens.of(
     Person::address,
     (person, newAddress) -> new Person(person.name(), newAddress)
 );

 Lens<Address, String> streetLens = Lens.of(
     Address::street,
     (address, newStreet) -> new Address(newStreet, address.city())
 );

 Lens<Person, String> personStreetLens = addressLens.to(streetLens);

 Person person = new Person("Alice", new Address("1st Ave", "Wonderland"));
 String street = personStreetLens.getter(person); // "1st Ave"
 Person updatedPerson = personStreetLens.wither(person, "2nd Ave");

Composability:

You may compose lenses using the to(Lens) method, which composes them into a new lens, enabling seamless traversal and modification of deeply nested structures.

Factory Method:

The of(Function, BiFunction) static method is provided to easily create lenses from lambda expressions.

  • Method Summary

    Modifier and Type
    Method
    Description
    B
    getter(A parentValue)
    Extracts the field of type B from the parent type A and returns it or throws an exception if an error occurs while extracting the field.
    static <A, B> Lens<A,B>
    of(Function<A,B> getter, BiFunction<A,B,A> wither)
    Creates a new lens from the given getter and wither functions, where the first function serves as an implementation of getter(Object) and the second function serves as an implementation of wither(Object, Object).
    default <C> Lens<A,C>
    to(Function<B,C> getter, BiFunction<B,C,B> wither)
    Combines this lens with a pair of getter and wither functions, to create a new lens that focuses on a more deeply nested field.
    default <C> Lens<A,C>
    to(Lens<B,C> other)
    Composes this lens with another lens, creating a new lens that focuses on a more deeply nested field.
    A
    wither(A parentValue, B newValue)
    Produces a new instance of the parent type A with one of its fields of type B updated with a new value.

  • Method Details

    • of

      static <A, B> Lens<A,B> of(Function<A,B> getter, BiFunction<A,B,A> wither)
      Creates a new lens from the given getter and wither functions, where the first function serves as an implementation of getter(Object) and the second function serves as an implementation of wither(Object, Object).
      Type Parameters:
      A - The parent type with the field of type B to be focused on.
      B - The type of the field to be focused on in the parent type A.
      Parameters:
      getter - The function that extracts the field of type B from the parent type A.
      wither - The function that produces a new instance of the parent type A with the field updated.
      Returns:
      A new lens instance.
      Throws:
      NullPointerException - If either of the given functions is null.

    • getter

      B getter(A parentValue) throws Exception
      Extracts the field of type B from the parent type A and returns it or throws an exception if an error occurs while extracting the field.
      Parameters:
      parentValue - The parent object to extract the field from.
      Returns:
      The field of type B from the parent object.
      Throws:
      Exception - If an error occurs while extracting the field.

    • wither

      A wither(A parentValue, B newValue) throws Exception
      Produces a new instance of the parent type A with one of its fields of type B updated with a new value. The parent object is not modified, and a new instance is returned.
      Parameters:
      parentValue - The parent object to update the field in.
      newValue - The new value to update the field with.
      Returns:
      A new instance of the parent type A with the field updated.
      Throws:
      Exception - If an error occurs while updating the field.

    • to

      default <C> Lens<A,C> to(Lens<B,C> other)
      Composes this lens with another lens, creating a new lens that focuses on a more deeply nested field. This lens focuses on a field of type B in the parent type A, and the other lens focuses on a field of type C in the parent type B. The composed lens will focus on a field of type C in the parent type A, effectively traversing two levels of nesting and side-stepping the intermediate parent type B.
      Type Parameters:
      C - The type of the field to be focused on in the parent type B.
      Parameters:
      other - The other lens to compose with this lens.
      Returns:
      A new lens that focuses on a more deeply nested field.
      Throws:
      NullPointerException - If the given lens is null.

    • to

      default <C> Lens<A,C> to(Function<B,C> getter, BiFunction<B,C,B> wither)
      Combines this lens with a pair of getter and wither functions, to create a new lens that focuses on a more deeply nested field. This lens focuses on a field of type B in the parent type A, and the two supplied lambdas focus on a field of type C in the parent type B. The composed lens will focus on a field of type C in the parent type A, effectively traversing two levels of nesting and side-stepping the intermediate parent type B.
      Type Parameters:
      C - The type of the field to be focused on in the parent type B.
      Parameters:
      getter - The function that extracts the field of type C from the parent type B.
      wither - The function that produces a new instance of the parent type B with the field updated.
      Returns:
      A new lens that focuses on a more deeply nested field.
      Throws:
      NullPointerException - If either of the given functions is null.