Package org.hibernate.query

Interface Query<R>

    • Method Detail

      • getSession

        SharedSessionContract getSession()
        Get the QueryProducer this Query originates from. Generally speaking, this is the Session/StatelessSession that was used to create the Query instance.
        Returns:
        The producer of this query

      • getQueryString

        String getQueryString()
        Get the query string. Note that this may be null or some other less-than-useful return because the source of the query might not be a String (e.g., a Criteria query).
        Returns:
        the query string.

      • applyGraph

        Query<R> applyGraph​(RootGraph<?> graph,
                    GraphSemantic semantic)
        Apply the given graph using the given semantic
        Parameters:
        graph - The graph the apply.
        semantic - The semantic to use when applying the graph
        Returns:
        this - for method chaining

      • scroll

        ScrollableResults<R> scroll​(ScrollMode scrollMode)
        Returns scrollable access to the query results. The capabilities of the returned ScrollableResults depend on the specified ScrollMode.
        "API Note:"
        The exact behavior of this method depends somewhat on the JDBC driver's ResultSet scrolling support

      • list

        List<R> list()
        Return the query results as a List. If the query contains multiple results per row, the results are returned in an instance of Object[].
        Returns:
        the result list

      • uniqueResult

        R uniqueResult()
        Convenience method to return a single instance that matches the query, or null if the query returns no results.
        Returns:
        the single result or null
        Throws:
        NonUniqueResultException - if there is more than one matching result

      • uniqueResultOptional

        Optional<R> uniqueResultOptional()

      • stream

        Stream<R> stream()
        Retrieve a Stream over the query results.

        In the initial implementation (5.2) this returns a simple sequential Stream. The plan is to return a a smarter stream in 6.x leveraging the SQM model.

        You should call BaseStream.close() after processing the stream so that the underlying resources are deallocated right away.

        Returns:
        The results Stream
        Since:
        5.2

      • getComment

        String getComment()
        Obtain the comment currently associated with this query. Provided SQL commenting is enabled (generally by enabling the hibernate.use_sql_comments config setting), this comment will also be added to the SQL query sent to the database. Often useful for identifying the source of troublesome queries on the database side.
        Returns:
        The comment.

      • setComment

        Query<R> setComment​(String comment)
        Set the comment for this query.
        Parameters:
        comment - The human-readable comment
        Returns:
        this, for method chaining
        See Also:
        getComment()

      • addQueryHint

        Query<R> addQueryHint​(String hint)
        Add a DB query hint to the SQL. These differ from JPA's QueryHint and Query.getHints(), which is specific to the JPA implementation and ignores DB vendor-specific hints. Instead, these are intended solely for the vendor-specific hints, such as Oracle's optimizers. Multiple query hints are supported; the Dialect will determine concatenation and placement.
        Parameters:
        hint - The database specific query hint to add.

      • getLockOptions

        LockOptions getLockOptions()
        Obtains the LockOptions in effect for this query.
        Returns:
        The LockOptions
        See Also:
        LockOptions

      • setLockMode

        Query<R> setLockMode​(String alias,
                     LockMode lockMode)
        Set the LockMode to use for specific alias (as defined in the query's FROM clause).

        The alias-specific lock modes specified here are added to the query's internal LockOptions.

        The effect of these alias-specific LockModes is somewhat dependent on the driver/database in use. Generally speaking, for maximum portability, this method should only be used to mark that the rows corresponding to the given alias should be included in pessimistic locking (LockMode.PESSIMISTIC_WRITE).

        Parameters:
        alias - a query alias, or "this" for a collection filter
        lockMode - The lock mode to apply.
        Returns:
        this, for method chaining
        See Also:
        getLockOptions()

      • getQueryOptions

        QueryOptions getQueryOptions()
        Get the execution options for this Query. Many of the setter on the Query contract update the state of the returned QueryOptions. This is important because it gives access to any primitive data in their wrapper forms rather than the primitive forms as required by JPA. For example, that allows use to know whether a specific value has been set at all by the Query consumer.
        Returns:
        Return the encapsulation of this query's options, which includes access to firstRow, maxRows, timeout and fetchSize, etc.

      • getParameterMetadata

        ParameterMetadata getParameterMetadata()
        Access to information about query parameters.
        Returns:
        information about query parameters.

      • setParameter

        <T> Query<R> setParameter​(QueryParameter<T> parameter,
                          T val)
        Bind a query parameter using its inferred Type. If the parameter is defined in such a way that the Type cannot be inferred from its usage context then use of this form of binding is not allowed, and setParameter(QueryParameter, Object, AllowableParameterType) should be used instead
        Parameters:
        parameter - The query parameter memento
        val - the possibly-null parameter value
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(String name,
                          P val,
                          AllowableParameterType<P> type)
        Bind a named query parameter using the supplied Type
        Parameters:
        name - the name of the parameter
        val - the possibly-null parameter value
        type - the Hibernate allowable parameter type
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(int position,
                          P val,
                          AllowableParameterType<P> type)
        Bind a value to a JDBC-style query parameter.
        Parameters:
        position - the position of the parameter in the query string, numbered from 0.
        val - the possibly-null parameter value
        type - the Hibernate allowable parameter type
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(String name,
                          P val,
                          BasicTypeReference<P> type)
        Bind a named query parameter using the supplied Type
        Parameters:
        name - the name of the parameter
        val - the possibly-null parameter value
        type - the Hibernate allowable parameter type
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(int position,
                          P val,
                          BasicTypeReference<P> type)
        Bind a value to a JDBC-style query parameter.
        Parameters:
        position - the position of the parameter in the query string, numbered from 0.
        val - the possibly-null parameter value
        type - the Hibernate allowable parameter type
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(String name,
                          P val,
                          TemporalType temporalType)
        Bind a named query parameter as some form of date/time using the indicated temporal-type.
        Parameters:
        name - the parameter name
        val - the possibly-null parameter value
        temporalType - the temporal-type to use in binding the date/time
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(int position,
                          P val,
                          TemporalType temporalType)
        Bind a positional query parameter as some form of date/time using the indicated temporal-type.
        Parameters:
        position - the position of the parameter in the query string, numbered from 0.
        val - the possibly-null parameter value
        temporalType - the temporal-type to use in binding the date/time
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(QueryParameter<P> parameter,
                          P val,
                          TemporalType temporalType)
        Bind a query parameter as some form of date/time using the indicated temporal-type.
        Parameters:
        parameter - The query parameter memento
        val - the possibly-null parameter value
        temporalType - the temporal-type to use in binding the date/time
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(QueryParameter<P> parameter,
                          P val,
                          AllowableParameterType<P> type)
        Bind a query parameter using the supplied Type
        Parameters:
        parameter - The query parameter memento
        val - the possibly-null parameter value
        type - the Hibernate allowable parameter type
        Returns:
        this, for method chaining

      • setParameter

        <P> Query<R> setParameter​(QueryParameter<P> parameter,
                          P val,
                          BasicTypeReference<P> type)
        Bind a query parameter using the supplied Type
        Parameters:
        parameter - The query parameter memento
        val - the possibly-null parameter value
        type - the Hibernate allowable parameter type
        Returns:
        this, for method chaining

      • setTimeout

        Query<R> setTimeout​(int timeout)
        Description copied from interface: CommonQueryContract
        Set the query timeout in seconds. NOTE it is important to understand that any value set here is eventually passed directly through to the JDBC Statement which expressly disallows negative values. So negative values should be avoided as a general rule.
        Specified by:
        setTimeout in interface CommonQueryContract
        Parameters:
        timeout - the timeout in seconds
        Returns:
        this, for method chaining
        See Also:
        CommonQueryContract.getTimeout()

      • setParameter

        Query<R> setParameter​(String name,
                      Object value)
        Bind a named query parameter using its inferred Type. If the parameter is defined in such a way that the Type cannot be inferred from its usage context then use of this form of binding is not allowed, and setParameter(String, Object, AllowableParameterType) should be used instead
        Specified by:
        setParameter in interface Query
        Specified by:
        setParameter in interface TypedQuery<R>
        Parameters:
        name - the parameter name
        value - the (possibly-null) parameter value
        Returns:
        this, for method chaining

      • setParameter

        Query<R> setParameter​(int position,
                      Object value)
        Bind a positional query parameter using its inferred Type. If the parameter is defined in such a way that the Type cannot be inferred from its usage context then use of this form of binding is not allowed, and setParameter(int, Object, AllowableParameterType) should be used instead
        Specified by:
        setParameter in interface Query
        Specified by:
        setParameter in interface TypedQuery<R>
        Parameters:
        position - the position of the parameter in the query string, numbered from 0.
        value - the possibly-null parameter value
        Returns:
        this, for method chaining

      • setParameterList

        <P> Query<R> setParameterList​(QueryParameter<P> parameter,
                              Collection<P> values)
        Bind multiple values to a query parameter using its inferred Type. The Hibernate type of the parameter values is first detected via the usage/position in the query and if not sufficient secondly guessed from the class of the first object in the collection. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        parameter - the parameter memento
        values - a collection of values to list
        Returns:
        this, for method chaining

      • setParameterList

        Query<R> setParameterList​(String name,
                          Collection<?> values)
        Bind multiple values to a named query parameter. The Hibernate type of the parameter is first detected via the usage/position in the query and if not sufficient secondly guessed from the class of the first object in the collection. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        name - the name of the parameter
        values - a collection of values to list
        Returns:
        this, for method chaining

      • setParameterList

        Query<R> setParameterList​(int position,
                          Collection<?> values)
        Bind multiple values to a positional query parameter. The Hibernate type of the parameter is first detected via the usage/position in the query and if not sufficient secondly guessed from the class of the first object in the collection. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        position - the parameter positional label
        values - a collection of values to list
        Returns:
        this, for method chaining

      • setParameterList

        <P> Query<R> setParameterList​(String name,
                              Collection<? extends P> values,
                              Class<P> type)
        Bind multiple values to a named query parameter. The Hibernate type of the parameter is first detected via the usage/position in the query and if not sufficient secondly guessed from the class of the first object in the collection. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        name - the name of the parameter
        values - a collection of values to list
        Returns:
        this, for method chaining

      • setParameterList

        <P> Query<R> setParameterList​(int position,
                              Collection<? extends P> values,
                              Class<P> type)
        Bind multiple values to a positional query parameter. The Hibernate type of the parameter is first detected via the usage/position in the query and if not sufficient secondly guessed from the class of the first object in the collection. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        position - the parameter positional label
        values - a collection of values to list
        Returns:
        this, for method chaining

      • setParameterList

        <P> Query<R> setParameterList​(String name,
                              Collection<? extends P> values,
                              AllowableParameterType<P> type)
        Bind multiple values to a named query parameter. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        name - the name of the parameter
        values - a collection of values to list
        type - the Hibernate allowable parameter type of the values
        Returns:
        this, for method chaining

      • setParameterList

        <P> Query<R> setParameterList​(int position,
                              Collection<? extends P> values,
                              AllowableParameterType<P> type)
        Bind multiple values to a positional query parameter. This is useful for binding a list of values to an expression such as foo.bar in (?1).
        Parameters:
        position - the parameter positional label
        values - a collection of values to list
        type - the Hibernate allowable parameter type of the values
        Returns:
        this, for method chaining

      • setParameterList

        Query<R> setParameterList​(String name,
                          Object[] values,
                          AllowableParameterType<?> type)
        Bind multiple values to a named query parameter. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        name - the name of the parameter
        values - a collection of values to list
        type - the Hibernate type of the values
        Returns:
        this, for method chaining

      • setParameterList

        Query<R> setParameterList​(int position,
                          Object[] values,
                          AllowableParameterType<?> type)
        Bind multiple values to a named query parameter. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        position - the parameter positional label
        values - a collection of values to list
        type - the Hibernate type of the values
        Returns:
        this, for method chaining

      • setParameterList

        Query<R> setParameterList​(String name,
                          Object[] values)
        Bind multiple values to a named query parameter. The Hibernate type of the parameter is first detected via the usage/position in the query and if not sufficient secondly guessed from the class of the first object in the array. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        name - the name of the parameter
        values - a collection of values to list
        Returns:
        this, for method chaining

      • setParameterList

        Query<R> setParameterList​(int position,
                          Object[] values)
        Bind multiple values to a named query parameter. The Hibernate type of the parameter is first detected via the usage/position in the query and if not sufficient secondly guessed from the class of the first object in the array. This is useful for binding a list of values to an expression such as foo.bar in (:value_list).
        Parameters:
        position - the parameter positional label
        values - a collection of values to list
        Returns:
        this, for method chaining

      • setProperties

        Query<R> setProperties​(Object bean)
        Bind the property values of the given bean to named parameters of the query, matching property names with parameter names and mapping property types to Hibernate types using heuristics.
        Parameters:
        bean - any JavaBean or POJO
        Returns:
        this, for method chaining

      • setProperties

        Query<R> setProperties​(Map bean)
        Bind the values of the given Map for each named parameters of the query, matching key names with parameter names and mapping value types to Hibernate types using heuristics.
        Parameters:
        bean - a java.util.Map
        Returns:
        this, for method chaining