Annotations at a Glance

The complete optic-generation surface in one page

What You'll Learn

  • Which annotation to apply for each optic type, and what target each annotation expects (record, sealed interface, enum, method, package-info).
  • How to choose between @ImportOptics and an OpticsSpec interface for types you don't own.
  • The eight spec-method hints that drive optic generation for external types: prism matchers, lens copy strategies, traversal hints, and Kind-field configuration.
  • Where in the book to look for the in-depth treatment of each annotation.

Every optic in this chapter is generated by an annotation. You write a record or sealed type, add the annotation, and the processor produces a typed companion class at compile time. There are no runtime reflection costs and no boilerplate to maintain.

This page is the lookup table. Each row links to the page that explores the annotation in depth.

1. Generate optics for your records

Apply these to your own records and sealed types. The generated class is placed in the same package by default; pass targetPackage = "..." to override.

AnnotationApply toGeneratesWhen to reach for it
@GenerateLensesrecordXLenses (one lens per field, plus withFoo helpers)Default starting point for any record you want to update functionally
@GenerateFocusrecordXFocus (path-based DSL builder)Pair with @GenerateLenses when you want fluent, IDE-friendly navigation
@GenerateFoldsrecordXFolds (read-only optics)Querying without modification (CQRS-friendly)
@GenerateGettersrecordXGetters (asymmetric read-only)When you specifically want a Getter rather than a full Lens
@GenerateSettersrecordXSetters (asymmetric write-only)When you specifically want a Setter rather than a full Lens
@GenerateTraversalsrecord containing List<T> etc.XTraversals (one traversal per traversable field)Bulk operations on a collection embedded in a record
@GeneratePrismssealed interface or enumXPrisms (one prism per variant)Sum types, including both sealed hierarchies and enum constants
@GenerateIsosmethod returning Iso<A, B>companion class with the iso as a static fieldLossless conversions between equivalent representations

Annotations stack

You almost always want at least @GenerateLenses and @GenerateFocus together. Add @GenerateTraversals if the record contains a collection field and @GenerateFolds if you also need read-only queries.

@GenerateLenses
@GenerateFocus
@GenerateTraversals
public record Order(Customer customer, List<LineItem> items) {}

2. Generate optics for types you don't own

External types like LocalDate, Jackson's JsonNode, JOOQ records, and Protobuf messages can't be annotated directly. Two gateways bring them into the optics world.

AnnotationApply toUse when
@ImportOpticspackage-info.java or a typeThe external type is a record (lenses), sealed interface (prisms), or enum (prisms) and the processor can analyse it directly
OpticsSpec<S>extend in your own interfaceThe external type defies auto-detection (no sealed hierarchy, no copy mechanism, predicate-based type checks). You declare what you want; hint annotations say how to build it.

OpticsSpec interfaces use the spec-method hints below to tell the processor how to generate each optic.

3. Spec-method hints (inside OpticsSpec interfaces)

Apply these to abstract methods inside an interface that extends OpticsSpec<S>.

Prism hints, for sum-type-like external types

AnnotationGenerates a prism via
@InstanceOf(SubType.class)Java instanceof pattern matching (e.g. Jackson's ObjectNode, ArrayNode)
@MatchWhenPredicate method (isFoo()) plus a getter (asFoo()), for type-checking APIs that don't use sealed types

Lens hints, copy strategies for legacy Java

External record-like types rarely have a single copy mechanism. The processor uses these hints to know how to rebuild the object after a set or modify.

AnnotationGenerates a lens that copies via
@WitherA withFoo(value) method on the source
@ViaBuilderThe builder pattern (source.toBuilder().foo(value).build())
@ViaConstructorThe all-args constructor
@ViaCopyAndSetA copy constructor followed by a setter call (legacy bean style)

Traversal hints

AnnotationGenerates
@ThroughFieldA traversal composing a lens-to-field with the auto-detected container traversal
@TraverseWithA traversal using an explicitly named Traverse instance

Kind-field configuration

AnnotationEffect
@TraverseFieldConfigures how a Kind<F, A> field is processed by the Focus DSL generator. Pair with KindSemantics to declare cardinality (EXACTLY_ONE, ZERO_OR_ONE, ZERO_OR_MORE).

4. Build setup

The HKJ Gradle and Maven plugins wire the annotation processor in for you. Apply the plugin and every annotation on this page is available immediately. See Build Plugins: One-Line HKJ Setup for the plugin DSL, or Manual Setup if you need to configure dependencies by hand.

For compile-time path-type checking, see Compile-Time Checks.

5. Quick decision guide

You have...You want to...Reach for
A recordGet/set fields functionally@GenerateLenses
A recordNavigate deeply with a fluent DSL@GenerateLenses + @GenerateFocus
A record with a List fieldUpdate every element@GenerateTraversals
A recordQuery without modifying@GenerateFolds
A sealed interface or enumOperate on one variant@GeneratePrisms
Two equivalent typesConvert losslessly@GenerateIsos on a method
An external record (in a library)Lenses for its components@ImportOptics
An external sealed/enum (in a library)Prisms for its variants@ImportOptics
JsonNode, JOOQ records, anything trickyCustom optics with copy strategy@ImportOptics on an OpticsSpec interface + spec-method hints

Where next?

Previous: Quickstart Next: Fundamentals