Package in.co.akshitbansal.springwebquery.annotation

Annotation Interface FieldMapping

@Retention(RUNTIME) @Target({}) public @interface FieldMapping
Defines a mapping between an API-facing field name and an actual entity field name.

This annotation is used within WebQuery.fieldMappings() to create aliases for entity fields in filtering and sorting requests. It allows clients to use simpler or more intuitive names while mapping them to the actual field names on the entity.

These mappings are used by entity-aware query resolution (WebQuery.dtoClass() is void.class). When a DTO contract is configured, path translation is handled through MapsTo on DTO fields.

Example usage:


 @GetMapping("/users")
 @WebQuery(
     entityClass = User.class,
     fieldMappings = {
         @FieldMapping(name = "id", field = "userId"),
         @FieldMapping(name = "fullName", field = "profile.name")
     }
 )
 public List<User> search(
     @RsqlSpec Specification<User> spec,
     @RestrictedPageable Pageable pageable
 ) {
     return userRepository.findAll(spec);
 }

In the example above, clients can use id==123 or fullName==John in their RSQL queries, which will be translated to userId==123 and profile.name==John respectively.

See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    field
    The actual field name or path on the entity.
    String
    name
    The alias name to use in API query strings.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    allowOriginalFieldName
    Whether to allow the use of the original field name in addition to the alias.

  • Element Details

    • name

      String name
      The alias name to use in API query strings.

      This is the name that clients will use when constructing their queries.

      Returns:
      the query parameter field name

    • field

      String field
      The actual field name or path on the entity.

      This can be a simple field name (e.g., "userId") or a nested path using dot notation (e.g., "profile.name").

      Returns:
      the entity field name or path

    • allowOriginalFieldName

      boolean allowOriginalFieldName
      Whether to allow the use of the original field name in addition to the alias.

      When false (default), only the alias name defined in name() can be used in entity-aware filter and sort expressions. When true, both the alias and the original field name are allowed.

      Returns:
      true if the original field name should remain usable, false to enforce exclusive use of the alias
      Default:
      false