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 Known Subinterfaces:
Metamodel.Key<T,E>
All Known Implementing Classes:
AbstractKeyMetamodel, AbstractMetamodel, Metamodel.KeyDelegate
public interface Metamodel<T extends Data,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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Metamodel.Key<T extends Data,E>
    Marker interface for metamodel fields that correspond to columns known to be unique.
    static final record 
    Metamodel.KeyDelegate<T extends Data,E>
    Delegating wrapper that adds the Metamodel.Key marker to an existing Metamodel instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Metamodel<? extends Data,E>
    canonical()
    Returns the canonical metamodel for the field represented by this metamodel.
    String
    field()
    Returns the field name.
    default String
    fieldPath()
    Returns the field path.
    Class<E>
    fieldType()
    Returns the field type of the designated element.
    default List<Metamodel<T,?>>
    flatten()
    Returns a flat list of leaf metamodels for this metamodel.
    Object
    getValue(T record)
    Extracts the value from the given record as specified by this metamodel.
    boolean
    isColumn()
    Returns true if the metamodel corresponds to a database column, returns false otherwise, for example, if the metamodel refers to the root metamodel or an inline record.
    boolean
    isIdentical(T a, T b)
    Checks whether the value extracted from a is identical to the value extracted from b.
    boolean
    isInline()
    Returns true if the metamodel corresponds to an inline record, returns false otherwise.
    boolean
    isSame(T a, T b)
    Checks whether the value extracted from a is the same as the value extracted from b.
    static <T extends Data, E>
    Metamodel.Key<T,E>
    key(Metamodel<T,E> metamodel)
    Returns a Key view of the given metamodel.
    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.
    String
    path()
    Returns the path to the database table.
    Class<T>
    root()
    Returns the root metamodel.
    static <T extends Data>
    Metamodel<T,T>
    root(Class<T> table)
    Creates a new metamodel for the given record type.
    Metamodel<T,? extends Data>
    table()
    Returns the table that holds the column to which this metamodel is pointing.
    default Class<? extends Data>
    tableType()
    Returns the type of the table that holds the column to which this metamodel is pointing.

  • Method Details

    • root

      static <T extends Data> Metamodel<T,T> root(@Nonnull 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(@Nonnull Class<T> rootTable, @Nonnull 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.

    • canonical

      default Metamodel<? extends Data,E> canonical()
      Returns the canonical metamodel for the field represented by this metamodel. The resulting metamodel captures only the table type and field.

      The result is independent of the position of this field within a table graph. This makes the normalized form suitable for equality checks, for example, to determine whether two metamodels refer to the same underlying field.

      Returns:
      the canonical metamodel for this metamodel.
      Since:
      1.8

    • isColumn

      boolean isColumn()
      Returns true if the metamodel corresponds to a database column, returns false otherwise, for example, if the metamodel refers to the root metamodel or an inline record.

      Note that a column can also be a table, for example, in the case of a foreign key.

      Returns:
      true if this metamodel maps to a column, false otherwise.

    • isInline

      boolean isInline()
      Returns true if the metamodel corresponds to an inline record, returns false otherwise.
      Returns:
      true if this metamodel maps to an inline record, false otherwise.

    • root

      Class<T> root()
      Returns the root metamodel. This is typically the table specified in the FROM clause of a query.
      Returns:
      the root metamodel.

    • 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.
      Returns:
      the table that holds the column to which this metamodel is pointing.

    • tableType

      default Class<? extends Data> tableType()
      Returns the type of the table that holds the column to which this metamodel is pointing.
      Returns:
      the type of the table that holds the column to which this metamodel is pointing.
      Since:
      1.7

    • path

      String path()
      Returns the path to the database table.
      Returns:
      path to the database table.

    • fieldType

      Class<E> fieldType()
      Returns the field type of the designated element.
      Returns:
      the field type of the designated element.

    • field

      String field()
      Returns the field name.
      Returns:
      field name.

    • fieldPath

      default String fieldPath()
      Returns the field path.
      Returns:
      field path.

    • getValue

      Object getValue(@Nonnull 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

    • flatten

      default List<Metamodel<T,?>> flatten()
      Returns a flat list of leaf metamodels for this metamodel. If this metamodel is not an inline record, it returns a singleton list containing this. If it is an inline record, it recursively expands all nested inline records and returns the individual column metamodels.

      This method is useful for operations like ORDER BY and GROUP BY, where inline records need to be expanded into their individual columns.

      Returns:
      a list of leaf metamodels.
      Since:
      1.9

    • isIdentical

      boolean isIdentical(@Nonnull T a, @Nonnull 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(@Nonnull T a, @Nonnull 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(@Nonnull 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.

      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