Package org.hibernate.procedure

Interface ProcedureCall

  • All Superinterfaces:
    AutoCloseable, CommonQueryContract, NameableQuery, jakarta.persistence.Query, jakarta.persistence.StoredProcedureQuery, SynchronizeableQuery
    All Known Subinterfaces:
    ProcedureCallImplementor<R>
    All Known Implementing Classes:
    ProcedureCallImpl
    public interface ProcedureCall
extends CommonQueryContract, SynchronizeableQuery, jakarta.persistence.StoredProcedureQuery, NameableQuery, AutoCloseable
    Defines support for executing database stored procedures and functions.

    Note that here we use the terms "procedure" and "function" as follows:

    • procedure is a named database executable we expect to call via : {call procedureName(...)}
    • function is a named database executable we expect to call via : {? = call functionName(...)}
    Unless explicitly specified, the ProcedureCall is assumed to follow the procedure call syntax. To explicitly specify that this should be a function call, use markAsFunctionCall(int). JPA users could either:
    • use storedProcedureQuery.unwrap( ProcedureCall.class .markAsFunctionCall()
    • set the FUNCTION_RETURN_TYPE_HINT hint (avoids casting to Hibernate-specific classes)

    When using function-call syntax:

    • parameters must be registered by position (not name)
    • The first parameter is considered to be the function return (the `?` before the call)
    • the first parameter must have mode of OUT, INOUT or REF_CURSOR; IN is invalid

    In some cases, based on the Dialect, we will have other validations and assumptions as well. For example, on PGSQL, whenever we see a REF_CURSOR mode parameter, we know that:

    • this will be a function call (so we call markAsFunctionCall(int) implicitly) because that is the only way PGSQL supports returning REF_CURSOR results.
    • there can be only one REF_CURSOR mode parameter

    • Field Detail

      • FUNCTION_RETURN_TYPE_HINT

        static final String FUNCTION_RETURN_TYPE_HINT
        The hint key (for use with JPA's "hint system") indicating the function's return JDBC type code (aka, Types code)
        See Also:
        Constant Field Values

    • Method Detail

      • getProcedureName

        String getProcedureName()
        Get the name of the stored procedure (or function) to be called.
        Returns:
        The procedure name.

      • isFunctionCall

        boolean isFunctionCall()
        Does this ProcedureCall represent a call to a database FUNCTION (as opposed to a PROCEDURE call)? NOTE : this will only report whether this ProcedureCall was marked as a function via call to markAsFunctionCall(int). Specifically will not return true when using JPA query hint.
        Returns:
        true indicates that this ProcedureCall represents a function call; false indicates a procedure call.

      • markAsFunctionCall

        ProcedureCall markAsFunctionCall​(int sqlType)
        Mark this ProcedureCall as representing a call to a database function, rather than a database procedure.
        Parameters:
        sqlType - The Types code for the function return
        Returns:
        this, for method chaining

      • markAsFunctionCall

        ProcedureCall markAsFunctionCall​(Class<?> resultType)
        Mark this ProcedureCall as representing a call to a database function, rather than a database procedure.
        Parameters:
        resultType - The result type for the function return
        Returns:
        this, for method chaining
        Since:
        6.2

      • markAsFunctionCall

        ProcedureCall markAsFunctionCall​(BasicTypeReference<?> typeReference)
        Mark this ProcedureCall as representing a call to a database function, rather than a database procedure.
        Parameters:
        typeReference - The result type for the function return
        Returns:
        this, for method chaining
        Since:
        6.2

      • registerParameter

        <T> ProcedureParameter<T> registerParameter​(int position,
                                            Class<T> type,
                                            jakarta.persistence.ParameterMode mode)
        Basic form for registering a positional parameter.
        Type Parameters:
        T - The parameterized Java type of the parameter.
        Parameters:
        position - The position
        type - The Java type of the parameter
        mode - The parameter mode (in, out, inout)
        Returns:
        The parameter registration memento

      • registerParameter

        <T> ProcedureParameter<T> registerParameter​(int position,
                                            BasicTypeReference<T> type,
                                            jakarta.persistence.ParameterMode mode)
        Basic form for registering a positional parameter.
        Type Parameters:
        T - The parameterized Java type of the parameter.
        Parameters:
        position - The position
        type - The type reference of the parameter type
        mode - The parameter mode (in, out, inout)
        Returns:
        The parameter registration memento

      • getParameterRegistration

        ProcedureParameter getParameterRegistration​(int position)
        Retrieve a previously registered parameter memento by the position under which it was registered.
        Parameters:
        position - The parameter position
        Returns:
        The parameter registration memento
        Throws:
        ParameterStrategyException - If the ProcedureCall is defined using named parameters
        NoSuchParameterException - If no parameter with that position exists

      • registerParameter

        <T> ProcedureParameter<T> registerParameter​(String parameterName,
                                            Class<T> type,
                                            jakarta.persistence.ParameterMode mode)
                                     throws NamedParametersNotSupportedException
        Basic form for registering a named parameter.
        Type Parameters:
        T - The parameterized Java type of the parameter.
        Parameters:
        parameterName - The parameter name
        type - The Java type of the parameter
        mode - The parameter mode (in, out, inout)
        Returns:
        The parameter registration memento
        Throws:
        NamedParametersNotSupportedException - When the underlying database is known to not support named procedure parameters.

      • registerParameter

        <T> ProcedureParameter<T> registerParameter​(String parameterName,
                                            BasicTypeReference<T> type,
                                            jakarta.persistence.ParameterMode mode)
                                     throws NamedParametersNotSupportedException
        Basic form for registering a named parameter.
        Type Parameters:
        T - The parameterized Java type of the parameter.
        Parameters:
        parameterName - The parameter name
        type - The type reference of the parameter type
        mode - The parameter mode (in, out, inout)
        Returns:
        The parameter registration memento
        Throws:
        NamedParametersNotSupportedException - When the underlying database is known to not support named procedure parameters.

      • getParameterRegistration

        ProcedureParameter getParameterRegistration​(String name)
        Retrieve a previously registered parameter memento by the name under which it was registered.
        Parameters:
        name - The parameter name
        Returns:
        The parameter registration memento
        Throws:
        ParameterStrategyException - If the ProcedureCall is defined using positional parameters
        NoSuchParameterException - If no parameter with that name exists

      • getRegisteredParameters

        List<ProcedureParameter> getRegisteredParameters()
        Retrieve all registered parameters.
        Returns:
        The (immutable) list of all registered parameters.

      • getOutputs

        ProcedureOutputs getOutputs()
        Retrieves access to outputs of this procedure call. Can be called multiple times, returning the same ProcedureOutputs instance each time.

        If the procedure call has not actually be executed yet, it will be executed and then the ProcedureOutputs will be returned.

        Returns:
        The ProcedureOutputs representation

      • setParameter

        <T> ProcedureCall setParameter​(jakarta.persistence.Parameter<T> param,
                               T value)
        Specified by:
        setParameter in interface CommonQueryContract
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.StoredProcedureQuery
        See Also:
        Query.setParameter(Parameter, Object)

      • setParameter

        ProcedureCall setParameter​(jakarta.persistence.Parameter<Calendar> param,
                           Calendar value,
                           jakarta.persistence.TemporalType temporalType)
        Specified by:
        setParameter in interface CommonQueryContract
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.StoredProcedureQuery
        See Also:
        Query.setParameter(Parameter, Calendar, TemporalType)

      • setParameter

        ProcedureCall setParameter​(jakarta.persistence.Parameter<Date> param,
                           Date value,
                           jakarta.persistence.TemporalType temporalType)
        Specified by:
        setParameter in interface CommonQueryContract
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.StoredProcedureQuery
        See Also:
        Query.setParameter(Parameter, Date, TemporalType)

      • setParameter

        ProcedureCall setParameter​(String name,
                           Calendar value,
                           jakarta.persistence.TemporalType temporalType)
        Specified by:
        setParameter in interface CommonQueryContract
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.StoredProcedureQuery
        See Also:
        Query.setParameter(String, Calendar, TemporalType)

      • setParameter

        ProcedureCall setParameter​(String name,
                           Date value,
                           jakarta.persistence.TemporalType temporalType)
        Specified by:
        setParameter in interface CommonQueryContract
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.StoredProcedureQuery
        See Also:
        Query.setParameter(String, Date, TemporalType)

      • setParameter

        ProcedureCall setParameter​(int position,
                           Calendar value,
                           jakarta.persistence.TemporalType temporalType)
        Specified by:
        setParameter in interface CommonQueryContract
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.StoredProcedureQuery
        See Also:
        Query.setParameter(int, Calendar, TemporalType)

      • setParameter

        ProcedureCall setParameter​(int position,
                           Date value,
                           jakarta.persistence.TemporalType temporalType)
        Specified by:
        setParameter in interface CommonQueryContract
        Specified by:
        setParameter in interface jakarta.persistence.Query
        Specified by:
        setParameter in interface jakarta.persistence.StoredProcedureQuery
        See Also:
        Query.setParameter(int, Date, TemporalType)

      • registerStoredProcedureParameter

        ProcedureCall registerStoredProcedureParameter​(int position,
                                               Class type,
                                               jakarta.persistence.ParameterMode mode)
        Specified by:
        registerStoredProcedureParameter in interface jakarta.persistence.StoredProcedureQuery

      • registerStoredProcedureParameter

        ProcedureCall registerStoredProcedureParameter​(String parameterName,
                                               Class type,
                                               jakarta.persistence.ParameterMode mode)
        Specified by:
        registerStoredProcedureParameter in interface jakarta.persistence.StoredProcedureQuery