Focus DSL with External Libraries

Navigate from your records into Immutables, Lombok, AutoValue or Protobuf types with one Focus path.

"The best interface is no interface at all. The second best is the one that feels invisible."

– Don Norman

The best solution would be Focus DSL working seamlessly with every external type, no extra code. That is not possible; external libraries do not know about our optics. The second best is what this page builds: a bridge that feels invisible in use, so a developer navigates from OfficeNetworkFocus.headquarters() into AddressOptics.city() without thinking about the boundary.

Here is the whole pattern, compiled by the build. A Focus path over your own records, joined by .via() to an optic generated for a type you do not own:

  public static TraversalPath<OfficeNetwork, String> allCompanyEmails() {
    // offices() returns TraversalPath<OfficeNetwork, Office>
    // via(TraversalPath) composes to TraversalPath<OfficeNetwork, OfficeWorker>
    return OfficeNetworkFocus.offices()
        .via(OfficeFocus.staff())
        .via(OfficeWorkerFocus.contact())
        .via(ContactDetailsOptics.email());
  }

OfficeNetworkFocus.offices() and OfficeFocus.staff() are generated from your records; ContactDetailsOptics.email() is generated from a spec interface for an Immutables value. .via() does not care which is which.

The Bridge Pattern

Focus covers the types you own. Spec interfaces cover the types you do not. The bridge layer is a handful of composed constants where the two meet, and the only real decision is which copy strategy the external library's generated code calls for. Database Records with JOOQ sets those four out in full; this page is about what happens once the external optics exist.

A Complete Example: Immutables Value Objects

The External Types

Address and ContactDetails come from an Immutables-generated module: accessor methods with no get prefix, and wither methods for modification.

// An Immutables module's Address, with the chapter's Address components
@Value.Immutable
public interface Address {
  String street();
  String city();
  String postcode();

  // Immutables generates withStreet(...), withCity(...), and a builder
}

The Spec Interface

@Wither names each getter and wither pair, and the processor generates AddressOptics:

@ImportOptics
public interface AddressOpticsSpec extends OpticsSpec<Address> {

  @Wither(value = "withStreet", getter = "street")
  Lens<Address, String> street();

  @Wither(value = "withCity", getter = "city")
  Lens<Address, String> city();

  @Wither(value = "withPostcode", getter = "postcode")
  Lens<Address, String> postcode();
}

Your Local Domain

Ordinary records, annotated as usual, with fields whose types come from the external library:

@GenerateFocus
@GenerateLenses
public record OfficeNetwork(String name, Address headquarters, List<Office> offices) {}

@GenerateFocus
@GenerateLenses
public record Office(String name, OfficeWorker manager, List<OfficeWorker> staff, Address location) {}

@GenerateFocus
@GenerateLenses
public record OfficeWorker(String id, String name, ContactDetails contact, BigDecimal salary) {}

The Bridge

.via() covers the composition itself. toLens() earns its place when you want the result to be a reusable Lens constant rather than a path, which is what lets code that has never heard of the Focus DSL consume it:

  public static final Lens<OfficeNetwork, String> HEADQUARTERS_CITY =
      OfficeNetworkFocus.headquarters().toLens().andThen(AddressOptics.city());

Using them looks like nothing in particular, which is the point. The values shown are for a sample Acme Corp, the one FocusBridgingExample runs against. Its headquarters is in New York and its two offices sit in Boston and Chicago, and a test holds each value:

    String city = CompanyBridge.HEADQUARTERS_CITY.get(acme);
    // "New York": read straight through the Immutables Address

    OfficeNetwork moved = CompanyBridge.HEADQUARTERS_CITY.set("Seattle", acme);
    // headquarters.city is "Seattle"; every other Address field, and acme itself, is untouched

    List<String> emails = CompanyBridge.allCompanyEmails().getAll(acme);
    // [alice@acme.com, bob@acme.com, carol@acme.com]: three records deep, across the boundary

    List<String> phones = CompanyBridge.allCompanyPhones().getAll(acme);
    // [617-555-0101, 617-555-0102, 312-555-0201]

Using the Bridges

The service layer sees one vocabulary:

public final class CompanyService {

  /** Relocate the headquarters. */
  public OfficeNetwork relocate(OfficeNetwork company, String newCity) {
    return CompanyBridge.HEADQUARTERS_CITY.set(newCity, company);
  }

  /** Every employee email, company-wide. */
  public List<String> allEmails(OfficeNetwork company) {
    return CompanyBridge.allCompanyEmails().getAll(company);
  }

  /** Standardise phone numbers across the whole company. */
  public OfficeNetwork standardisePhones(OfficeNetwork company, UnaryOperator<String> formatter) {
    return CompanyBridge.allCompanyPhones().modifyAll(formatter, company);
  }

  /** Raise salaries in one city only. */
  public OfficeNetwork raiseIn(OfficeNetwork company, String city, BigDecimal multiplier) {
    return OfficeNetworkFocus.offices()
        .filter(o -> CompanyBridge.officeCity().get(o).equals(city))
        .via(OfficeFocus.staff())
        .via(OfficeWorkerFocus.salary())
        .modifyAll(salary -> salary.multiply(multiplier), company);
  }
}

The last method is worth a second look: filter narrows the traversal by a predicate that itself reads through a bridge, and the rest of the chain carries on unchanged.

Other Libraries, Same Shape

Each library differs only in which copy strategy its generated code exposes.

Lombok @Builder(toBuilder = true):

@ImportOptics
interface LombokPersonOpticsSpec extends OpticsSpec<LombokPerson> {

  @ViaBuilder(getter = "getName", setter = "name")
  Lens<LombokPerson, String> name();
}

AutoValue:

@ImportOptics
interface AutoPersonOpticsSpec extends OpticsSpec<AutoPerson> {

  @ViaBuilder(getter = "name", toBuilder = "toBuilder", setter = "setName")
  Lens<AutoPerson, String> name();
}

Protocol Buffers, over the CustomerMessage that protoc generates for Bean-Shaped Wires:

@ImportOptics
interface CustomerMessageOpticsSpec extends OpticsSpec<CustomerMessage> {

  @ViaBuilder(getter = "getName", setter = "setName")
  Lens<CustomerMessage, String> name();
}

A repeated field is set whole by protoc's addAllSkus, and the generated lens clears the field first, as Non-Standard Naming explains. Over DispatchRequest's skus:

@ImportOptics
interface DispatchRequestOpticsSpec extends OpticsSpec<DispatchRequest> {

  @ViaBuilder(getter = "getSkusList", setter = "addAllSkus")
  Lens<DispatchRequest, List<String>> skus();
}

See Database Records with JOOQ for the strategies in full.

Organising the Bridge Layer

com.myapp.optics/
├── external/
│   ├── AddressOpticsSpec.java          # spec, generates AddressOptics
│   └── ContactDetailsOpticsSpec.java   # spec, generates ContactDetailsOptics
├── bridges/
│   ├── CompanyBridge.java              # composed constants for the company domain
│   └── OrderBridge.java
└── package-info.java                   # @ImportOptics for the simple types

Three habits keep the layer honest:

Name the bridges for the domain, not the path. employeeEmail() says what it reaches; contact().andThen(email()) says how, which is the part that should be free to change.

Document the boundary in one place. A short class comment naming the external library and its copy mechanism saves the next reader a trip through the generated sources.

Test the round trip. The external type is the part you do not control, so a lens-law check at the boundary is worth more than it is anywhere else:

@Test
void headquartersCityBridgeIsLawful() {
  LensLaws.assertLensLaws(CompanyBridge.HEADQUARTERS_CITY, acme, "Boston", "Seattle");
}

Previous: Database Records with JOOQ Next: Validation, Batching and Auditing