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.

Type parameters

<T>: result type

Methods

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

Method details

setParameter

public abstract JpqlQuery<T> setParameter(String name, Object value)

Binds a named parameter used by this statement.

Parameters

name String: parameter name without the colon
value Object: bound value; null is allowed

Returns

this query

Throws

IllegalArgumentException: if the statement does not use this parameter

limit

public abstract JpqlQuery<T> limit(int value)

Sets the maximum number of selected results.

Parameters

value int: nonnegative maximum; zero returns no rows

Returns

this query

Throws

IllegalArgumentException: if value is negative

offset

public abstract JpqlQuery<T> offset(int value)

Sets the number of selected results to skip.

Parameters

value int: nonnegative offset

Returns

this query

Throws

IllegalArgumentException: if value is negative

list

public abstract 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

public abstract 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

public abstract 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