Interface JpqlQuery<T>

Type Parameters:
T - result type
public interface JpqlQuery<T>

A mutable query obtained from Session.createQuery(String, Class). Supports entity and scalar selections, relationship joins, aggregates, grouping, ordering, predicate subqueries, and transactional bulk update/delete statements. This is a JPQL subset, not a complete JPA implementation; unsupported syntax is rejected during query creation. Bind named parameters before execution.

Selects flush pending changes in an active transaction and return managed entities or scalar values. Multiple selected values produce Object[] tuples. Fetch joins initialize relationships separately. Keep the owning session open; queries are not thread-safe. Applications should not implement this interface.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    executeUpdate()
    Executes a bulk update or delete in an active transaction.
    T
    first()
    Executes a select for at most one result, respecting the offset.
    JpqlQuery<T>
    limit(int value)
    Sets the maximum number of selected results.
    List<T>
    list()
    Executes a select with the configured pagination.
    JpqlQuery<T>
    offset(int value)
    Sets the number of selected results to skip.
    JpqlQuery<T>
    setParameter(String name, Object value)
    Binds a named parameter used by this statement.

  • Method Details

    • setParameter

      JpqlQuery<T> setParameter(String name, Object value)
      Binds a named parameter used by this statement.
      Parameters:
      name - parameter name without the colon
      value - bound value; null is allowed
      Returns:
      this query
      Throws:
      IllegalArgumentException - if the statement does not use this parameter

    • limit

      JpqlQuery<T> limit(int value)
      Sets the maximum number of selected results.
      Parameters:
      value - nonnegative maximum; zero returns no rows
      Returns:
      this query
      Throws:
      IllegalArgumentException - if value is negative

    • offset

      JpqlQuery<T> offset(int value)
      Sets the number of selected results to skip.
      Parameters:
      value - nonnegative offset
      Returns:
      this query
      Throws:
      IllegalArgumentException - if value is negative

    • list

      List<T> list()
      Executes a select with the configured pagination.
      Returns:
      selected entities, scalars, or tuples
      Throws:
      IllegalStateException - if this is a bulk mutation
      IllegalArgumentException - if a named parameter is unbound
      PersistenceException - if a result does not match the requested type or SQL fails

    • first

      T first()
      Executes a select for at most one result, respecting the offset.
      Returns:
      the first result, or null if none exists or the limit is zero
      Throws:
      IllegalStateException - if this is a bulk mutation
      IllegalArgumentException - if a named parameter is unbound

    • executeUpdate

      int executeUpdate()
      Executes a bulk update or delete in an active transaction. Flushes first, bypasses entity cascades and lifecycle callbacks, then clears the session so subsequent reads cannot reuse stale managed entities.
      Returns:
      number of affected rows
      Throws:
      IllegalStateException - if this is a select
      IllegalArgumentException - if pagination is set or a parameter is unbound
      PersistenceException - if no usable transaction is active or SQL fails