Focus DSL: Path-Based Optic Syntax

Navigate and update nested records through generated, compile-checked paths that mirror the shape of your data.

A Focus path does for your records what the JPA metamodel or QueryDSL's Q-types do for a query, and it writes as well as reads. OrderFocus.customer().name() names a field the way QOrder.order.customer.name does, and the compiler checks every step. Instead of composing lenses, prisms and traversals by hand, you navigate your data with method chains that mirror its shape.

The whole feature on one screen

Step 1. Annotate the records. These are the chapter's cast, which the Quickstart introduced: an Order placed by a Customer.

@GenerateLenses
@GenerateFocus
@GenerateTraversals
public record Order(
    UUID id,
    Customer customer,
    List<LineItem> lines,
    Instant placedAt,
    Currency currency,
    OrderStatus status) {}

@GenerateLenses
@GenerateFocus
public record Customer(String name, EmailAddress email) {}

Step 2. Use the generated OrderFocus companion class:

    String name = OrderFocus.customer().name().get(order);

    Order renamed = OrderFocus.customer().name().set("Ada Lovelace", order);

    Order tidied = OrderFocus.customer().name().modify(String::strip, order);

Step 3. That is it. The path you typed (OrderFocus.customer().name()) is a typed value: store it, pass it around, reuse it. The processor generated OrderFocus and CustomerFocus at compile time; nothing reflective happens at runtime.

.name() chains straight off .customer() because Customer is another annotated record, so customer() returns a navigator. A navigator is the field's own path, a FocusPath<Order, Customer>, with a method added for each field of the record it reaches. It goes wherever a FocusPath goes, and .via(CustomerFocus.name()) spells the same hop. Navigators are on by default, and @GenerateFocus(generateNavigators = false) turns them off for a record.

Collections, optionals and sealed types extend the same pattern, and Find your field gives the spelling for each. You almost never have to compose lenses by hand to get useful work done.

Find your field

You arrive holding a field, not an optic type. Find its declaration in the table: the row gives what the generated method returns and what you write next. Every row but the last is a component of one Basket: the basket a customer pays for before it becomes an Order, given a field of every kind around the cast's own records. The collapsed proof compiles each one. Each field links to the section that explains it.

The two rows marked "by default" step into the elements instead when the annotation sets widenCollections = true, or names the field in widenFields, which the fine print covers.

// The basket a customer pays for before it becomes an Order, with a field of every kind
@GenerateFocus
record Basket(
    Customer customer,
    String reference,
    List<LineItem> lines,
    Optional<String> giftMessage,
    @Nullable String couponCode,
    String legacyNote,
    Map<String, String> attributes,
    String[] tags,
    Either<String, String> approvedBy,
    Payment payment,
    JsonNode payload) {}

    // A record with @GenerateFocus: with navigators on, the next field chains straight on
    FocusPath<Basket, String> customerEmail = BasketFocus.customer().email().value();

    // A plain value: read and write it
    FocusPath<Basket, String> reference = BasketFocus.reference();

    // A List, Set or Collection of records: a navigator already on the elements
    TraversalPath<Basket, Integer> quantities = BasketFocus.lines().quantity();

    // An Optional, or a component with a recognised @Nullable: zero or one
    AffinePath<Basket, String> giftMessage = BasketFocus.giftMessage();
    AffinePath<Basket, String> couponCode = BasketFocus.couponCode();

    // A reference that may hold null, with no annotation: say so with .nullable()
    AffinePath<Basket, String> legacyNote = BasketFocus.legacyNote().nullable();

    // A Map: the path focuses the whole map, and mapAt(k) picks one value
    AffinePath<Basket, String> channel = BasketFocus.attributes().via(FocusPaths.mapAt("channel"));

    // An array: the path focuses the whole array, and .each(...) steps into it
    TraversalPath<Basket, String> tags = BasketFocus.tags().each(EachInstances.arrayEach());

    // An Either, Maybe, Try or Validated: zero or one, on the success side
    AffinePath<Basket, String> approvedBy = BasketFocus.approvedBy();

    // A sealed type: a generated prism picks one variant, or instanceOf by runtime type
    AffinePath<Basket, Card> card = BasketFocus.payment().via(PaymentPrisms.card());
    AffinePath<Basket, Card> sameCard =
        BasketFocus.payment().via(AffinePath.instanceOf(Card.class));

    // A type you cannot annotate: compose the optics @ImportOptics generated for it
    AffinePath<Basket, ObjectNode> payloadObject =
        BasketFocus.payload().via(JsonNodeOptics.object());

Collections, Optionals and Sealed Types explains each row in depth: which fields get a navigator, and how a path widens as it goes.

What the processor gives you

Annotate the records

Add @GenerateFocus to generate path builders. The Focus class builds its own lenses, so @GenerateFocus alone compiles. Add @GenerateLenses as well in practice: several idioms in this chapter start from FocusPath.of(TheseLenses.field()), which needs the generated lens class. Indexing a list is one, and decomposing it into its head and tail with ListPrisms another.

The examples that follow use the cast's Order and LineItem, and a CustomerProfile: a customer's account profile, whose nickname and second email are optional.

@GenerateLenses
@GenerateFocus
public record CustomerProfile(
    String name, Optional<String> nickname, Optional<EmailAddress> altEmail) {}

One method per component, and the field type picks the path

The generated companion has one method per record component, and the field's type decides the path type you get back:

    // A plain field: exactly one focus
    FocusPath<Order, OrderStatus> statusPath = OrderFocus.status();
    OrderStatus status = statusPath.get(order);

    // A List field: the processor has already stepped into the elements
    TraversalPath<Order, LineItem> linePath = OrderFocus.lines();
    List<LineItem> lines = linePath.getAll(order);

    // An Optional field: zero or one focus
    AffinePath<CustomerProfile, String> nicknamePath = CustomerProfileFocus.nickname();
    Optional<String> nickname = nicknamePath.getOptional(profile);

Chain with .via()

Paths compose with .via(). Composing a path with a wider one widens the result, so one focus joined to many focuses is many focuses, and anything joined to a traversal is a traversal. The navigator OrderFocus.lines().sku() is this same path, written as a method call:

    TraversalPath<Order, String> skus = OrderFocus.lines().via(LineItemFocus.sku());

    // Read every one of them
    List<String> all = skus.getAll(order);

    // Or update every one of them
    Order lowered = skus.modifyAll(String::toLowerCase, order);

The Three Path Types

Focus DSL provides three path types, one for each answer to "how many values does this path reach?". Each navigation hop keeps the count or widens it, and headOption() is the one step back, from many to at most one:

FocusPath: Exactly One Element

FocusPath<S, A> wraps a Lens<S, A> and guarantees exactly one focused element:

    FocusPath<Customer, String> namePath = CustomerFocus.name();

    String name = namePath.get(customer); // always a value
    Customer updated = namePath.set("Grace", customer); // always succeeds
    Customer modified = namePath.modify(String::toUpperCase, customer);

Key Operations:

AffinePath: Zero or One Element

AffinePath<S, A> wraps an Affine<S, A> for optional access:

    AffinePath<CustomerProfile, String> nicknamePath = CustomerProfileFocus.nickname();

    Optional<String> nickname = nicknamePath.getOptional(profile); // may be empty
    CustomerProfile updated = nicknamePath.set("Countess", profile); // writes even when absent
    CustomerProfile modified = nicknamePath.modify(String::toUpperCase, profile);
    boolean hasNickname = nicknamePath.matches(profile);

Key Operations:

TraversalPath: Zero or More Elements

TraversalPath<S, A> wraps a Traversal<S, A> for collection access:

    TraversalPath<Order, LineItem> linesPath = OrderFocus.lines();

    List<LineItem> all = linesPath.getAll(order);
    Order updated = linesPath.setAll(replacement, order);
    Order modified =
        linesPath.modifyAll(line -> LineItemLenses.quantity().modify(q -> q + 1, line), order);
    int lineCount = linesPath.count(order);

Key Operations:

Previous: Quickstart Next: Collections, Optionals and Sealed Types