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, Metamodel.Outer, SqlFunction.Call

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

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.
static final record	Metamodel.Outer<T extends Data,E>	A path named in the query that encloses the subquery it is used in, see outer(Navigable).

Method Summary

Modifier and Type	Method	Description
@Nullable Object	getValue(T record)	Extracts the value from the given record as specified by this metamodel.
boolean	isIdentical(T a, T b)	Checks whether the value extracted from a is identical to the value extracted from b.
static boolean	isOuter(Navigable<?,?> path)	Returns whether the path names a column of an enclosing query: a path made by outer(Navigable), a SqlFunction call on one, or a key view of one.
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.
static <T extends Data, E> Metamodel<T,E>	outer(Navigable<T,E> path)	Names the column at the given path in the query that encloses the subquery being built, as the other side of a comparison of two columns: where(Visit_.pet.id, EQUALS, outer(Pet_.id)) keeps the visits of the enclosing query's pet.
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.

Methods inherited from interface st.orm.Navigable

asMetamodel, canonical, field, fieldPath, fieldType, flatten, isColumn, isInline, path, root, tableType

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

outer

static <T extends Data,
E> Metamodel<T,E> outer(Navigable<T,E> path)

Names the column at the given path in the query that encloses the subquery being built, as the other side of a comparison of two columns: where(Visit_.pet.id, EQUALS, outer(Pet_.id)) keeps the visits of the enclosing query's pet. A path without it names the subquery's own tables, also where the subquery holds the table the enclosing query holds: the visit's own pet, which the subquery joins.

The path resolves in the nearest enclosing query that holds its table, never in the subquery itself. In a template, the path renders as its column at that occurrence.

Type Parameters:

T - the root table type.

E - the field type.

Parameters:

path - the path to the column, or columns, of the enclosing query.

Returns:

the path, named in the enclosing query.

Since:

1.16

isOuter

static boolean isOuter(Navigable<?,?> path)

Returns whether the path names a column of an enclosing query: a path made by outer(Navigable), a SqlFunction call on one, or a key view of one.

Parameters:

path - the path to inspect.

Returns:

true if the path resolves in an enclosing query, false otherwise.

Since:

1.16