Module storm.foundation
Package st.orm

Interface Metamodel<T extends Data,E>

Type Parameters:
T - the root table type (the entity from which the path originates).
E - the field type of the designated element.
All Superinterfaces:
Navigable<T,E>
All Known Subinterfaces:
Metamodel.Key<T,E>, TypedMetamodel<T,E,V>
All Known Implementing Classes:
AbstractKeyMetamodel, AbstractMetamodel, Metamodel.KeyDelegate
public interface Metamodel<T extends Data,E> extends Navigable<T,E>
The metamodel provides type-safe references to entity fields for use in queries. Generated metamodel classes (e.g., User_ for a User entity) contain static fields representing each entity field, enabling compile-time verification of field references.

Nested Paths (Fully Qualified)

Nested paths traverse from the root entity through relationships by chaining field accessors: 


 // Traverse User → City → Country → name
 User_.city.country.name

Nested paths are always unambiguous because they explicitly specify the traversal from the root entity. Storm automatically generates the necessary JOINs based on the path.

Short Form

Short form references a table's metamodel directly without specifying the path: 


 // Reference Country directly
 Country_.name

Short form works only when the table appears exactly once in the entity graph. If the table is referenced in multiple places, Storm cannot determine which occurrence you mean and throws an exception.

Short form is also used to reference tables added via custom joins, since those tables are not reachable through nested paths.

Path Resolution

When resolving a metamodel reference, Storm follows this order:

  1. Nested path — If a path is specified (e.g., User_.city.country), use the alias for that specific traversal
  2. Unique table lookup — If short form (e.g., Country_), check if the table appears exactly once in the entity graph or registered joins
  3. Error — If multiple paths exist, throw an exception indicating the ambiguity
Since:
1.2

  • Method Details

    • root

      static <T extends Data> Metamodel<T,T> root(Class<T> table)
      Creates a new metamodel for the given record type.
      Type Parameters:
      T - the root table type.
      Parameters:
      table - the root table to create the metamodel for.
      Returns:
      a new metamodel for the given record type.

    • of

      static <T extends Data, E> Metamodel<T,E> of(Class<T> rootTable, String path)
      Creates a new metamodel for the given root rootTable and path.

      This method is typically used to manually create a metamodel for a component of a record, which can be useful in cases where the metamodel cannot be generated automatically, for example, local records.

      Type Parameters:
      T - the root rootTable type.
      E - the record component type of the designated component.
      Parameters:
      rootTable - the root rootTable to create the metamodel for.
      path - a dot separated path starting from the root table.
      Returns:
      a new metamodel for the given root rootTable and path.
      Throws:
      PersistenceException - if the metamodel cannot be created for the root rootTable and path.

    • table

      Metamodel<T,? extends Data> table()
      Returns the table that holds the column to which this metamodel is pointing. If the metamodel points to an inline record, the table is the parent table of the inline record. If the metamodel is a root metamodel, the root table is returned.
      Specified by:
      table in interface Navigable<T extends Data,E>
      Returns:
      the table that holds the column to which this metamodel is pointing.

    • getValue

      @Nullable Object getValue(T record)
      Extracts the value from the given record as specified by this metamodel.

      The returned value may be null if this metamodel represents a nullable field or if any parent metamodel in the access path resolves to null (for example, when navigating through an optional or nullable nested record).

      Implementations may return a non-null value, but callers must not rely on that unless they statically know they are using a non-null metamodel variant.

      Parameters:
      record - the root record from which the value is extracted.
      Returns:
      the extracted value, or null if the value cannot be resolved.
      Since:
      1.7

    • isIdentical

      boolean isIdentical(T a, T b)
      Checks whether the value extracted from a is identical to the value extracted from b.

      Semantics: This method performs an identity comparison on the extracted field value. It returns true if and only if both extracted values refer to the same object instance.

      This operation is only meaningful for reference-typed fields. It is not defined for primitive-typed fields.

      Performance guarantees:

      • No boxing or unboxing is performed.
      • No value coercion or conversion is performed.
      • No equals(...) or comparator logic is used.
      Parameters:
      a - the instance from which the left-hand value is extracted, must not be null.
      b - the instance from which the right-hand value is extracted, must not be null.
      Returns:
      true if both extracted values are the same object instance.
      Since:
      1.7

    • isSame

      boolean isSame(T a, T b)
      Checks whether the value extracted from a is the same as the value extracted from b.

      Semantics: This method performs a value comparison on the extracted field value. The comparison is defined by the field type:

      • For primitive-typed fields, values are compared using ==.
      • For reference-typed fields, values are compared using their defined value semantics (for example equals(...) or an equivalent comparator).

      Performance guarantees:

      • No boxing or unboxing is performed.
      • No identity comparison is performed.
      • The comparison operates directly on the extracted values.
      Parameters:
      a - the instance from which the left-hand value is extracted, must not be null.
      b - the instance from which the right-hand value is extracted, must not be null.
      Returns:
      true if both extracted values are equal by value.
      Since:
      1.7

    • key

      static <T extends Data, E> Metamodel.Key<T,E> key(Metamodel<T,E> metamodel)
      Returns a Key view of the given metamodel. If metamodel already implements Metamodel.Key, it is returned as-is; otherwise it is wrapped in a delegate that implements Key.

      This factory is intended for cases where the generated metamodel does not carry the Key marker (for example, composite primary keys or dynamically constructed metamodels), or where a column is known to produce unique values in a particular query context (for example, a column that appears in a GROUP BY clause).

      Important: callers are responsible for ensuring that the column produces unique values in the context where the key is used. Using a non-unique column as a keyset pagination key will silently skip rows when duplicate values span page boundaries.

      The returned key reports Metamodel.Key.isNullable() from the underlying field: a nullable field stays nullable when viewed as a key, so keyset pagination keeps rejecting it.

      Type Parameters:
      T - the root table type.
      E - the field type.
      Parameters:
      metamodel - the metamodel to view as a key.
      Returns:
      a Key instance backed by the given metamodel.
      Since:
      1.9