Package org.datanucleus.api.jakarta

Class JakartaQuery<X>

  • Type Parameters:
    X - Type of the candidate of the query
    All Implemented Interfaces:
    jakarta.persistence.Query, jakarta.persistence.TypedQuery<X>
    Direct Known Subclasses:
    JakartaStoredProcedureQuery
    public class JakartaQuery<X>
extends Object
implements jakarta.persistence.TypedQuery<X>
    Basic implementation of a Jakarta Persistence Query. Wraps an internal query.

    • Constructor Summary

      Constructors 
      Constructor Description
      JakartaQuery​(JakartaEntityManager em, org.datanucleus.store.query.Query query, String language)
      Constructor for a query used by Jakarta Persistence.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int executeUpdate()
      Method to execute a (UPDATE/DELETE) query returning the number of changed records.
      JakartaFetchPlan getFetchPlan()  
      int getFirstResult()
      The position of the first result the query object was set to retrieve.
      jakarta.persistence.FlushModeType getFlushMode()
      The flush mode in effect for the query execution.
      Map<String,​Object> getHints()
      Get the hints and associated values that are in effect for the query instance.
      org.datanucleus.store.query.Query getInternalQuery()
      Accessor for the internal query.
      String getLanguage()
      Accessor for the query language.
      jakarta.persistence.LockModeType getLockMode()  
      int getMaxResults()
      The maximum number of results the query object was set to retrieve.
      Object getNativeQuery()
      Accessor for the native query invoked by this query (if known at this time and supported by the store plugin).
      jakarta.persistence.Parameter<?> getParameter​(int position)  
      <T> jakarta.persistence.Parameter<T> getParameter​(int position, Class<T> type)
      Get the positional parameter with the given position and type.
      jakarta.persistence.Parameter<?> getParameter​(String name)  
      <T> jakarta.persistence.Parameter<T> getParameter​(String name, Class<T> type)
      Get the parameter of the given name and type.
      Set<jakarta.persistence.Parameter<?>> getParameters()
      Get the query parameter objects.
      Object getParameterValue​(int position)  
      <T> T getParameterValue​(jakarta.persistence.Parameter<T> param)
      Return the value that has been bound to the parameter.
      Object getParameterValue​(String name)  
      List getResultList()
      Method to execute a (SELECT) query statement returning multiple results.
      X getSingleResult()
      Method to execute a SELECT statement returning a single result.
      Set<String> getSupportedHints()
      Get the names of the hints that are supported for query objects.
      boolean isBound​(jakarta.persistence.Parameter<?> param)  
      protected boolean isNativeQuery()  
      protected void loadParameters()  
      protected void loadParametersForCompilation​(org.datanucleus.store.query.compiler.QueryCompilation compilation)  
      void saveAsNamedQuery​(String name)
      Save this query as a named query with the specified name.
      jakarta.persistence.TypedQuery<X> setFirstResult​(int startPosition)
      Method to set the results to start from a particular position.
      jakarta.persistence.TypedQuery<X> setFlushMode​(jakarta.persistence.FlushModeType mode)
      Mutator for the flush mode.
      jakarta.persistence.TypedQuery<X> setHint​(String hintName, Object value)
      Method to add a vendor extension to the query.
      jakarta.persistence.TypedQuery<X> setLockMode​(jakarta.persistence.LockModeType lock)  
      jakarta.persistence.TypedQuery<X> setMaxResults​(int max)
      Method to set the max number of results to return.
      jakarta.persistence.TypedQuery<X> setParameter​(int position, Object value)
      Bind an argument to a positional parameter.
      jakarta.persistence.TypedQuery<X> setParameter​(int position, Calendar value, jakarta.persistence.TemporalType temporalType)
      Bind an instance of java.util.Calendar to a positional parameter.
      jakarta.persistence.TypedQuery<X> setParameter​(int position, Date value, jakarta.persistence.TemporalType temporalType)
      Bind an instance of java.util.Date to a positional parameter.
      JakartaQuery<X> setParameter​(jakarta.persistence.Parameter<Calendar> param, Calendar cal, jakarta.persistence.TemporalType type)  
      jakarta.persistence.TypedQuery<X> setParameter​(jakarta.persistence.Parameter<Date> param, Date date, jakarta.persistence.TemporalType type)  
      <T> jakarta.persistence.TypedQuery<X> setParameter​(jakarta.persistence.Parameter<T> param, T value)
      Bind the value of a Parameter object.
      jakarta.persistence.TypedQuery<X> setParameter​(String name, Object value)
      Bind an argument to a named parameter.
      jakarta.persistence.TypedQuery<X> setParameter​(String name, Calendar value, jakarta.persistence.TemporalType temporalType)
      Bind an instance of java.util.Calendar to a named parameter.
      jakarta.persistence.TypedQuery<X> setParameter​(String name, Date value, jakarta.persistence.TemporalType temporalType)
      Bind an instance of java.util.Date to a named parameter.
      String toString()
      Method to return the single-string form of the query.
      <T> T unwrap​(Class<T> cls)
      Return an object of the specified type to allow access to the provider-specific API.

      • Methods inherited from interface jakarta.persistence.TypedQuery

        getResultStream

    • Field Detail

      • QUERY_HINT_FETCH_SIZE

        public static final String QUERY_HINT_FETCH_SIZE

      • QUERY_HINT_IGNORE_CACHE

        public static final String QUERY_HINT_IGNORE_CACHE

    • Constructor Detail

      • JakartaQuery

        public JakartaQuery​(JakartaEntityManager em,
                    org.datanucleus.store.query.Query query,
                    String language)
        Constructor for a query used by Jakarta Persistence.
        Parameters:
        em - Entity Manager
        query - Underlying query
        language - Query language

    • Method Detail

      • executeUpdate

        public int executeUpdate()
        Method to execute a (UPDATE/DELETE) query returning the number of changed records.
        Specified by:
        executeUpdate in interface jakarta.persistence.Query
        Returns:
        Number of records updated/deleted with the query.
        Throws:
        jakarta.persistence.QueryTimeoutException - if the query times out

      • getResultList

        public List getResultList()
        Method to execute a (SELECT) query statement returning multiple results.
        Specified by:
        getResultList in interface jakarta.persistence.Query
        Specified by:
        getResultList in interface jakarta.persistence.TypedQuery<X>
        Returns:
        The results
        Throws:
        jakarta.persistence.QueryTimeoutException - if the query times out

      • getSingleResult

        public X getSingleResult()
        Method to execute a SELECT statement returning a single result.
        Specified by:
        getSingleResult in interface jakarta.persistence.Query
        Specified by:
        getSingleResult in interface jakarta.persistence.TypedQuery<X>
        Returns:
        the result
        Throws:
        jakarta.persistence.QueryTimeoutException - if the query times out

      • setFirstResult

        public jakarta.persistence.TypedQuery<X> setFirstResult​(int startPosition)
        Method to set the results to start from a particular position.
        Specified by:
        setFirstResult in interface jakarta.persistence.Query
        Specified by:
        setFirstResult in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        startPosition - position of first result numbered from 0
        Returns:
        The query

      • setMaxResults

        public jakarta.persistence.TypedQuery<X> setMaxResults​(int max)
        Method to set the max number of results to return.
        Specified by:
        setMaxResults in interface jakarta.persistence.Query
        Specified by:
        setMaxResults in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        max - Number of results max
        Returns:
        The query

      • getMaxResults

        public int getMaxResults()
        The maximum number of results the query object was set to retrieve. Returns Integer.MAX_VALUE if setMaxResults was not applied to the query object.
        Specified by:
        getMaxResults in interface jakarta.persistence.Query
        Returns:
        maximum number of results

      • getFirstResult

        public 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.
        Specified by:
        getFirstResult in interface jakarta.persistence.Query
        Returns:
        position of first result

      • setFlushMode

        public jakarta.persistence.TypedQuery<X> setFlushMode​(jakarta.persistence.FlushModeType mode)
        Mutator for the flush mode.
        Specified by:
        setFlushMode in interface jakarta.persistence.Query
        Specified by:
        setFlushMode in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        mode - Flush mode
        Returns:
        The query

      • getFlushMode

        public jakarta.persistence.FlushModeType getFlushMode()
        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.
        Specified by:
        getFlushMode in interface jakarta.persistence.Query
        Returns:
        flush mode

      • setHint

        public jakarta.persistence.TypedQuery<X> setHint​(String hintName,
                                                 Object value)
        Method to add a vendor extension to the query. If the hint name is not recognized, it is silently ignored.
        Specified by:
        setHint in interface jakarta.persistence.Query
        Specified by:
        setHint in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        hintName - Name of the "hint"
        value - Value for the "hint"
        Returns:
        the same query instance
        Throws:
        IllegalArgumentException - if the second argument is not valid for the implementation

      • getHints

        public Map<String,​Object> getHints()
        Get the hints and associated values that are in effect for the query instance.
        Specified by:
        getHints in interface jakarta.persistence.Query
        Returns:
        query hints

      • getSupportedHints

        public Set<String> getSupportedHints()
        Get the names of the hints that are supported for query objects. These hints correspond to hints that may be passed to the methods of the Query interface that take hints as arguments or used with the NamedQuery and NamedNativeQuery annotations. These include all standard query hints as well as vendor-specific hints supported by the provider. These hints may or may not currently be in effect.
        Returns:
        hints

      • setParameter

        public <T> jakarta.persistence.TypedQuery<X> setParameter​(jakarta.persistence.Parameter<T> param,
                                                          T value)
        Bind the value of a Parameter object.
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        param - parameter to be set
        value - parameter value
        Returns:
        query instance
        Throws:
        IllegalArgumentException - if parameter does not correspond to a parameter of the query

      • setParameter

        public jakarta.persistence.TypedQuery<X> setParameter​(String name,
                                                      Object value)
        Bind an argument to a named parameter.
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        name - the parameter name
        value - The value for the param
        Returns:
        the same query instance
        Throws:
        IllegalArgumentException - if parameter name does not correspond to parameter in query string or argument is of incorrect type

      • setParameter

        public jakarta.persistence.TypedQuery<X> setParameter​(int position,
                                                      Object value)
        Bind an argument to a positional parameter.
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        position - Parameter position
        value - The value
        Returns:
        the same query instance
        Throws:
        IllegalArgumentException - if position does not correspond to positional parameter of query or argument is of incorrect type

      • setParameter

        public jakarta.persistence.TypedQuery<X> setParameter​(String name,
                                                      Date value,
                                                      jakarta.persistence.TemporalType temporalType)
        Bind an instance of java.util.Date to a named parameter.
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        name - Name of the param
        value - Value for the param
        temporalType - The temporal type
        Returns:
        the same query instance
        Throws:
        IllegalArgumentException - if parameter name does not correspond to parameter in query string

      • setParameter

        public jakarta.persistence.TypedQuery<X> setParameter​(String name,
                                                      Calendar value,
                                                      jakarta.persistence.TemporalType temporalType)
        Bind an instance of java.util.Calendar to a named parameter.
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        name - name of the param
        value - Value for the param
        temporalType - The temporal type
        Returns:
        the same query instance
        Throws:
        IllegalArgumentException - if parameter name does not correspond to parameter in query string

      • setParameter

        public jakarta.persistence.TypedQuery<X> setParameter​(int position,
                                                      Date value,
                                                      jakarta.persistence.TemporalType temporalType)
        Bind an instance of java.util.Date to a positional parameter.
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        position - Parameter position
        value - Value for the param
        temporalType - Temporal Type
        Returns:
        the same query instance
        Throws:
        IllegalArgumentException - if position does not correspond to positional parameter of query

      • setParameter

        public jakarta.persistence.TypedQuery<X> setParameter​(int position,
                                                      Calendar value,
                                                      jakarta.persistence.TemporalType temporalType)
        Bind an instance of java.util.Calendar to a positional parameter.
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>
        Parameters:
        position - Parameter position
        value - Value for the param
        temporalType - Temporal type
        Returns:
        the same query instance
        Throws:
        IllegalArgumentException - if position does not correspond to positional parameter of query

      • setParameter

        public JakartaQuery<X> setParameter​(jakarta.persistence.Parameter<Calendar> param,
                                    Calendar cal,
                                    jakarta.persistence.TemporalType type)
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>

      • setParameter

        public jakarta.persistence.TypedQuery<X> setParameter​(jakarta.persistence.Parameter<Date> param,
                                                      Date date,
                                                      jakarta.persistence.TemporalType type)
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.TypedQuery<X>

      • getInternalQuery

        public org.datanucleus.store.query.Query getInternalQuery()
        Accessor for the internal query.
        Returns:
        Internal query

      • unwrap

        public <T> T unwrap​(Class<T> cls)
        Return an object of the specified type to allow access to the provider-specific API. If the provider's Query implementation does not support the specified class, the PersistenceException is thrown.
        Specified by:
        unwrap in interface jakarta.persistence.Query
        Parameters:
        cls - the class of the object to be returned. This is normally either the underlying Query implementation class or an interface that it implements.
        Returns:
        an instance of the specified class
        Throws:
        jakarta.persistence.PersistenceException - if the provider does not support the call.

      • getLanguage

        public String getLanguage()
        Accessor for the query language.
        Returns:
        Query language

      • getParameters

        public Set<jakarta.persistence.Parameter<?>> getParameters()
        Get the query parameter objects. Returns empty set if the query has no parameters.
        Specified by:
        getParameters in interface jakarta.persistence.Query
        Returns:
        parameter objects

      • loadParameters

        protected void loadParameters()

      • loadParametersForCompilation

        protected void loadParametersForCompilation​(org.datanucleus.store.query.compiler.QueryCompilation compilation)

      • getParameter

        public <T> jakarta.persistence.Parameter<T> getParameter​(String name,
                                                         Class<T> type)
        Get the parameter of the given name and type.
        Specified by:
        getParameter in interface jakarta.persistence.Query
        Returns:
        parameter object
        Throws:
        IllegalArgumentException - if the parameter of the specified name and type doesn't exist

      • getParameter

        public <T> jakarta.persistence.Parameter<T> getParameter​(int position,
                                                         Class<T> type)
        Get the positional parameter with the given position and type.
        Specified by:
        getParameter in interface jakarta.persistence.Query
        Returns:
        parameter object
        Throws:
        IllegalArgumentException - if the parameter with the specified position and type doesn't exist

      • getParameter

        public jakarta.persistence.Parameter<?> getParameter​(int position)
        Specified by:
        getParameter in interface jakarta.persistence.Query

      • getParameter

        public jakarta.persistence.Parameter<?> getParameter​(String name)
        Specified by:
        getParameter in interface jakarta.persistence.Query

      • getParameterValue

        public <T> T getParameterValue​(jakarta.persistence.Parameter<T> param)
        Return the value that has been bound to the parameter.
        Specified by:
        getParameterValue in interface jakarta.persistence.Query
        Parameters:
        param - parameter object
        Returns:
        parameter value
        Throws:
        IllegalStateException - if the parameter has not been bound

      • getParameterValue

        public Object getParameterValue​(int position)
        Specified by:
        getParameterValue in interface jakarta.persistence.Query

      • getParameterValue

        public Object getParameterValue​(String name)
        Specified by:
        getParameterValue in interface jakarta.persistence.Query

      • isBound

        public boolean isBound​(jakarta.persistence.Parameter<?> param)
        Specified by:
        isBound in interface jakarta.persistence.Query

      • getLockMode

        public jakarta.persistence.LockModeType getLockMode()
        Specified by:
        getLockMode in interface jakarta.persistence.Query

      • setLockMode

        public jakarta.persistence.TypedQuery<X> setLockMode​(jakarta.persistence.LockModeType lock)
        Specified by:
        setLockMode in interface jakarta.persistence.Query
        Specified by:
        setLockMode in interface jakarta.persistence.TypedQuery<X>

      • toString

        public String toString()
        Method to return the single-string form of the query. Note that the Jakarta Persistence spec doesn't define this methods handling and this is an extension.
        Overrides:
        toString in class Object
        Returns:
        The single-string form of the query

      • getNativeQuery

        public Object getNativeQuery()
        Accessor for the native query invoked by this query (if known at this time and supported by the store plugin).
        Returns:
        The native query (e.g for RDBMS this is the SQL).

      • saveAsNamedQuery

        public void saveAsNamedQuery​(String name)
        Save this query as a named query with the specified name. See also EntityManagerFactory.addNamedQuery(String, Query)
        Parameters:
        name - The name to refer to it under

      • isNativeQuery

        protected boolean isNativeQuery()