Interface StatementOrTypedQuery

All Superinterfaces:
Query
public interface StatementOrTypedQuery extends Query
Declares operations allowing a Statement or TypedQuery to be obtained when the type of a query or statement has not yet been specified. This allows a slightly more fluent programming style where:
  • a Jakarta Persistence or native SQL query is provided to createQuery(), and
  • the type of the query clarified in a subsequent method call.

If an instance of this interface represents an UPDATE or DELETE statement, then a Statement representing the same statement may be obtained by calling asStatement(). 

int updated =
        em.createQuery("delete from Temporary where timestamp > ?1")
                .asStatement()
                .setParameter(1, cutoffDateTime)
                .execute();

If an instance of this interface represents a SELECT query, then a TypedQuery representing the same query may be obtained by calling ofType(Class), passing the result type of the query. 

List<Book> books =
        em.createQuery("from Book where extract(year from publicationDate) > :year")
                .ofType(Book.class)
                .setParameter("year", Year.of(2000))
                .setMaxResults(10)
                .setCacheRetrieveMode(CacheRetrieveMode.BYPASS)
                .getResultList();

These operations may be viewed as a sort of type cast to a given subtype of this interface.

Since:
4.0
API note:
For backward compatibility with older versions of the Persistence API, it is possible to execute a query or statement by calling the deprecated methods Query.getResultList() and Query.executeUpdate() inherited by this interface. But new code targeting Persistence 4 should not use this interface for direct execution of statements or queries. Statements should be executed using the Statement interface, and queries should be executed using the TypedQuery interface.

  • Method Details

    • asStatement

      @Nonnull Statement asStatement()
      Obtain a Statement representing this statement, which must be some kind of executable statement, that is, a Jakarta Persistence UPDATE or DELETE statement, or any native SQL statement that returns a row count. The executable statement may be executed by calling Statement.execute().
      Throws:
      IllegalStateException - if this query is a Jakarta Persistence SELECT query

    • ofType

      @Nonnull <R> TypedQuery<R> ofType(@Nonnull Class<R> resultType)
      Obtain a TypedQuery with the given query result type, which must be a supertype of the result type of this query. This query must be a Jakarta Persistence SELECT query or a native SQL query which returns a result set.
      Type Parameters:
      R - The query result type
      Parameters:
      resultType - The Java class of the query result type
      Throws:
      IllegalArgumentException - if the given result type is not a supertype of the result type of this query
      IllegalStateException - if this query is a Jakarta Persistence UPDATE or DELETE statement

    • withEntityGraph

      @Nonnull <R> TypedQuery<R> withEntityGraph(@Nonnull EntityGraph<R> graph)
      Obtain a TypedQuery with the given entity graph, which must be rooted at a supertype of the result type of this query. This query must be a Jakarta Persistence SELECT query which returns a single entity type.
      Type Parameters:
      R - The query result type
      Parameters:
      graph - The entity graph, interpreted as a load graph
      Throws:
      IllegalArgumentException - if the given graph type is not rooted at a supertype of the result type of this query
      IllegalStateException - if this query is a Jakarta Persistence UPDATE or DELETE statement

    • withResultSetMapping

      @Nonnull <R> TypedQuery<R> withResultSetMapping(@Nonnull ResultSetMapping<R> mapping)
      Obtain a TypedQuery with the given result set mapping. This query must be a native SQL query returning a result set compatible with the given mapping.
      Type Parameters:
      R - The query result type
      Parameters:
      mapping - The result set mapping
      Throws:
      IllegalArgumentException - if the given graph type is not rooted at a supertype of the result type of this query
      IllegalStateException - if this query is a Jakarta Persistence query or statement