Module jakarta.data

Annotation Interface StaticMetamodel


@Documented @Retention(RUNTIME) @Target(TYPE) public @interface StaticMetamodel

Annotates a class which serves as a static metamodel for an entity, enabling type-safe access to entity attribute names and related objects such as instances of Sorts for an attribute. A metamodel class contains one or more public static fields corresponding to persistent fields of the entity class. The type of each of these fields must be either String, Attribute, or a subinterface of Attribute defined in this package.

Jakarta Data defines the following conventions for static metamodel classes:

  • The metamodel class can be an interface or concrete class.
  • The name of the static metamodel class should consist of underscore (_) followed by the entity class name.
  • Fields of type String should be named with all upper case.
  • Fields of type Attribute should be named in lower case or mixed case.

For example, for the following entity,

 @Entity
 public class Person {
     @Id
     public long ssn;

     @Embedded
     public Name name;

     public int yearOfBirth;
 }

 @Embeddable
 public class Name {
     public String first;
     public String last;
 }
 

An application programmer may define a static metamodel as follows,

 @StaticMetamodel(Person.class)
 public interface _Person {
     String SSN = "ssn";
     String NAME = "name";
     String NAME_FIRST = "name.first";
     String NAME_LAST = "name.last";
     String YEAROFBIRTH = "yearOfBirth";

     SortableAttribute<Person> ssn = new SortableAttributeRecord<>(SSN);
     Attribute<Person> name = new AttributeRecord<>(NAME);
     TextAttribute<Person> name_first = new TextAttributeRecord<>(NAME_FIRST);
     TextAttribute<Person> name_last = new TextAttributeRecord<>(NAME_LAST);
     SortableAttribute<Person> yearOfBirth = new SortableAttributeRecord<>(YEAROFBIRTH);
 }
 

And use it to refer to entity attributes in a type-safe manner,

 Order<Person> order =
         Order.by(_Person.yearOfBirth.desc(),
                  _Person.name_last.asc(),
                  _Person.name_first.asc(),
                  _Person.ssn.asc());
 

Alternatively, an annotation processor might generate static metamodel classes for entities at compile time. The generated classes must be annotated with the @Generated annotation. The fields may be statically initialized, or they may be initialized by the provider during system initialization. In the first case, the fields are declared final and the metamodel class can be an interface. In the second case, the fields are declared non-final and volatile and the metamodel class must be a concrete class.

In cases where multiple Jakarta Data providers provide repositories for the same entity type, no guarantees are made of the order in which the Jakarta Data providers attempt to initialize the fields of the static metamodel class for that entity.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    An entity class.
  • Element Details

    • value

      Class<?> value
      An entity class.
      Returns:
      the entity class.