Interface Query

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      int executeUpdate()
      Execute an update or delete statement.
      CacheRetrieveMode getCacheRetrieveMode()
      The cache retrieval mode that will be in effect during query execution.
      CacheStoreMode getCacheStoreMode()
      The cache storage mode that will be in effect during query execution.
      int getFirstResult()
      The position of the first result the query object was set to retrieve.
      FlushModeType getFlushMode()
      Get the flush mode in effect for the query execution.
      java.util.Map<java.lang.String,​java.lang.Object> getHints()
      Get the properties and hints and associated values that are in effect for the query instance.
      LockModeType getLockMode()
      Get the current lock mode for the query.
      int getMaxResults()
      The maximum number of results the query object was set to retrieve.
      Parameter<?> getParameter​(int position)
      Get the parameter object corresponding to the declared positional parameter with the given position.
      <T> Parameter<T> getParameter​(int position, java.lang.Class<T> type)
      Get the parameter object corresponding to the declared positional parameter with the given position and type.
      Parameter<?> getParameter​(java.lang.String name)
      Get the parameter object corresponding to the declared parameter of the given name.
      <T> Parameter<T> getParameter​(java.lang.String name, java.lang.Class<T> type)
      Get the parameter object corresponding to the declared parameter of the given name and type.
      java.util.Set<Parameter<?>> getParameters()
      Get the parameter objects corresponding to the declared parameters of the query.
      java.lang.Object getParameterValue​(int position)
      Return the input value bound to the positional parameter.
      <T> T getParameterValue​(Parameter<T> param)
      Return the input value bound to the parameter.
      java.lang.Object getParameterValue​(java.lang.String name)
      Return the input value bound to the named parameter.
      java.util.List getResultList()
      Execute a SELECT query and return the query results as an untyped List.
      default java.util.stream.Stream getResultStream()
      Execute a SELECT query and return the query results as an untyped Stream.
      java.lang.Object getSingleResult()
      Execute a SELECT query that returns a single untyped result.
      java.lang.Object getSingleResultOrNull()
      Execute a SELECT query that returns a single untyped result.
      java.lang.Integer getTimeout()
      The query timeout.
      boolean isBound​(Parameter<?> param)
      Return a boolean indicating whether a value has been bound to the parameter.
      Query setCacheRetrieveMode​(CacheRetrieveMode cacheRetrieveMode)
      Set the cache retrieval mode that is in effect during query execution.
      Query setCacheStoreMode​(CacheStoreMode cacheStoreMode)
      Set the cache storage mode that is in effect during query execution.
      Query setFirstResult​(int startPosition)
      Set the position of the first result to retrieve.
      Query setFlushMode​(FlushModeType flushMode)
      Set the flush mode type to be used for the query execution.
      Query setHint​(java.lang.String hintName, java.lang.Object value)
      Set a query property or hint.
      Query setLockMode​(LockModeType lockMode)
      Set the lock mode type to be used for the query execution.
      Query setMaxResults​(int maxResult)
      Set the maximum number of results to retrieve.
      Query setParameter​(int position, java.lang.Object value)
      Bind an argument value to a positional parameter.
      Query setParameter​(int position, java.util.Calendar value, TemporalType temporalType)
      Deprecated.
      Newly-written code should use the date/time types defined in java.time.
      Query setParameter​(int position, java.util.Date value, TemporalType temporalType)
      Deprecated.
      Newly-written code should use the date/time types defined in java.time.
      Query setParameter​(Parameter<java.util.Calendar> param, java.util.Calendar value, TemporalType temporalType)
      Deprecated.
      Newly-written code should use the date/time types defined in java.time.
      Query setParameter​(Parameter<java.util.Date> param, java.util.Date value, TemporalType temporalType)
      Deprecated.
      Newly-written code should use the date/time types defined in java.time.
      <T> Query setParameter​(Parameter<T> param, T value)
      Bind the value of a Parameter object.
      Query setParameter​(java.lang.String name, java.lang.Object value)
      Bind an argument value to a named parameter.
      Query setParameter​(java.lang.String name, java.util.Calendar value, TemporalType temporalType)
      Deprecated.
      Newly-written code should use the date/time types defined in java.time.
      Query setParameter​(java.lang.String name, java.util.Date value, TemporalType temporalType)
      Deprecated.
      Newly-written code should use the date/time types defined in java.time.
      Query setTimeout​(java.lang.Integer timeout)
      Set the query timeout, in milliseconds.
      <T> T unwrap​(java.lang.Class<T> cls)
      Return an object of the specified type to allow access to a provider-specific API.
    • Method Detail

      • getResultList

        java.util.List getResultList()
        Execute a SELECT query and return the query results as an untyped List.
        Returns:
        a list of the results, or an empty list if there are no results
        Throws:
        java.lang.IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
        QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
        TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
        PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
        LockTimeoutException - if pessimistic locking fails and only the statement is rolled back
        PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back
      • getResultStream

        default java.util.stream.Stream getResultStream()
        Execute a SELECT query and return the query results as an untyped Stream.

        By default, this method delegates to getResultList().stream(), however persistence provider may choose to override this method to provide additional capabilities.

        Returns:
        a stream of the results, or an empty stream if there are no results
        Throws:
        java.lang.IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
        QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
        TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
        PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
        LockTimeoutException - if pessimistic locking fails and only the statement is rolled back
        PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back
        Since:
        2.2
        See Also:
        Stream, getResultList()
      • getSingleResult

        java.lang.Object getSingleResult()
        Execute a SELECT query that returns a single untyped result.
        Returns:
        the result
        Throws:
        NoResultException - if there is no result
        NonUniqueResultException - if more than one result
        java.lang.IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
        QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
        TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
        PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
        LockTimeoutException - if pessimistic locking fails and only the statement is rolled back
        PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back
      • getSingleResultOrNull

        java.lang.Object getSingleResultOrNull()
        Execute a SELECT query that returns a single untyped result.
        Returns:
        the result, or null if there is no result
        Throws:
        NonUniqueResultException - if more than one result
        java.lang.IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
        QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
        TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
        PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
        LockTimeoutException - if pessimistic locking fails and only the statement is rolled back
        PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back
        Since:
        3.2
      • executeUpdate

        int executeUpdate()
        Execute an update or delete statement.
        Returns:
        the number of entities updated or deleted
        Throws:
        java.lang.IllegalStateException - if called for a Jakarta Persistence query language SELECT statement or for a criteria query
        TransactionRequiredException - if there is no transaction or the persistence context has not been joined to the transaction
        QueryTimeoutException - if the statement execution exceeds the query timeout value set and only the statement is rolled back
        PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back
      • setMaxResults

        Query setMaxResults​(int maxResult)
        Set the maximum number of results to retrieve.
        Parameters:
        maxResult - maximum number of results to retrieve
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the argument is negative
      • getMaxResults

        int getMaxResults()
        The maximum number of results the query object was set to retrieve. Returns Integer.MAX_VALUE if setMaxResults(int) was not applied to the query object.
        Returns:
        maximum number of results
        Since:
        2.0
      • setFirstResult

        Query setFirstResult​(int startPosition)
        Set the position of the first result to retrieve.
        Parameters:
        startPosition - position of the first result, numbered from 0
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the argument is negative
      • getFirstResult

        int getFirstResult()
        The position of the first result the query object was set to retrieve. Returns 0 if setFirstResult was not applied to the query object.
        Returns:
        position of the first result
        Since:
        2.0
      • setHint

        Query setHint​(java.lang.String hintName,
                      java.lang.Object value)
        Set a query property or hint. The hints elements may be used to specify query properties and hints. Properties defined by this specification must be observed by the provider. Vendor-specific hints that are not recognized by a provider must be silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, this hint may or may not be observed.
        Parameters:
        hintName - name of the property or hint
        value - value for the property or hint
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the second argument is not valid for the implementation
      • getHints

        java.util.Map<java.lang.String,​java.lang.Object> getHints()
        Get the properties and hints and associated values that are in effect for the query instance.
        Returns:
        query properties and hints
        Since:
        2.0
      • setParameter

        <T> Query setParameter​(Parameter<T> param,
                               T value)
        Bind the value of a Parameter object.
        Parameters:
        param - parameter object
        value - parameter value
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the parameter does not correspond to a parameter of the query
        Since:
        2.0
      • setParameter

        @Deprecated(since="3.2")
        Query setParameter​(Parameter<java.util.Calendar> param,
                           java.util.Calendar value,
                           TemporalType temporalType)
        Deprecated.
        Newly-written code should use the date/time types defined in java.time.
        Bind an instance of Calendar to a Parameter object.
        Parameters:
        param - parameter object
        value - parameter value
        temporalType - temporal type
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the parameter does not correspond to a parameter of the query
        Since:
        2.0
      • setParameter

        @Deprecated(since="3.2")
        Query setParameter​(Parameter<java.util.Date> param,
                           java.util.Date value,
                           TemporalType temporalType)
        Deprecated.
        Newly-written code should use the date/time types defined in java.time.
        Bind an instance of Date to a Parameter object.
        Parameters:
        param - parameter object
        value - parameter value
        temporalType - temporal type
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the parameter does not correspond to a parameter of the query
        Since:
        2.0
      • setParameter

        Query setParameter​(java.lang.String name,
                           java.lang.Object value)
        Bind an argument value to a named parameter.
        Parameters:
        name - parameter name
        value - parameter value
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or if the argument is of incorrect type
      • setParameter

        @Deprecated(since="3.2")
        Query setParameter​(java.lang.String name,
                           java.util.Calendar value,
                           TemporalType temporalType)
        Deprecated.
        Newly-written code should use the date/time types defined in java.time.
        Bind an instance of Calendar to a named parameter.
        Parameters:
        name - parameter name
        value - parameter value
        temporalType - temporal type
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type
      • setParameter

        @Deprecated(since="3.2")
        Query setParameter​(java.lang.String name,
                           java.util.Date value,
                           TemporalType temporalType)
        Deprecated.
        Newly-written code should use the date/time types defined in java.time.
        Bind an instance of Date to a named parameter.
        Parameters:
        name - parameter name
        value - parameter value
        temporalType - temporal type
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type
      • setParameter

        Query setParameter​(int position,
                           java.lang.Object value)
        Bind an argument value to a positional parameter.
        Parameters:
        position - position
        value - parameter value
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query or if the argument is of incorrect type
      • setParameter

        @Deprecated(since="3.2")
        Query setParameter​(int position,
                           java.util.Calendar value,
                           TemporalType temporalType)
        Deprecated.
        Newly-written code should use the date/time types defined in java.time.
        Bind an instance of Calendar to a positional parameter.
        Parameters:
        position - position
        value - parameter value
        temporalType - temporal type
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type
      • setParameter

        @Deprecated(since="3.2")
        Query setParameter​(int position,
                           java.util.Date value,
                           TemporalType temporalType)
        Deprecated.
        Newly-written code should use the date/time types defined in java.time.
        Bind an instance of Date to a positional parameter.
        Parameters:
        position - position
        value - parameter value
        temporalType - temporal type
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type
      • getParameters

        java.util.Set<Parameter<?>> getParameters()
        Get the parameter objects corresponding to the declared parameters of the query. Returns empty set if the query has no parameters. This method is not required to be supported for native queries.
        Returns:
        set of the parameter objects
        Throws:
        java.lang.IllegalStateException - if invoked on a native query when the implementation does not support this use
        Since:
        2.0
      • getParameter

        Parameter<?> getParameter​(java.lang.String name)
        Get the parameter object corresponding to the declared parameter of the given name. This method is not required to be supported for native queries.
        Parameters:
        name - parameter name
        Returns:
        parameter object
        Throws:
        java.lang.IllegalArgumentException - if the parameter of the specified name does not exist
        java.lang.IllegalStateException - if invoked on a native query when the implementation does not support this use
        Since:
        2.0
      • getParameter

        <T> Parameter<T> getParameter​(java.lang.String name,
                                      java.lang.Class<T> type)
        Get the parameter object corresponding to the declared parameter of the given name and type. This method is required to be supported for criteria queries only.
        Parameters:
        name - parameter name
        type - type
        Returns:
        parameter object
        Throws:
        java.lang.IllegalArgumentException - if the parameter of the specified name does not exist or is not assignable to the type
        java.lang.IllegalStateException - if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use
        Since:
        2.0
      • getParameter

        Parameter<?> getParameter​(int position)
        Get the parameter object corresponding to the declared positional parameter with the given position. This method is not required to be supported for native queries.
        Parameters:
        position - position
        Returns:
        parameter object
        Throws:
        java.lang.IllegalArgumentException - if the parameter with the specified position does not exist
        java.lang.IllegalStateException - if invoked on a native query when the implementation does not support this use
        Since:
        2.0
      • getParameter

        <T> Parameter<T> getParameter​(int position,
                                      java.lang.Class<T> type)
        Get the parameter object corresponding to the declared positional parameter with the given position and type. This method is not required to be supported by the provider.
        Parameters:
        position - position
        type - type
        Returns:
        parameter object
        Throws:
        java.lang.IllegalArgumentException - if the parameter with the specified position does not exist or is not assignable to the type
        java.lang.IllegalStateException - if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use
        Since:
        2.0
      • isBound

        boolean isBound​(Parameter<?> param)
        Return a boolean indicating whether a value has been bound to the parameter.
        Parameters:
        param - parameter object
        Returns:
        boolean indicating whether parameter has been bound
        Since:
        2.0
      • getParameterValue

        <T> T getParameterValue​(Parameter<T> param)
        Return the input value bound to the parameter. (Note that OUT parameters are unbound.)
        Parameters:
        param - parameter object
        Returns:
        parameter value
        Throws:
        java.lang.IllegalArgumentException - if the parameter is not a parameter of the query
        java.lang.IllegalStateException - if the parameter has not been bound
        Since:
        2.0
      • getParameterValue

        java.lang.Object getParameterValue​(java.lang.String name)
        Return the input value bound to the named parameter. (Note that OUT parameters are unbound.)
        Parameters:
        name - parameter name
        Returns:
        parameter value
        Throws:
        java.lang.IllegalStateException - if the parameter has not been bound
        java.lang.IllegalArgumentException - if the parameter of the specified name does not exist
        Since:
        2.0
      • getParameterValue

        java.lang.Object getParameterValue​(int position)
        Return the input value bound to the positional parameter. (Note that OUT parameters are unbound.)
        Parameters:
        position - position
        Returns:
        parameter value
        Throws:
        java.lang.IllegalStateException - if the parameter has not been bound
        java.lang.IllegalArgumentException - if the parameter with the specified position does not exist
        Since:
        2.0
      • setFlushMode

        Query setFlushMode​(FlushModeType flushMode)
        Set the flush mode type to be used for the query execution. The flush mode type applies to the query regardless of the flush mode type in use for the entity manager.
        Parameters:
        flushMode - flush mode
        Returns:
        the same query instance
      • getFlushMode

        FlushModeType getFlushMode()
        Get the flush mode in effect for the query execution. If a flush mode has not been set for the query object, returns the flush mode in effect for the entity manager.
        Returns:
        flush mode
        Since:
        2.0
      • setLockMode

        Query setLockMode​(LockModeType lockMode)
        Set the lock mode type to be used for the query execution.
        Parameters:
        lockMode - lock mode
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalStateException - if the query is found not to be a Jakarta Persistence query language SELECT query or a CriteriaQuery query
        Since:
        2.0
      • getLockMode

        LockModeType getLockMode()
        Get the current lock mode for the query. Returns null if a lock mode has not been set on the query object.
        Returns:
        lock mode
        Throws:
        java.lang.IllegalStateException - if the query is found not to be a Jakarta Persistence query language SELECT query or a CriteriaQuery query
        Since:
        2.0
      • setCacheRetrieveMode

        Query setCacheRetrieveMode​(CacheRetrieveMode cacheRetrieveMode)
        Set the cache retrieval mode that is in effect during query execution. This cache retrieval mode overrides the cache retrieve mode in use by the entity manager.
        Parameters:
        cacheRetrieveMode - cache retrieval mode
        Returns:
        the same query instance
        Since:
        3.2
      • setCacheStoreMode

        Query setCacheStoreMode​(CacheStoreMode cacheStoreMode)
        Set the cache storage mode that is in effect during query execution. This cache storage mode overrides the cache storage mode in use by the entity manager.
        Parameters:
        cacheStoreMode - cache storage mode
        Returns:
        the same query instance
        Since:
        3.2
      • getCacheRetrieveMode

        CacheRetrieveMode getCacheRetrieveMode()
        The cache retrieval mode that will be in effect during query execution.
        Since:
        3.2
      • getCacheStoreMode

        CacheStoreMode getCacheStoreMode()
        The cache storage mode that will be in effect during query execution.
        Since:
        3.2
      • setTimeout

        Query setTimeout​(java.lang.Integer timeout)
        Set the query timeout, in milliseconds. This is a hint, and is an alternative to setting the hint jakarta.persistence.query.timeout.
        Parameters:
        timeout - the timeout, in milliseconds, or null to indicate no timeout
        Returns:
        the same query instance
        Since:
        3.2
      • getTimeout

        java.lang.Integer getTimeout()
        The query timeout.
        Since:
        3.2
      • unwrap

        <T> T unwrap​(java.lang.Class<T> cls)
        Return an object of the specified type to allow access to a provider-specific API. If the provider implementation of Query does not support the given type, the PersistenceException is thrown.
        Parameters:
        cls - the type of the object to be returned. This is usually either the underlying class implementing Query or an interface it implements.
        Returns:
        an instance of the specified class
        Throws:
        PersistenceException - if the provider does not support the given type
        Since:
        2.0