Module storm
Package st.orm

Interface Ref<T extends Record>

Type Parameters:
T - record type.
All Known Implementing Classes:
AbstractRef
public interface Ref<T extends Record>
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 Record & Entity<ID>>
    ID
    entityId(Ref<E> ref)
    Extracts the primary key from the given entity ref returning a type-safe id.
    T
    fetch()
    Fetches the record from the database if the record has not been fetched yet.
    Object
    id()
    Returns the primary key of the record.
    default boolean
    isNull()
    Returns true if the ref instance represents a null value.
    static <E extends Record & Entity<?>>
    Ref<E>
    of(E entity)
    Creates a fully loaded ref instance that wraps the given entity.
    static <P extends Record & 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 <T extends Record>
    Ref<T>
    ofNull()
    Creates a ref instance with a null value.
    static <E extends Record & Entity<?>>
    Ref<E>
    ofNullable(E entity)
    Creates a ref instance with the specified entity, if non-null, otherwise returns a null ref instance.
    static <P extends Record & Projection<ID>, ID>
    Ref<P>
    ofNullable(P projection, ID id)
    Creates a ref instance with the specified projection and id, if both non-null, otherwise returns a null ref instance.
    static <ID, P extends Record & Entity<ID>>
    ID
    projectionId(Ref<P> ref)
    Extracts the primary key from the given projection ref returning a type-safe id.
    void
    unload()
    Unloads the entity from memory, if applicable.

  • Method Details

    • ofNull

      static <T extends Record> Ref<T> ofNull()
      Creates a ref instance with a null value. This can be used to represent a null value for a foreign key reference.
      Type Parameters:
      T - record type.
      Returns:
      ref instance.

    • ofNullable

      static <E extends Record & Entity<?>> Ref<E> ofNullable(@Nullable E entity)
      Creates a ref instance with the specified entity, if non-null, otherwise returns a null ref instance.
      Type Parameters:
      E - record type.
      Parameters:
      entity - the entity to wrap in a ref, or null if no entity is provided.
      Returns:
      ref instance.

    • of

      static <E extends Record & Entity<?>> Ref<E> of(@Nonnull E entity)
      Creates a fully loaded ref instance that wraps the given entity.

      This method creates a ref for an entity that is already fully loaded. The returned ref is considered immutable; calling unload() on it is a no-op, as the entity cannot be re-fetched.

      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.

    • ofNullable

      static <P extends Record & Projection<ID>, ID> Ref<P> ofNullable(@Nullable P projection, @Nullable ID id)
      Creates a ref instance with the specified projection and id, if both non-null, otherwise returns a null ref instance.
      Type Parameters:
      P - the type of the projection.
      ID - the type of the primary key.
      Parameters:
      projection - the projection to wrap in a ref, or null if no projection is provided.
      id - the primary key of the projection, or null if no primary key is provided.
      Returns:
      ref instance.

    • of

      static <P extends Record & 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.

      This method creates a ref for a projection that is already fully loaded. The provided projection and its id are used to form the ref instance. Similar to entity refs, calling unload() on this ref is a no-op because the projection is immutable and cannot be re-fetched.

      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 Record & 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 Record & Entity<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.

    • isNull

      default boolean isNull()
      Returns true if the ref instance represents a null value.
      Returns:
      true if the ref instance represents a null value.

    • 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.

    • fetch

      T fetch()
      Fetches the record from the database if the record has not been fetched yet. The record will be fetched at most once.
      Returns:
      the fetched record.

    • unload

      void unload()
      Unloads the entity from memory, if applicable.

      For refs that support lazy-loading, this method clears the cached record to free memory. However, for fully loaded or immutable refs (such as refs generated via of(Record) and of(Record, Object)), this method is a no-op because the record cannot be re-fetched. In such cases, calling unload has no effect.