Annotation Type DtoPath

@Target({FIELD,METHOD}) @Retention(CLASS) public @interface DtoPath
Mark a DTO field or accessor to be populated from an entity property path other than its own name, or from a nested/flattened path on the source entity graph.

Used with generated entity-to-DTO graph mapping (see query.mapTo(SomeDto.class)). By default a DTO property is matched to the source entity property (or nested DTO) of the same name. @DtoPath overrides that default, allowing the DTO property to be renamed and/or flattened from a nested path: 

public class CustomerDto {
  Integer id;
  String name;

  @DtoPath("billingAddress.line1")
  String billingLine1;   // flattened from a nested ToOne relationship
}

This is purely a compile-time / codegen-time hint consumed when generating the DTO mapper and deriving the query's fetch spec - the DTO itself remains a plain, framework-free type with no runtime dependency on this annotation.

When the path traverses an intermediate relation that can be null (e.g. billingAddress above may itself be null) and the DTO field's type is a Java primitive (e.g. long, int, boolean), the generated mapper defaults the value to the primitive's zero-equivalent (0/false/etc.) rather than throwing - set failOnNull() to true to instead throw a clear exception when that happens.

Every segment of the path must name a real, fetchable Ebean bean property (one with a backing field) - if a segment is instead a computed/derived getter (e.g. a hand-written method deriving a value from other properties, with no backing field of its own), its own data dependencies can't be inferred from the path alone, so requires() must explicitly name the real entity paths that need to be fetched for it to execute safely without triggering a lazy load: 

@DtoPath(value = "currentMachine.organisationMachine.registrationPlate",
  requires = "currentMachine.organisationMachines")
String machineLabel;   // getOrganisationMachine() derives its result from organisationMachines

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    The source property path to map from, using dot-notation (e.g.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    failOnNull
    For a primitive-typed DTO field whose path traverses a nullable intermediate relation, set to true to throw a clear exception when that relation is null at runtime, rather than the default of silently defaulting to the primitive's zero-equivalent value.
    String[]
    requires
    Real entity paths (dot-notation, same convention as value()) that must be fetched to support a computed/derived getter segment within value() - required whenever a segment of the path has no backing field, since its data dependencies can't otherwise be inferred.

  • Element Details

    • value

      String value
      The source property path to map from, using dot-notation (e.g. "billingAddress.line1").

    • failOnNull

      boolean failOnNull
      For a primitive-typed DTO field whose path traverses a nullable intermediate relation, set to true to throw a clear exception when that relation is null at runtime, rather than the default of silently defaulting to the primitive's zero-equivalent value.

      Has no effect for non-primitive (reference-typed) DTO fields - null is always a valid result for those regardless of this setting.

      Default:
      false

    • requires

      String[] requires
      Real entity paths (dot-notation, same convention as value()) that must be fetched to support a computed/derived getter segment within value() - required whenever a segment of the path has no backing field, since its data dependencies can't otherwise be inferred. Ignored (and unnecessary) when every segment names a real, fetchable property.

      If the computed getter genuinely needs nothing extra fetched (e.g. it only touches properties already guaranteed to be selected), set requires = {} explicitly to confirm that - as opposed to omitting requires entirely, which is treated as "not yet considered" and fails the build with a clear compile error.

      Default:
      {}