What a Path Is Made Of
Every path wraps an optic: take it out, compose it with andThen, and know when you need it.

- Name the optic each path type wraps, and take it out
- Write a lens by hand, and see that it is an accessor and a copy
- Compose optics with
andThen, and predict the type it returns - Choose an optic by how many values it reaches and whether it writes
- Know when to hand over the optic rather than the path
The code on this page is PathPartsBook.java and its PathPartsBookTest.java: the page includes them, so the build compiles and runs them.
Nearly every update so far has been a path, such as OrderFocus.customer().email().value(). A path is a thin wrapper around an optic: an object that reads one or more parts of a structure, and rebuilds the structure with them replaced. Most code never opens the wrapper. This page opens it for the few jobs that need it. When you need the optic lists them: an API that takes an optic, a type the processor cannot reach, an optic with no path type, and a compiler message that names an optic type.
Each path type wraps an optic
Each of the three path types wraps the optic of the same reach: a FocusPath a Lens, an AffinePath an Affine, and a TraversalPath a Traversal. Each hands its optic over with one call. The records are the chapter's cast, which the Quickstart introduced:
The cast these examples use
The cast these examples use
@GenerateLenses
@GenerateFocus
@GenerateTraversals
public record Order(
UUID id,
Customer customer,
List<LineItem> lines,
Instant placedAt,
Currency currency,
OrderStatus status) {}
@GenerateLenses
@GenerateFocus
public record LineItem(String sku, Integer quantity, BigDecimal price) {}
@GenerateLenses
@GenerateFocus
public record Customer(String name, EmailAddress email) {}
@GenerateLenses
@GenerateFocus
public record EmailAddress(String value) {}
@GenerateLenses
@GenerateFocus
public record Consignment(UUID orderId, Address to, ConsignmentState state) {}
/** Where a consignment has got to. */
@GeneratePrisms
public sealed interface ConsignmentState
permits ConsignmentState.Pending, ConsignmentState.Dispatched, ConsignmentState.Returned {
record Pending() implements ConsignmentState {}
@GenerateFocus
record Dispatched(Instant at) implements ConsignmentState {}
@GenerateFocus
record Returned(String reason) implements ConsignmentState {}
}
Each path gives up its optic:
FocusPath<Order, String> emailPath = OrderFocus.customer().email().value();
Lens<Order, String> emailValue = emailPath.toLens();
AffinePath<Consignment, ConsignmentState.Dispatched> dispatchedPath =
ConsignmentFocus.state().via(ConsignmentStatePrisms.dispatched());
Affine<Consignment, ConsignmentState.Dispatched> dispatched = dispatchedPath.toAffine();
TraversalPath<Order, Integer> quantityPath = OrderFocus.lines().quantity();
Traversal<Order, Integer> quantities = quantityPath.toTraversal();
The optic reads and writes exactly what its path does: setting the email through emailValue gives the same Order as setting it through emailPath. FocusPath.of(lens) goes the other way, and wraps an optic you already hold in a path.
What a lens is
A Lens<S, A> is the pair you would write by hand for one record component: the accessor, and a copy that replaces that component. Lens.of takes exactly those two functions:
Lens<Customer, EmailAddress> email =
Lens.of(Customer::email, (customer, newEmail) -> new Customer(customer.name(), newEmail));
CustomerLenses.email() is this lens, generated, and a generated lens class holds one per component; the Quickstart's What the processor wrote shows a whole class. A lens keeps three promises: you read back what you set; setting what you just read changes nothing; and a second set replaces the first. hkj-test's LensLaws checks all three, which matters most for a lens you write by hand. A lens is a wither you can pass around, and it does what a wither cannot: compose. Why a lens, when you have @With? makes that case in full.
Composing optics with andThen
andThen joins two optics end to end, as .via(...) joins a path to its next hop. The result reaches as many values as the two steps allow together. A lens then a lens is a Lens. A lens then a zero-or-one step is an Affine, even when that step is a Prism. Any of the five read-write optics followed by a Traversal is a Traversal. An Iso takes the type of whatever follows it:
// exactly one, then exactly one: still exactly one
Lens<Order, String> emailValue =
OrderLenses.customer().andThen(CustomerLenses.email()).andThen(EmailAddressLenses.value());
// exactly one, then one variant: zero or one
Affine<Consignment, ConsignmentState.Dispatched> dispatched =
ConsignmentLenses.state().andThen(ConsignmentStatePrisms.dispatched());
// zero or more, then exactly one: zero or more
Traversal<Order, Integer> quantities =
OrderTraversals.lines().andThen(LineItemLenses.quantity());
.via(...) on a path is andThen on the optic inside, so ConsignmentFocus.state().via(ConsignmentStatePrisms.dispatched()) and ConsignmentLenses.state().andThen(ConsignmentStatePrisms.dispatched()) find the same dispatch. The composed emailValue is the copy-and-rebuild cascade written once: a set through it rebuilds the EmailAddress, the Customer and the Order, and reuses every value off the path. Composition Rules gives the result type for every pair.
Choosing an optic
Two questions pick the optic: how many values it reaches, and whether you may write through it.
| exactly one | zero or one | zero or more | |
|---|---|---|---|
| read and write | Lens, or an Iso when it converts both ways | Affine, or a Prism when it picks a variant of a sealed type | Traversal |
| read only | Getter | a Fold that finds at most one | Fold |
| write only | Setter |
Each plays the part of a Java idiom you already write:
| Optic | Plays the part of | What it adds |
|---|---|---|
| Lens | an accessor and a withX copy, as one value | composes through nested records |
| Affine | an accessor that returns Optional, with a copy that writes the value | composes, and modify leaves an absent value alone |
| Prism | an instanceof pattern, and the variant's constructor | composes, and builds the variant back |
| Iso | a wrapper record's constructor and accessor, such as new EmailAddress(value) and email.value(), which lose nothing | composes, and turns around with reverse() |
| Traversal | stream().map(f).toList() over a list field, put back with a wither | does the rebuild for you, at any depth |
| Fold | a Stream over the same values, which only reads | composes, and says in its type that it never writes |
| Getter | a derived accessor, such as a fullName() computed from two fields | composes with other getters, and as a fold, through asFold(), with any optic's fold |
| Setter | stream().map(f).toList() put back with a wither, with nothing read out first | composes, for a value you change without reading |
An iso keeps a stronger promise than a lens: converting there and back, either way round, returns what you started with, and hkj-test's IsoLaws checks it.
The chapter introduction draws how the eight types relate, and Decision Trees asks the same two questions as a tree.
Using an optic directly
A raw optic carries the operations its type allows. A Traversal is the exception that surprises people: its reads and writes live in the Traversals utility rather than on the traversal itself, and it reads as a Fold through asFold():
Order doubled = Traversals.modify(quantities, quantity -> quantity * 2, order);
int totalQuantity =
quantities.asFold().foldMap(Monoids.integerAddition(), quantity -> quantity, order);
Optional<ConsignmentState.Dispatched> dispatch = dispatched.getOptional(consignment);
For Ada's order of one lamp and four bulbs, doubled holds quantities of 2 and 8 and totalQuantity is 5, and for a dispatched consignment dispatch holds its dispatch. A TraversalPath has modifyAll and getAll of its own, which is one reason to stay on the path. Mind the argument order, which differs by home: a path's methods take the source last, path.modify(f, source); Traversals.modify(traversal, f, source) puts the optic first; and OpticOps, on the next page, puts the source first.
When you need the optic, not the path
Stay on the path by default. It has every read and write, its field names locate a validation error, and it can hand its value on to an Effect Path. Take the optic out when one of these is true:
| When | What to do |
|---|---|
An API takes an optic: OpticOps, which Updates That Can Fail uses, or hkj-test's LensLaws, which checks that a hand-written lens behaves | Hand it path.toLens(), toAffine() or toTraversal() |
| The processor cannot reach the type, because you cannot annotate the class | Write the lens with Lens.of, as in What a lens is, and check it with LensLaws; or generate the optics with @ImportOptics, which Optics for External Types covers, and when to write a lens by hand compares |
The optic has no path type: an Iso, a Getter, a Fold or a Setter | Use it directly. An iso still joins a path through .via(iso), and every path gives you its fold with asFold() |
A compiler message names an optic type, such as Affine<Consignment, Dispatched> | Read it as the optic inside the matching path type; the grid says what that optic can do, and Compiler Errors lists the common messages |
You can now take the optic out of a path, compose optics with andThen, and choose an optic by how many values it reaches and whether it writes. The next page hands those optics to updates that can fail.
Are ConsignmentLenses.to().andThen(AddressLenses.postcode()) and ConsignmentFocus.to().postcode().toLens() the same optic? What type is each?
Answer and why
Answer and why
Yes: each is a Lens<Consignment, String>, and they read and write the same postcode. .via(...) on a path is andThen on the optic inside, and a navigator's hop is sugar for that .via(...).
Where this lives: Composing optics with andThen.
Iso.of(EmailAddress::value, EmailAddress::new) is a lawful iso. Is Iso.of(Instant::getEpochSecond, Instant::ofEpochSecond) one?
Answer and why
Answer and why
No. It compiles as an Iso, but it breaks the iso's promise. An Instant with a fraction of a second loses it on the way to whole seconds, so converting there and back does not return the instant you started with, and IsoLaws reports it.
Where this lives: Choosing an optic.
- A path is an optic with a friendlier API.
FocusPathwraps aLens,AffinePathanAffineandTraversalPathaTraversal;toLens(),toAffine()andtoTraversal()take it out. - A lens is an accessor and a copy.
Lens.of(getter, setter)is the whole definition, and the processor writes one per record component. andThenis.via()for optics. The result reaches as many values as both steps allow together, anIsotakes the type of what follows it, and Composition Rules tabulates every pair.- Two questions pick the optic. How many values it reaches, and whether it may write.
- Stay on the path until an API, a type or a message needs the optic.
- Tutorial01_LensBasics.java (7 exercises): lenses by hand and generated
- Tutorial06_OpticsComposition.java (7 exercises): composing different optic types
- The Optic Types: each optic type in depth
- Composition Rules: the type
andThenreturns for every pair - Optic Capabilities: which operations each optic type declares
- Profunctor Optics: changing the types an optic works between
Previous: Collections, Optionals and Sealed Types Next: Updates That Can Fail