Interface TypedQuery<X>

  • Type Parameters:
    X - query result type
    All Superinterfaces:
    Query

    public interface TypedQuery<X>
    extends Query
    Interface used to control the execution of typed queries.
    Since:
    2.0
    See Also:
    Query, Parameter
    • Method Detail

      • getResultList

        java.util.List<X> getResultList()
        Execute a SELECT query and return the query results as a typed List.
        Specified by:
        getResultList in interface Query
        Returns:
        a list of the results
        Throws:
        java.lang.IllegalStateException - if called for a Java 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<X> getResultStream()
        Execute a SELECT query and return the query results as a typed java.util.stream.Stream. By default this method delegates to getResultList().stream(), however persistence provider may choose to override this method to provide additional capabilities.
        Specified by:
        getResultStream in interface Query
        Returns:
        a stream of the results
        Throws:
        java.lang.IllegalStateException - if called for a Java 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

        X getSingleResult()
        Execute a SELECT query that returns a single result.
        Specified by:
        getSingleResult in interface Query
        Returns:
        the result
        Throws:
        NoResultException - if there is no result
        NonUniqueResultException - if more than one result
        java.lang.IllegalStateException - if called for a Java 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
      • setMaxResults

        TypedQuery<X> setMaxResults​(int maxResult)
        Set the maximum number of results to retrieve.
        Specified by:
        setMaxResults in interface Query
        Parameters:
        maxResult - maximum number of results to retrieve
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the argument is negative
      • setFirstResult

        TypedQuery<X> setFirstResult​(int startPosition)
        Set the position of the first result to retrieve.
        Specified by:
        setFirstResult in interface Query
        Parameters:
        startPosition - position of the first result, numbered from 0
        Returns:
        the same query instance
        Throws:
        java.lang.IllegalArgumentException - if the argument is negative
      • setHint

        TypedQuery<X> 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.
        Specified by:
        setHint in interface Query
        Parameters:
        hintName - name of 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
      • setParameter

        <T> TypedQuery<X> setParameter​(Parameter<T> param,
                                       T value)
        Bind the value of a Parameter object.
        Specified by:
        setParameter in interface Query
        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
      • setParameter

        TypedQuery<X> setParameter​(Parameter<java.util.Calendar> param,
                                   java.util.Calendar value,
                                   TemporalType temporalType)
        Bind an instance of java.util.Calendar to a Parameter object.
        Specified by:
        setParameter in interface Query
        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
      • setParameter

        TypedQuery<X> setParameter​(Parameter<java.util.Date> param,
                                   java.util.Date value,
                                   TemporalType temporalType)
        Bind an instance of java.util.Date to a Parameter object.
        Specified by:
        setParameter in interface Query
        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
      • setParameter

        TypedQuery<X> setParameter​(java.lang.String name,
                                   java.lang.Object value)
        Bind an argument value to a named parameter.
        Specified by:
        setParameter in interface Query
        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

        TypedQuery<X> setParameter​(java.lang.String name,
                                   java.util.Calendar value,
                                   TemporalType temporalType)
        Bind an instance of java.util.Calendar to a named parameter.
        Specified by:
        setParameter in interface Query
        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

        TypedQuery<X> setParameter​(java.lang.String name,
                                   java.util.Date value,
                                   TemporalType temporalType)
        Bind an instance of java.util.Date to a named parameter.
        Specified by:
        setParameter in interface Query
        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

        TypedQuery<X> setParameter​(int position,
                                   java.lang.Object value)
        Bind an argument value to a positional parameter.
        Specified by:
        setParameter in interface Query
        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

        TypedQuery<X> setParameter​(int position,
                                   java.util.Calendar value,
                                   TemporalType temporalType)
        Bind an instance of java.util.Calendar to a positional parameter.
        Specified by:
        setParameter in interface Query
        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

        TypedQuery<X> setParameter​(int position,
                                   java.util.Date value,
                                   TemporalType temporalType)
        Bind an instance of java.util.Date to a positional parameter.
        Specified by:
        setParameter in interface Query
        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
      • setFlushMode

        TypedQuery<X> 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.
        Specified by:
        setFlushMode in interface Query
        Parameters:
        flushMode - flush mode
        Returns:
        the same query instance
      • setLockMode

        TypedQuery<X> setLockMode​(LockModeType lockMode)
        Set the lock mode type to be used for the query execution.
        Specified by:
        setLockMode in interface Query
        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