org.hibernate.procedure.package-info Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of hibernate-core Show documentation

Hibernate's core ORM functionality

There is a newer version: 7.0.0.Alpha1

/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or .
 */
package org.hibernate.procedure;

/**
 * Defines support for executing database stored procedures and functions and accessing its outputs.
 * 
 * First a reference to  {@link ProcedureCall} is obtained through one of the overloaded
 * {@link org.hibernate.Session#createStoredProcedureCall} methods.  The ProcedureCall reference is then used to "configure"
 * the procedure call (set timeouts, etc) and to perform parameter registration.  All procedure parameters that the
 * application wants to use must be registered.  For all IN and INOUT parameters, values can then be bound.
 * 

 * At this point we are ready to execute the procedure call and start accessing the outputs.  This is done by first
 * calling the {@link ProcedureCall#getResult()} method.  The underlying JDBC call is executed as needed.  The pattern to
 * access the returns is iterating through the outputs while {@link ProcedureResult#hasMoreReturns()} returns {@code true} and
 * calling {@link ProcedureResult#getNextReturn()} during iteration:
 * 
 *     ProcedureCall call = session.createStoredProcedureCall( "some_procedure" );
 *     ...
 *     ProcedureResult result = call.getResult();
 *     while ( result.hasMoreReturns() ) {
 *         final Return rtn = result.getNextReturn();
 *         if ( rtn.isResultSet() ) {
 *             handleResultSetReturn( (ResultSetReturn) rtn );
 *         }
 *         else {
 *             handleUpdateCountReturn( (UpdateCountReturn) rtn );
 *         }
 *     }
 * 
 * 
 * Finally output parameters can be accessed using the overloaded {@link ProcedureResult#getOutputParameterValue} methods.
 * For portability amongst databases, it is advised to access the output parameters after all returns have been
 * processed.
 *
 * @see org.hibernate.Session#createStoredProcedureCall(String)
 * @see org.hibernate.Session#createStoredProcedureCall(String, Class[])
 * @see org.hibernate.Session#createStoredProcedureCall(String, String...)
 */