Module storm.foundation

Package st.orm

Interface Projection<ID>

Type Parameters:

ID - the row identity type of the projection, or Void if the projection has no primary key.

All Superinterfaces:

Data

public interface Projection<ID>
extends Data

Marker interface for record-based projections.

Usage examples:

Define a projection record based on the basket_summary_view view, with a basket_id primary key.

Java:

 @DbTable("basket_summary_view")
 record BasketSummary(@PK @FK Basket basket, int itemCount, BigDecimal totalPrice) implements Projection<Integer> {}
 

Kotlin:

 @DbTable("basket_summary_view")
 data class BasketSummary(@PK @FK val basket: Basket, val itemCount: Int, val totalPrice: BigDecimal) : Projection<Int>
 

Then, you can use the projection in a query like this:

 var baskets = ...
 List<BasketSummary> summaries = ORM(dataSource).projection(BasketSummary.class)
     .select()
     .where(baskets)  // Type-safe.
     .getResultList();
 

Or use it as a foreign key in an entity.

Java:

 record User(@PK int id, @FK("basket_id") BasketSummary basketSummary) implements Entity<Integer> {}
 

Kotlin:

 data class User(@PK val id: Int, @FK("basket_id") val basketSummary: BasketSummary) : Entity<Int>
 

Then, you can query all users having a basket with at least 1 item:

 List<User> users = ORM(dataSource).entity(User.class)
     .select()
     .where(User_.basketSummary.itemCount, GREATER_THAN, 0)   // Type-safe metamodel.
     .getResultList();
 

The ID parameter

ID is the projection's row identity type: the type the id-based operations work with, such as ProjectionRepository.findById(ID), ProjectionRepository.ref(ID) and Ref.projectionId(Ref). When the primary key component is a foreign key, the row identity is the referenced table's key rather than the component value: BasketSummary above is identified by the basket's Integer key, while its primary key component holds a Basket. Declare Projection<Void> for a projection without a primary key; the id-based operations do not apply to such projections.

Unlike Entity.id(), this interface deliberately declares no id accessor: a projection's row identity is not in general derivable from its components. It may differ in type from the primary key component, as shown above, or the identity may not be among the mapped columns at all. Operations that need the id of a projection instance therefore take it explicitly, as in Ref.of(Projection, Object).

The declared type argument is validated against the mapped primary key when the projection is used: a projection that maps a primary key must not declare Void, and the declared type must match the key's row identity type. A projection without a mapped primary key may declare a row identity type; this supports detached refs via Ref.of(Class, Object), while the id-based repository operations require the mapped key.