Module storm
Package st.orm

Interface Query

All Known Subinterfaces:
PreparedQuery
public interface Query
Abstraction for DQL (Data Query Language) statements, such as SELECT queries and DML (Data Manipulation Language) statements, such as INSERT, UPDATE and DELETE statements

  • Method Summary

    Modifier and Type
    Method
    Description
    int[]
    executeBatch()
    Execute a batch of commands.
    int
    executeUpdate()
    Execute a command, such as an INSERT, UPDATE or DELETE statement.
    default Optional<Object[]>
    getOptionalResult()
    Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
    default <T> Optional<T>
    getOptionalResult(Class<T> type)
    Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
    default <T extends Record>
    List<Ref<T>>
    getRefList(Class<T> type, Class<?> pkType)
    Execute a SELECT query and return the resulting rows as a list of ref instances.
    <T extends Record>
    Stream<Ref<T>>
    getRefStream(Class<T> type, Class<?> pkType)
    Execute a SELECT query and return the resulting rows as a stream of ref instances.
    default <T, R> R
    getResult(Class<T> type, ResultCallback<T,R> callback)
    Execute a SELECT query and return the resulting rows as a stream of row instances.
    default <R> R
    getResult(ResultCallback<Object[],R> callback)
    Execute a SELECT query and return the resulting rows as a stream of row instances.
    default long
    getResultCount()
    Returns the number of results of this query.
    default List<Object[]>
    getResultList()
    Execute a SELECT query and return the resulting rows as a list of row instances.
    default <T> List<T>
    getResultList(Class<T> type)
    Execute a SELECT query and return the resulting rows as a list of row instances.
    Stream<Object[]>
    getResultStream()
    Execute a SELECT query and return the resulting rows as a stream of row instances.
    <T> Stream<T>
    getResultStream(Class<T> type)
    Execute a SELECT query and return the resulting rows as a stream of row instances.
    default Object[]
    getSingleResult()
    Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
    default <T> T
    getSingleResult(Class<T> type)
    Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
    boolean
    isVersionAware()
    Returns true if the query is version aware, false otherwise.
    PreparedQuery
    prepare()
    Prepares the query for execution.
    Query
    safe()
    Returns a new query that is marked as safe.

  • Method Details

    • prepare

      PreparedQuery prepare()
      Prepares the query for execution.

      Queries are normally constructed in a lazy fashion, unlike prepared queries which are constructed eagerly. Prepared queries allow the use of bind variables and enable reading generated keys after row insertion.

      Note that the prepared query must be closed after usage to prevent resource leaks. As the prepared query is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Returns:
      the prepared query.
      Throws:
      PersistenceException - if the query preparation fails.

    • safe

      Query safe()
      Returns a new query that is marked as safe. This means that dangerous operations, such as DELETE and UPDATE without a WHERE clause, will be allowed.
      Returns:
      a new query that is marked as safe.
      Since:
      1.2

    • getSingleResult

      default Object[] getSingleResult()
      Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getOptionalResult

      default Optional<Object[]> getOptionalResult()
      Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list, or an empty optional if there is no result.
      Throws:
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getResultCount

      default long getResultCount()
      Returns the number of results of this query.
      Returns:
      the total number of results of this query as a long value.
      Throws:
      PersistenceException - if the query operation fails due to underlying database issues, such as connectivity.

    • getSingleResult

      default <T> T getSingleResult(@Nonnull Class<T> type)
      Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
      Parameters:
      type - the type of the result.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getOptionalResult

      default <T> Optional<T> getOptionalResult(@Nonnull Class<T> type)
      Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
      Parameters:
      type - the type of the result.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list, or an empty optional if there is no result.
      Throws:
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getResultList

      default List<Object[]> getResultList()
      Execute a SELECT query and return the resulting rows as a list of row instances.

      Each element in the list represents a row in the result, where the columns of the row corresponds to the order of values in the row array.

      Returns:
      the result list.
      Throws:
      PersistenceException - if the query fails.

    • getResultList

      default <T> List<T> getResultList(@Nonnull Class<T> type)
      Execute a SELECT query and return the resulting rows as a list of row instances.

      Each element in the list represents a row in the result, where the columns of the row are mapped to the constructor arguments of the specified type.

      Parameters:
      type - the type of the result.
      Returns:
      the result list.
      Throws:
      PersistenceException - if the query fails.

    • getRefList

      default <T extends Record> List<Ref<T>> getRefList(@Nonnull Class<T> type, @Nonnull Class<?> pkType)
      Execute a SELECT query and return the resulting rows as a list of ref instances.

      Each element in the list represents a row in the result, where the columns of the row are mapped to the constructor arguments primary key type.

      Parameters:
      type - the type of the results that are being referenced.
      Returns:
      the result list.
      Throws:
      PersistenceException - if the query fails.
      Since:
      1.3

    • getResultStream

      Stream<Object[]> getResultStream()
      Execute a SELECT query and return the resulting rows as a stream of row instances.

      Each element in the stream represents a row in the result, where the columns of the row corresponds to the order of values in the row array.

      The resulting stream is lazily loaded, meaning that the records are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of records.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Returns:
      a stream of results.
      Throws:
      PersistenceException - if the query operation fails due to underlying database issues, such as connectivity.

    • getResult

      default <R> R getResult(@Nonnull ResultCallback<Object[],R> callback)
      Execute a SELECT query and return the resulting rows as a stream of row instances.

      Each element in the stream represents a row in the result, where the columns of the row corresponds to the order of values in the row array.

      This method ensures efficient handling of large data sets by loading entities only as needed. It also manages lifecycle of the callback stream, automatically closing the stream after processing to prevent resource leaks.

      Returns:
      the result stream.
      Throws:
      PersistenceException - if the query fails.

    • getResultStream

      <T> Stream<T> getResultStream(@Nonnull Class<T> type)
      Execute a SELECT query and return the resulting rows as a stream of row instances.

      Each element in the stream represents a row in the result, where the columns of the row are mapped to the constructor arguments of the specified type.

      The resulting stream is lazily loaded, meaning that the records are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of records.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Returns:
      a stream of results.
      Throws:
      PersistenceException - if the query operation fails due to underlying database issues, such as connectivity.

    • getRefStream

      <T extends Record> Stream<Ref<T>> getRefStream(@Nonnull Class<T> type, @Nonnull Class<?> pkType)
      Execute a SELECT query and return the resulting rows as a stream of ref instances.

      Each element in the stream represents a row in the result, where the columns of the row are mapped to the constructor arguments primary key type.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Parameters:
      type - the type of the results that are being referenced.
      pkType - the primary key type.
      Returns:
      a stream of ref instances.
      Throws:
      PersistenceException - if the query fails.
      Since:
      1.3

    • getResult

      default <T, R> R getResult(@Nonnull Class<T> type, @Nonnull ResultCallback<T,R> callback)
      Execute a SELECT query and return the resulting rows as a stream of row instances.

      Each element in the stream represents a row in the result, where the columns of the row are mapped to the constructor arguments of the specified type.

      This method ensures efficient handling of large data sets by loading entities only as needed. It also manages lifecycle of the callback stream, automatically closing the stream after processing to prevent resource leaks.

      Parameters:
      type - the type of the result.
      Returns:
      the result stream.
      Throws:
      PersistenceException - if the query fails.

    • isVersionAware

      boolean isVersionAware()
      Returns true if the query is version aware, false otherwise.
      Returns:
      true if the query is version aware, false otherwise.

    • executeUpdate

      int executeUpdate()
      Execute a command, such as an INSERT, UPDATE or DELETE statement.
      Returns:
      the number of rows impacted as result of the statement.
      Throws:
      PersistenceException - if the statement fails.

    • executeBatch

      int[] executeBatch()
      Execute a batch of commands.
      Returns:
      an array of update counts containing one element for each command in the batch. The elements of the array are ordered according to the order in which commands were added to the batch, following Statement.executeBatch semantics.
      Throws:
      PersistenceException - if the batch fails.