Module storm.foundation
Package st.orm

Interface Ref<T extends Data>

Type Parameters:
T - record type.
public interface Ref<T extends Data>
Ref records are used to represent reference to records, allowing them to be fetched from the database. This can be used to defer the fetching of records until they are actually needed. Ref records are used to represent entities, projections and regular records.

Ref records are generally used for foreign key references in entities and projections, preventing deep object graphs. Alternatively, ref records can be used outside the scope entities and projections to simply act as a factory pattern for fetching records on demand.

Ref records are effectively immutable and can be used as keys in maps and sets. Equality is based on the primary key of the record and the actual record instance will be fetched at most once.

Since:
1.3

  • Method Summary

    Modifier and Type
    Method
    Description
    static <ID, E extends Entity<ID>>
    ID
    entityId(Ref<E> ref)
    Extracts the primary key from the given entity ref returning a type-safe id.
    default T
    fetch()
    Fetches the record if it has not been fetched yet.
    T
    fetchOrNull()
    Fetches the record if it has not been fetched yet.
    T
    getOrNull()
    Returns the record if it has already been fetched, without triggering a database call.
    Object
    id()
    Returns the primary key of the record.
    boolean
    isFetchable()
    Returns whether this ref is attached to a database context and capable of fetching the record on demand.
    default boolean
    isLoaded()
    Returns whether the record has already been fetched and is available in memory.
    static <E extends Entity<?>>
    Ref<E>
    of(E entity)
    Creates a fully loaded ref instance that wraps the given entity.
    static <T extends Data, ID>
    Ref<T>
    of(Class<T> type, ID pk)
    Creates a detached ref instance for the given type and primary key.
    static <P extends Projection<ID>, ID>
    Ref<P>
    of(P projection, ID id)
    Creates a fully loaded ref instance that wraps the given projection along with its primary key.
    static <ID, P extends Projection<ID>>
    ID
    projectionId(Ref<P> ref)
    Extracts the primary key from the given projection ref returning a type-safe id.
    Class<T>
    type()
    The type of the record.
    Ref<T>
    unload()
    Returns a detached ref with the same identity but without data.

  • Method Details

    • type

      Class<T> type()
      The type of the record.
      Returns:
      the type of the record.

    • of

      static <T extends Data, ID> Ref<T> of(@Nonnull Class<T> type, @Nonnull ID pk)
      Creates a detached ref instance for the given type and primary key.

      The returned ref is not connected to a database context. Calling fetch() or fetchOrNull() on a detached ref will return null since there is no database connection available to retrieve the record.

      Type Parameters:
      T - the type of the record, which must extend Data.
      ID - the type of the primary key.
      Parameters:
      type - the class of the record.
      pk - the primary key of the record.
      Returns:
      a detached ref instance for the given type and primary key.

    • of

      static <E extends Entity<?>> Ref<E> of(@Nonnull E entity)
      Creates a fully loaded ref instance that wraps the given entity.
      Type Parameters:
      E - the type of the entity, which must extend Record and implement Entity.
      Parameters:
      entity - the fully loaded entity to wrap in a ref.
      Returns:
      a fully loaded ref instance for the provided entity.

    • of

      static <P extends Projection<ID>, ID> Ref<P> of(@Nonnull P projection, @Nonnull ID id)
      Creates a fully loaded ref instance that wraps the given projection along with its primary key.
      Type Parameters:
      P - the type of the projection.
      ID - the type of the primary key.
      Parameters:
      projection - the fully loaded projection to wrap in a ref.
      id - the primary key of the projection.
      Returns:
      a fully loaded ref instance for the provided projection.

    • entityId

      static <ID, E extends Entity<ID>> ID entityId(@Nonnull Ref<E> ref)
      Extracts the primary key from the given entity ref returning a type-safe id.
      Type Parameters:
      ID - the id type.
      E - the entity type.
      Parameters:
      ref - ref to extract the primary key from.
      Returns:
      the primary key of the specified ref.

    • projectionId

      static <ID, P extends Projection<ID>> ID projectionId(@Nonnull Ref<P> ref)
      Extracts the primary key from the given projection ref returning a type-safe id.
      Type Parameters:
      ID - the id type.
      P - the projection type.
      Parameters:
      ref - ref to extract the primary key from.
      Returns:
      the primary key of the specified ref.

    • id

      Object id()
      Returns the primary key of the record.

      This method is provided for convenience. If the type of the id is known, you can cast it to the appropriate type.

      Returns:
      the primary key as an Object.

    • getOrNull

      @Nullable T getOrNull()
      Returns the record if it has already been fetched, without triggering a database call.
      Returns:
      the record if already loaded, or null if not yet fetched.
      Since:
      1.7

    • fetch

      default T fetch()
      Fetches the record if it has not been fetched yet. The record will be fetched at most once.

      Within a transaction, this method may return the same instance as other retrieval operations for the same primary key without querying the database, depending on the transaction isolation level.

      Returns:
      the fetched record.
      Throws:
      PersistenceException - if the record is not available and the Ref is not attached.

    • fetchOrNull

      @Nullable T fetchOrNull()
      Fetches the record if it has not been fetched yet. Returns null if the record is not available and the Ref is not attached.

      Within a transaction, this method may return the same instance as other retrieval operations for the same primary key without querying the database, depending on the transaction isolation level.

      Returns:
      the fetched record, or null if the record is not available and the Ref is not attached.
      Since:
      1.7

    • isFetchable

      boolean isFetchable()
      Returns whether this ref is attached to a database context and capable of fetching the record on demand.

      A fetchable ref has access to a database connection and can attempt to retrieve the record when fetch() or fetchOrNull() is called. A non-fetchable (detached) ref can only return data that was already loaded at the time of its creation.

      Note that this method indicates the capability to fetch, not a guarantee of success. A fetchable ref may still fail to retrieve a record if it has been deleted from the database or if the connection encounters an error.

      Returns:
      true if this ref can attempt to fetch from the database, false if it is detached.
      Since:
      1.7

    • isLoaded

      default boolean isLoaded()
      Returns whether the record has already been fetched and is available in memory.

      This method does not trigger a database call. It simply checks if the record is currently cached.

      Returns:
      true if the record is loaded and available via getOrNull(), false otherwise.
      Since:
      1.7

    • unload

      Ref<T> unload()
      Returns a detached ref with the same identity but without data.

      The returned ref is not attached to a database context. Calling fetch() on the returned ref will fail since there is no database connection to recover the data.

      For refs that are already detached and unloaded, this method may return the same instance.

      Returns:
      a detached ref with the same type and primary key but without cached data.