Module storm.java
Package st.orm.template

Interface ORMTemplate

All Superinterfaces:
QueryTemplate, RepositoryLookup, SubqueryTemplate
public interface ORMTemplate extends QueryTemplate, RepositoryLookup
The primary entry point for Storm's ORM functionality, combining SQL template query construction with repository access.

ORMTemplate extends both QueryTemplate (for constructing and executing SQL queries) and RepositoryLookup (for obtaining type-safe EntityRepository and ProjectionRepository instances). It is the central interface from which all database operations originate.

Instances are created using the static factory methods of(javax.sql.DataSource) or of(java.sql.Connection), or via the convenience methods in the Templates class. For JPA-based usage, see JpaTemplate.

Example


 ORMTemplate orm = ORMTemplate.of(dataSource);

 // Repository-based access
 EntityRepository<User, Integer> users = orm.entity(User.class);
 Optional<User> user = users.findById(42);

 // Template-based query
 List<User> result = orm.query(RAW."""
         SELECT \{User.class}
         FROM \{User.class}
         WHERE \{User_.name} = \{"Alice"}""")
     .getResultList(User.class);
See Also:

  • Method Details

    • withEntityCallback

      ORMTemplate withEntityCallback(@Nonnull EntityCallback<?> callback)
      Returns a new ORMTemplate with the specified entity callback added.

      The returned template shares the same underlying connection and configuration, but applies the given callback to entity lifecycle operations (insert, update, delete) performed through its repositories. The callback is only invoked for entities matching its type parameter. Multiple callbacks can be registered by chaining calls to this method.

      Parameters:
      callback - the entity callback to add; must not be null.
      Returns:
      a new ORMTemplate with the callback added.
      Since:
      1.9

    • withEntityCallbacks

      ORMTemplate withEntityCallbacks(@Nonnull List<EntityCallback<?>> callbacks)
      Returns a new ORMTemplate with the specified entity callbacks added.

      The returned template shares the same underlying connection and configuration, but applies the given callbacks to entity lifecycle operations (insert, update, delete) performed through its repositories. Each callback is only invoked for entities matching its type parameter.

      Parameters:
      callbacks - the entity callbacks to add; must not be null.
      Returns:
      a new ORMTemplate with the callbacks added.
      Since:
      1.9

    • validateSchema

      List<String> validateSchema()
      Validates all discovered entity and projection types against the database schema.

      Logs each validation error and returns the list of error messages. On success, logs a confirmation message and returns an empty list.

      This method requires a DataSource-backed template. Templates created from a raw Connection or EntityManager do not support schema validation.

      Returns:
      the list of validation error messages (empty on success).
      Throws:
      PersistenceException - if the template does not support schema validation.
      Since:
      1.9

    • validateSchema

      List<String> validateSchema(@Nonnull Predicate<Class<? extends Data>> filter)
      Validates discovered types matching the filter against the database schema.

      Discovers all entity and projection types via the classpath index, applies the given filter, and validates the matching types. This is useful when a single application connects to multiple datasources and only a subset of types is reachable from each connection.

      Logs each validation error and returns the list of error messages. On success, logs a confirmation message and returns an empty list.

      This method requires a DataSource-backed template. Templates created from a raw Connection or EntityManager do not support schema validation.

      Parameters:
      filter - predicate to select which discovered types to validate.
      Returns:
      the list of validation error messages (empty on success).
      Throws:
      PersistenceException - if the template does not support schema validation.
      Since:
      1.11

    • validateSchema

      List<String> validateSchema(@Nonnull Iterable<Class<? extends Data>> types)
      Validates the specified types against the database schema.

      Logs each validation error and returns the list of error messages. On success, logs a confirmation message and returns an empty list.

      This method requires a DataSource-backed template. Templates created from a raw Connection or EntityManager do not support schema validation.

      Parameters:
      types - the entity and projection types to validate.
      Returns:
      the list of validation error messages (empty on success).
      Throws:
      PersistenceException - if the template does not support schema validation.
      Since:
      1.9

    • validateSchemaOrThrow

      void validateSchemaOrThrow()
      Validates all discovered types and throws if any errors are found.

      This method requires a DataSource-backed template. Templates created from a raw Connection or EntityManager do not support schema validation.

      Throws:
      PersistenceException - if validation fails or the template does not support schema validation.
      Since:
      1.9

    • validateSchemaOrThrow

      void validateSchemaOrThrow(@Nonnull Predicate<Class<? extends Data>> filter)
      Validates discovered types matching the filter and throws if any errors are found.

      Discovers all entity and projection types via the classpath index, applies the given filter, and validates the matching types. This is useful when a single application connects to multiple datasources and only a subset of types is reachable from each connection.

      This method requires a DataSource-backed template. Templates created from a raw Connection or EntityManager do not support schema validation.

      Parameters:
      filter - predicate to select which discovered types to validate.
      Throws:
      PersistenceException - if validation fails or the template does not support schema validation.
      Since:
      1.11

    • validateSchemaOrThrow

      void validateSchemaOrThrow(@Nonnull Iterable<Class<? extends Data>> types)
      Validates the specified types and throws if any errors are found.

      This method requires a DataSource-backed template. Templates created from a raw Connection or EntityManager do not support schema validation.

      Parameters:
      types - the entity and projection types to validate.
      Throws:
      PersistenceException - if validation fails or the template does not support schema validation.
      Since:
      1.9

    • of

      static ORMTemplate of(@Nonnull DataSource dataSource)
      Returns an ORMTemplate for use with JDBC.

      This method creates an ORM repository template using the provided DataSource. It allows you to perform database operations using JDBC in a type-safe manner.

      Example usage: 

      
 DataSource dataSource = ...;
 ORMTemplate orm = ORMTemplate.of(dataSource);
 List<MyTable> otherTables = orm.query(RAW."""
         SELECT \{MyTable.class}
         FROM \{MyTable.class}
         WHERE \{MyTable_.name} = \{"ABC"}""")
     .getResultList(MyTable.class);
      Parameters:
      dataSource - the DataSource to use for database operations; must not be null.
      Returns:
      an ORMTemplate configured for use with JDBC.

    • of

      static ORMTemplate of(@Nonnull Connection connection)
      Returns an ORMTemplate for use with JDBC.

      This method creates an ORM repository template using the provided Connection. It allows you to perform database operations using JDBC in a type-safe manner.

      Note: The caller is responsible for closing the connection after usage.

      Example usage: 

      
 try (Connection connection = ...) {
     ORMTemplate orm = ORMTemplate.of(connection);
     List<MyTable> otherTables = orm.query(RAW."""
             SELECT \{MyTable.class}
             FROM \{MyTable.class}
             WHERE \{MyTable_.name} = \{"ABC"}""")
         .getResultList(MyTable.class)
 }
      Parameters:
      connection - the Connection to use for database operations; must not be null.
      Returns:
      an ORMTemplate configured for use with JDBC.

    • of

      static ORMTemplate of(@Nonnull DataSource dataSource, @Nonnull UnaryOperator<TemplateDecorator> decorator)
      Returns an ORMTemplate for use with JDBC, with a custom template decorator.

      This method creates an ORM repository template using the provided DataSource and applies the specified decorator to customize template processing behavior.

      Parameters:
      dataSource - the DataSource to use for database operations; must not be null.
      decorator - a function that transforms the TemplateDecorator to customize template processing.
      Returns:
      an ORMTemplate configured for use with JDBC.

    • of

      static ORMTemplate of(@Nonnull Connection connection, @Nonnull UnaryOperator<TemplateDecorator> decorator)
      Returns an ORMTemplate for use with JDBC, with a custom template decorator.

      This method creates an ORM repository template using the provided Connection and applies the specified decorator to customize template processing behavior.

      Note: The caller is responsible for closing the connection after usage.

      Parameters:
      connection - the Connection to use for database operations; must not be null.
      decorator - a function that transforms the TemplateDecorator to customize template processing.
      Returns:
      an ORMTemplate configured for use with JDBC.

    • of

      static ORMTemplate of(@Nonnull DataSource dataSource, @Nonnull StormConfig config)
      Returns an ORMTemplate for use with JDBC, configured with the provided StormConfig.

      The provided configuration is applied to the template instance, not as a process-wide default.

      Parameters:
      dataSource - the DataSource to use for database operations; must not be null.
      config - the Storm configuration to apply; must not be null.
      Returns:
      an ORMTemplate configured for use with JDBC.

    • of

      static ORMTemplate of(@Nonnull DataSource dataSource, @Nonnull StormConfig config, @Nonnull UnaryOperator<TemplateDecorator> decorator)
      Returns an ORMTemplate for use with JDBC, configured with the provided StormConfig and a custom template decorator.
      Parameters:
      dataSource - the DataSource to use for database operations; must not be null.
      config - the Storm configuration to apply; must not be null.
      decorator - a function that transforms the TemplateDecorator to customize template processing.
      Returns:
      an ORMTemplate configured for use with JDBC.

    • of

      static ORMTemplate of(@Nonnull Connection connection, @Nonnull StormConfig config)
      Returns an ORMTemplate for use with JDBC, configured with the provided StormConfig.

      Note: The caller is responsible for closing the connection after usage.

      Parameters:
      connection - the Connection to use for database operations; must not be null.
      config - the Storm configuration to apply; must not be null.
      Returns:
      an ORMTemplate configured for use with JDBC.

    • of

      static ORMTemplate of(@Nonnull Connection connection, @Nonnull StormConfig config, @Nonnull UnaryOperator<TemplateDecorator> decorator)
      Returns an ORMTemplate for use with JDBC, configured with the provided StormConfig and a custom template decorator.

      Note: The caller is responsible for closing the connection after usage.

      Parameters:
      connection - the Connection to use for database operations; must not be null.
      config - the Storm configuration to apply; must not be null.
      decorator - a function that transforms the TemplateDecorator to customize template processing.
      Returns:
      an ORMTemplate configured for use with JDBC.