Annotation Type DtoMapping

@Target({PACKAGE,MODULE}) @Retention(SOURCE) @Repeatable(DtoMapping.List.class) public @interface DtoMapping
Register a source entity type and a target DTO type as a pair for which a DTO graph mapper should be generated (see query.mapTo(SomeDto.class)).

Declared on a neutral holder - typically a package-info.java - rather than on the DTO or the entity itself. This matters because:

  • The DTO type is often owned/generated elsewhere (e.g. from an OpenAPI spec) and shouldn't need to know about, or be annotated with, an internal persistence/entity type.
  • One entity may be the source for several different DTOs (e.g. a summary vs. a detail view), and one entity/DTO pair may need re-registering from multiple consuming modules.
@DtoMapping(source = Customer.class, target = CustomerDto.class)
@DtoMapping(source = Contact.class, target = ContactDto.class)
package org.example.dto;

Purely a compile-time / codegen-time trigger - never needed at runtime, so this annotation itself carries no runtime footprint (source retention).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    DtoMapping.Builder
    Target construction strategy - see builder().
    static @interface 
    DtoMapping.List
    Container annotation allowing @DtoMapping to be repeated on the same element.
    static enum 
    DtoMapping.Setter
    Target construction strategy - see setter().

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    Class<?>
    source
    The source entity (or embeddable) type to map from.
    Class<?>
    target
    The target DTO type to map to.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    DtoMapping.Builder
    builder
    Controls whether the generated mapper constructs the target DTO via a positional constructor call or via a detected builder (a static Target.builder() factory returning a type with fluent per-property setters and a build() method - the shape avaje-recordbuilder's @RecordBuilder generates).
    String[]
    exclude
    Nested ToOne/ToMany DTO property names (declared field names on the target, not source paths), or non-primitive scalar property names (e.g. a @DtoConvert-backed List property with no registered nested DTO mapping of its own), to exclude from this named variant - only meaningful when name() is non-empty.
    String
    mapperName
    Override the simple class name of the generated mapper.
    String
    mapperPackage
    Override the package the generated mapper is written to.
    String
    name
    Name this mapping as a named variant of an already-registered (source, target) pair, rather than the primary/base mapping.
    DtoMapping.Setter
    setter
    Controls whether the generated mapper constructs the target DTO via a detected setter-based (mutable JavaBean) construction path - a public no-arg constructor plus a setXxx(propertyType) setter for every mapped property, the shape JAXB/XSD-generated legacy SOAP types commonly follow - rather than a positional constructor call or a builder chain.

  • Element Details

    • source

      Class<?> source
      The source entity (or embeddable) type to map from.

    • target

      Class<?> target
      The target DTO type to map to.

    • mapperPackage

      String mapperPackage
      Override the package the generated mapper is written to.

      Defaults to the target DTO's own package - unless the source and/or target type belongs to a different module than the one being processed, in which case the generated mapper is placed in a package derived from the processing module's own name instead, to avoid a Java module "split package" violation (the same fallback avaje-jsonb uses for @Json.Import of external types).

      Default:
      ""

    • mapperName

      String mapperName
      Override the simple class name of the generated mapper.

      Defaults to the target DTO's own simple name suffixed with Mapper (e.g. a mapping targeting Fleet generates FleetMapper). Set this when that default name would clash with an existing hand-written class of the same name (e.g. a legacy mapper still in use elsewhere that can't be renamed/removed yet) - the generated mapper can then be given a distinct name (and, if needed, paired with mapperPackage() too) so both classes can coexist.

      Default:
      ""

    • name

      String name
      Name this mapping as a named variant of an already-registered (source, target) pair, rather than the primary/base mapping.

      The same (source, target) pair may be declared more than once - one base declaration (leaving name() empty) plus any number of named variants - all generated into a single shared mapper class (one class per target, not one per variant). Each variant excludes one or more nested ToOne/ToMany DTO properties (see exclude()) from both its own fetchGroup and its mapped output, letting the same target DTO type be populated in more than one shape (e.g. with vs. without an expensive nested collection) without generating a second target type.

      The generated mapper exposes each variant as a same-named method returning its own DtoMapper<SOURCE, TARGET> view, e.g. name = "noFleets" generates a noFleets() accessor method - pass its result to query.mapTo(Target.class, mapper.noFleets()).

      Default:
      ""

    • exclude

      String[] exclude
      Nested ToOne/ToMany DTO property names (declared field names on the target, not source paths), or non-primitive scalar property names (e.g. a @DtoConvert-backed List property with no registered nested DTO mapping of its own), to exclude from this named variant - only meaningful when name() is non-empty. Excluded properties are omitted from this variant's fetchGroup (no fetch/join/select is issued for them) and mapped to null (a single-valued property) or an empty list (a List-typed property) in this variant's output, rather than being populated from the source graph.

      A primitive-typed scalar property cannot be excluded - there's no type-safe "absent" value for it.

      Default:
      {}

    • builder

      DtoMapping.Builder builder
      Controls whether the generated mapper constructs the target DTO via a positional constructor call or via a detected builder (a static Target.builder() factory returning a type with fluent per-property setters and a build() method - the shape avaje-recordbuilder's @RecordBuilder generates).
      Default:
      AUTO

    • setter

      DtoMapping.Setter setter
      Controls whether the generated mapper constructs the target DTO via a detected setter-based (mutable JavaBean) construction path - a public no-arg constructor plus a setXxx(propertyType) setter for every mapped property, the shape JAXB/XSD-generated legacy SOAP types commonly follow - rather than a positional constructor call or a builder chain. A matching setter may either return void or return the target type itself (fluent-style, e.g. public Target setXxx(...) { ...; return this; }) - either way the generated code calls it as a plain statement and ignores any return value.
      Default:
      AUTO