org.hibernate.procedure

Interface ProcedureCall

All Superinterfaces:

AutoCloseable, CommonQueryContract, NameableQuery, Query, StoredProcedureQuery, SynchronizeableQuery

All Known Subinterfaces:

ProcedureCallImplementor<R>

public interface ProcedureCall
extends CommonQueryContract, SynchronizeableQuery, 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 Summary

Fields

Modifier and Type	Field and Description
static 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)

Method Summary

Modifier and Type	Method and Description
ProcedureCall	addSynchronizedEntityClass(Class entityClass) Adds an entity for (a) auto-flush checking and (b) query result cache invalidation checking.
ProcedureCall	addSynchronizedEntityName(String entityName) Adds an entity name for (a) auto-flush checking and (b) query result cache invalidation checking.
ProcedureCall	addSynchronizedQuerySpace(String querySpace) Adds a query space.
default void	close() Release the underlying JDBC CallableStatement
ProcedureOutputs	getOutputs() Retrieves access to outputs of this procedure call.
ProcedureParameter	getParameterRegistration(int position) Retrieve a previously registered parameter memento by the position under which it was registered.
ProcedureParameter	getParameterRegistration(String name) Retrieve a previously registered parameter memento by the name under which it was registered.
String	getProcedureName() Get the name of the stored procedure (or function) to be called.
List<ProcedureParameter>	getRegisteredParameters() Retrieve all registered parameters.
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).
ProcedureCall	markAsFunctionCall(int sqlType) Mark this ProcedureCall as representing a call to a database function, rather than a database procedure.
<T> ProcedureParameter<T>	registerParameter(int position, Class<T> type, ParameterMode mode) Basic form for registering a positional parameter.
<T> ProcedureParameter<T>	registerParameter(String parameterName, Class<T> type, ParameterMode mode) Basic form for registering a named parameter.
<T> ProcedureCall	registerParameter0(int position, Class<T> type, ParameterMode mode) Chained form of registerParameter(int, Class, javax.persistence.ParameterMode)
ProcedureCall	registerParameter0(String parameterName, Class type, ParameterMode mode) Chained form of registerParameter(String, Class, javax.persistence.ParameterMode)
NamedCallableQueryMemento	toMemento(String name) Convert the query into the memento

Methods inherited from interface org.hibernate.query.CommonQueryContract

getCacheMode, getCacheRegion, getFetchSize, getHibernateFlushMode, getTimeout, isCacheable, isReadOnly, setCacheable, setCacheMode, setCacheRegion, setFetchSize, setHibernateFlushMode, setReadOnly, setTimeout

Methods inherited from interface org.hibernate.SynchronizeableQuery

addSynchronizedEntityClass, addSynchronizedEntityName, addSynchronizedQuerySpace, addSynchronizedTable, addSynchronizedTable, getSynchronizedQuerySpaces

Methods inherited from interface javax.persistence.StoredProcedureQuery

execute, executeUpdate, getOutputParameterValue, getOutputParameterValue, getResultList, getSingleResult, getUpdateCount, hasMoreResults, registerStoredProcedureParameter, registerStoredProcedureParameter, setFlushMode, setHint, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter

Methods inherited from interface javax.persistence.Query

getFirstResult, getFlushMode, getHints, getLockMode, getMaxResults, getParameter, getParameter, getParameter, getParameter, getParameters, getParameterValue, getParameterValue, getParameterValue, getResultStream, isBound, setFirstResult, setLockMode, setMaxResults, unwrap

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

registerParameter

<T> ProcedureParameter<T> registerParameter(int position,
                                            Class<T> type,
                                            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

registerParameter0

<T> ProcedureCall registerParameter0(int position,
                                     Class<T> type,
                                     ParameterMode mode)

Chained form of registerParameter(int, Class, javax.persistence.ParameterMode)

Parameters:

position - The position

type - The Java type of the parameter

mode - The parameter mode (in, out, inout)

Returns:

this, for method chaining

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,
                                            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.

registerParameter0

ProcedureCall registerParameter0(String parameterName,
                                 Class type,
                                 ParameterMode mode)
                          throws NamedParametersNotSupportedException

Chained form of registerParameter(String, Class, javax.persistence.ParameterMode)

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.

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

close

default void close()

Release the underlying JDBC CallableStatement

Specified by:

close in interface AutoCloseable

addSynchronizedQuerySpace

ProcedureCall addSynchronizedQuerySpace(String querySpace)

Description copied from interface: SynchronizeableQuery

Adds a query space.

Specified by:

addSynchronizedQuerySpace in interface SynchronizeableQuery

Parameters:

querySpace - The query space to be auto-flushed for this query.

Returns:

this, for method chaining

addSynchronizedEntityName

ProcedureCall addSynchronizedEntityName(String entityName)
                                 throws MappingException

Description copied from interface: SynchronizeableQuery

Adds an entity name for (a) auto-flush checking and (b) query result cache invalidation checking. Same as SynchronizeableQuery.addSynchronizedQuerySpace(java.lang.String) for all tables associated with the given entity.

Specified by:

addSynchronizedEntityName in interface SynchronizeableQuery

Parameters:

entityName - The name of the entity upon whose defined query spaces we should additionally synchronize.

Returns:

this, for method chaining

Throws:

MappingException - Indicates the given name could not be resolved as an entity

addSynchronizedEntityClass

ProcedureCall addSynchronizedEntityClass(Class entityClass)
                                  throws MappingException

Description copied from interface: SynchronizeableQuery

Adds an entity for (a) auto-flush checking and (b) query result cache invalidation checking. Same as SynchronizeableQuery.addSynchronizedQuerySpace(java.lang.String) for all tables associated with the given entity.

Specified by:

addSynchronizedEntityClass in interface SynchronizeableQuery

Parameters:

entityClass - The class of the entity upon whose defined query spaces we should additionally synchronize.

Returns:

this, for method chaining

Throws:

MappingException - Indicates the given class could not be resolved as an entity

toMemento

NamedCallableQueryMemento toMemento(String name)

Description copied from interface: NameableQuery

Convert the query into the memento

Specified by:

toMemento in interface NameableQuery