com.iplanet.jato.model.sql
Class StoredProcModelBase

java.lang.Object
  |
  +--com.iplanet.jato.model.DefaultModel
        |
        +--com.iplanet.jato.model.sql.ResultSetModelBase
              |
              +--com.iplanet.jato.model.sql.StoredProcModelBase
All Implemented Interfaces:
ContextualModel, DatasetModel, ExecutingModel, Model, RequestParticipant, java.io.Serializable, SQLModel, StoredProcModel

public class StoredProcModelBase
extends ResultSetModelBase
implements StoredProcModel, RequestParticipant

A model implementation that uses a stored procedure as its backing data store

Version:
JATO/1.2.2 $Id: StoredProcModelBase.java,v 1.24 2002/03/16 03:26:34 todd Exp $
See Also:
StoredProcSchema, StoredProcParameterDescriptor, Serialized Form

Inner classes inherited from class com.iplanet.jato.model.DefaultModel
DefaultModel.Context, DefaultModel.RowValueArrayList
 
Field Summary
static boolean DEBUG_TRACE_PROC
           
protected static boolean OPTION_UNILATERALLY_REGISTER_INPUT_TYPE
          In general, we do not recommend setting this value to true, as it may require the values provided to the JDBC driver to be coerced to either a specific Java type or a JDBC-driver specific type (Oracle does the latter for example).
static java.lang.String RESULT_PARAM_NAME
           
 
Fields inherited from class com.iplanet.jato.model.sql.ResultSetModelBase
DEBUG_NEXTROW, DEBUG_POS_RESULTSET, DEBUG_SYNCROW, DEBUG_UPDATE_MODEL, OPTION_COERCE_CACHED_RESULT_SET_VALUES, OPTION_COERCE_VALUE_TYPES, SYNCROW_ALREADY_SYNCHRONIZED, SYNCROW_FOUND_DATA, SYNCROW_NO_MORE_DATA
 
Fields inherited from class com.iplanet.jato.model.DefaultModel
DEFAULT_CONTEXT_NAME, UNDEFINED_ROW_INDEX
 
Constructor Summary
StoredProcModelBase()
          Default constructor
StoredProcModelBase(StoredProcSchema schema)
          Creates a StoredProcModelBase object
 
Method Summary
protected  void afterExecute(ModelExecutionContext context, java.sql.CallableStatement statement)
          Invoked as notification that this model has just successfully completed execution.
protected  java.lang.String beforeExecute(ModelExecutionContext context, java.lang.String sql)
          Invoked as notification that this model is about to be executed.
 void clear()
          Clears all values (from all rows) in this model
 void clearParameterValues()
          Clears all cached parameter values.
protected  java.lang.String constructProcedureSQL()
           
 java.lang.Object execute(ModelExecutionContext context)
          Execute the model.
 java.lang.Object executeProcedure(ModelExecutionContext context)
          Executes the model's associated stored procedure, using the provided execution context
 java.lang.String getDataSourceName()
          Returns the logical name of the SQL datasource this model uses.
 java.sql.Connection getDefaultConnection()
          Returns a default JDBC connection.
 java.lang.String getDefaultConnectionPassword()
          Return the password that will be used when allocating a default JDBC connection.
 java.lang.String getDefaultConnectionUser()
          Return the username that will be used when allocating a default JDBC connection.
 java.lang.Class getFieldClass(java.lang.String name)
          We override this method in the subclass in order to allow lookup of a field type that is either a parameter or a result set column.
 java.util.Map getOtherSQLTypeMap()
           
 java.lang.Object getParameterValue(java.lang.String name)
          Returns the named parameter value.
 StoredProcSchema getProcedureSchema()
          Returns the schema containing the procedure metadata
 RequestContext getRequestContext()
          Returns the current request context
 java.lang.Object getResultParameterValue()
          Returns the result parameter value from the last execution of the procedure
 java.lang.Object getValue(java.lang.String name)
          Returns a named value from this model.
 java.lang.Object[] getValues(java.lang.String name)
          Returns a named set of values from this model.
protected  java.lang.Object mapOutputParameters(java.sql.CallableStatement statement)
          Copies the CallableStatement output parameters into the model's value cache.
protected  java.sql.ResultSet obtainResultSet(java.sql.CallableStatement statement)
          Return the callable statement's result set.
protected  void onDatabaseError(ModelExecutionContext context, java.sql.SQLException exception)
          Invoked as notification that this model encountered a SQLException.
protected  void registerParameters(java.sql.CallableStatement statement)
          Prepares the CallableStatement prior to execution.
 void removeParameterValue(java.lang.String name)
          Removes the named parameter value.
 void setDataSourceName(java.lang.String value)
          Sets the logical name of the SQL datasource this model uses.
 void setDefaultConnectionPassword(java.lang.String value)
          Set the password that will be used when allocating a default JDBC connection.
 void setDefaultConnectionUser(java.lang.String value)
          Set the username that will be used when allocating a default JDBC connection.
 void setOtherSQLTypeMap(java.util.Map value)
           
 void setParameterValue(java.lang.String name, java.lang.Object value)
          Sets the named parameter value.
 void setProcedureSchema(StoredProcSchema value)
          Sets the schema that is used by this model to prepare the stored procedure statement.
 void setRequestContext(RequestContext value)
          Sets the request context
protected  void setResultParameterValue(java.lang.Object value)
          Sets the RESULT parameter value.
 
Methods inherited from class com.iplanet.jato.model.sql.ResultSetModelBase
beforeFirst, clearResultSet, first, getFieldSchema, getLocation, getLocationOffset, getResultSet, getSize, getValueMap, hasMoreResults, hasPreviousResults, hasValue, last, next, positionResultSet, positionResultSet, previous, resolveResultSetColumnSet, setFieldSchema, setLocation, setLocationOffset, setMoreResults, setPreviousResults, setResultSet, setSize, setValue, setValues, synchronizeRow, updateModel
 
Methods inherited from class com.iplanet.jato.model.DefaultModel
addContext, appendRow, checkRowIndex, clearModelData, createValueMap, dumpValues, dumpValues, ensureRow, getContext, getContextNames, getCurrentContext, getCurrentContextName, getDefaultValue, getDefaultValueMap, getDefaultValues, getName, getNumRows, getRowIndex, getRowList, getValueMap, initializeDefaultContext, insertRow, isDefaultContext, isUseDefaultValues, removeContext, selectContext, selectDefaultContext, setDefaultValue, setDefaultValues, setName, setNumRows, setRowIndex, setRowList, setUseDefaultValues
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.iplanet.jato.model.Model
getName, setName, setValue, setValues
 

Field Detail

RESULT_PARAM_NAME

public static final java.lang.String RESULT_PARAM_NAME

DEBUG_TRACE_PROC

public static final boolean DEBUG_TRACE_PROC

OPTION_UNILATERALLY_REGISTER_INPUT_TYPE

protected static final boolean OPTION_UNILATERALLY_REGISTER_INPUT_TYPE
In general, we do not recommend setting this value to true, as it may require the values provided to the JDBC driver to be coerced to either a specific Java type or a JDBC-driver specific type (Oracle does the latter for example).
Constructor Detail

StoredProcModelBase

public StoredProcModelBase()
Default constructor

StoredProcModelBase

public StoredProcModelBase(StoredProcSchema schema)
Creates a StoredProcModelBase object
Parameters:
schema - The schema containing the procedure metadata
Method Detail

getDataSourceName

public java.lang.String getDataSourceName()
Description copied from interface: SQLModel
Returns the logical name of the SQL datasource this model uses. This name can be arbitrary, but is likely to be of the JNDI form described in the JDBC 2.0 Standard Extension specification, or use withing a J2EE-compliant container; for example, jdbc/MyDataSource or jdbc/MyApp/MyDataSource
Specified by:
getDataSourceName in interface SQLModel
Following copied from interface: com.iplanet.jato.model.sql.SQLModel
Returns:
The logical datasource name

setDataSourceName

public void setDataSourceName(java.lang.String value)
Sets the logical name of the SQL datasource this model uses. This name can be arbitrary, but should generally be of the JNDI form described in the JDBC 2.0 Standard Extension specification, for use within a J2EE-compliant container; for example, jdbc/MyDataSource or jdbc/MyApp/MyDataSource
Parameters:
value - The logical datasource name

getProcedureSchema

public StoredProcSchema getProcedureSchema()
Description copied from interface: StoredProcModel
Returns the schema containing the procedure metadata
Specified by:
getProcedureSchema in interface StoredProcModel

setProcedureSchema

public void setProcedureSchema(StoredProcSchema value)
Sets the schema that is used by this model to prepare the stored procedure statement.
Parameters:
value - The schema containing the procedure metadata

beforeExecute

protected java.lang.String beforeExecute(ModelExecutionContext context,
                                         java.lang.String sql)
                                  throws ModelControlException
Invoked as notification that this model is about to be executed. The reason this and similar methods exist is to provide the subclass developer a chance to perform model-specific pre-execution logic. This method is invoked regardless of the mode of model execution. The default implementation of this method simply allows the execution to proceed.
Parameters:
context - The ModelExecutionContext specific to the current execution.
sql - The SQL program.
Returns:
The SQL program
Throws:
ModelControlException -  

afterExecute

protected void afterExecute(ModelExecutionContext context,
                            java.sql.CallableStatement statement)
                     throws ModelControlException
Invoked as notification that this model has just successfully completed execution. The reason this and similar methods exist is to provide the subclass developer a chance to perform model-specific post-execution logic. This method is only invoked following a successful execution. If the execution resulted in a SQL exception, then onDatabaseError is invoked instead.
Parameters:
context - The ModelExecutionContext specific to the current execution.
statement - The CallableStatement that was just executed.
Throws:
ModelControlException -  

onDatabaseError

protected void onDatabaseError(ModelExecutionContext context,
                               java.sql.SQLException exception)
Invoked as notification that this model encountered a SQLException. The reason this and similar methods exist is to provide the subclass developer a chance to perform model-specific error handling logic.
Parameters:
context - The ModelExecutionContext specific to the current execution.
exception - The SQLException.

execute

public java.lang.Object execute(ModelExecutionContext context)
                         throws ModelControlException
Description copied from interface: ExecutingModel
Execute the model. The execution context may contain an operation name that specifies the particular operation to execute.
Specified by:
execute in interface ExecutingModel
Following copied from interface: com.iplanet.jato.model.ExecutingModel
Parameters:
context - The execution context that specifies detail information pertinent to the execution of this model
Returns:
An opaque implementation-dependent object encapsulating information related to the execution of this method
Throws:
ModelControlException - Thrown if an error occurs executing the model

executeProcedure

public java.lang.Object executeProcedure(ModelExecutionContext context)
                                  throws java.sql.SQLException,
                                         ModelControlException
Description copied from interface: StoredProcModel
Executes the model's associated stored procedure, using the provided execution context
Specified by:
executeProcedure in interface StoredProcModel
Following copied from interface: com.iplanet.jato.model.sql.StoredProcModel
Parameters:
context - The execution context to be used during the execution of this query
Returns:
The result parameter value from the execution of the procedure. The object returned by this method is generally also available via the getResultParameterValue() method.

obtainResultSet

protected java.sql.ResultSet obtainResultSet(java.sql.CallableStatement statement)
                                      throws java.sql.SQLException
Return the callable statement's result set. This method exists because obtaining a result set from a stored procedure may unfortunately be a non-standard operation. This method attemtps to use the standard mechanism to obtain a resut set (via a call to getResutSet(). If your JDBC driver requires a different technique, override this method to retrieve the result in the proper way. Also, note that this model implementation only supports the return of a single result set (via this method).
Parameters:
statement - The most-recently executed CallableStatement object, potentially containing a result set.
Returns:
A result set, if one was returned with the statement's last execution. This method should return null if no result set was returned.

getRequestContext

public RequestContext getRequestContext()
Returns the current request context
Returns:
The request context for the current servlet request

setRequestContext

public void setRequestContext(RequestContext value)
Description copied from interface: RequestParticipant
Sets the request context
Specified by:
setRequestContext in interface RequestParticipant
Following copied from interface: com.iplanet.jato.RequestParticipant
Parameters:
requestContext - The request context of the current request

getDefaultConnection

public java.sql.Connection getDefaultConnection()
                                         throws java.sql.SQLException
Returns a default JDBC connection. The default connection will be used if no explicit connection is provided at model execution time via a SQLModelExecutionContext.

getDefaultConnectionUser

public java.lang.String getDefaultConnectionUser()
Return the username that will be used when allocating a default JDBC connection. This username will not be used if a connection or statement is provided during execution.

setDefaultConnectionUser

public void setDefaultConnectionUser(java.lang.String value)
Set the username that will be used when allocating a default JDBC connection. This username will not be used if a connection or statement is provided during execution. A value of null will result in a username & password not being used when obtaining a default connection. Note: this value may not be necessary if the JDBC connection string or JDBC DataSource includes or has already been configured to use a username & password.
Parameters:
value - A valid username, or null to disable use of a username & password when obtaining a default connection

getDefaultConnectionPassword

public java.lang.String getDefaultConnectionPassword()
Return the password that will be used when allocating a default JDBC connection. This password will not be used if a connection or statement is provided during execution.

setDefaultConnectionPassword

public void setDefaultConnectionPassword(java.lang.String value)
Set the password that will be used when allocating a default JDBC connection. This password will not be used if a connection or statement is provided during execution. Note: this value may not be necessary if the JDBC connection string or JDBC DataSource includes or has already been configured to use a username & password.
Parameters:
value - A valid password for the current default connection user

constructProcedureSQL

protected java.lang.String constructProcedureSQL()

registerParameters

protected void registerParameters(java.sql.CallableStatement statement)
                           throws java.sql.SQLException
Prepares the CallableStatement prior to execution. This method is used internally to prepare the CallableStatement prior to its execution by setting any input parameter values and registering any output and/or result parameters.
Parameters:
statement - The CallableStatement prior to its execution.
Throws:
java.sql.SQLException -  

mapOutputParameters

protected java.lang.Object mapOutputParameters(java.sql.CallableStatement statement)
                                        throws java.sql.SQLException
Copies the CallableStatement output parameters into the model's value cache. This method is used internally to store the output parameter values (if any) in the model's local data cache.
Parameters:
statement - The CallableStatement that was just executed.

getOtherSQLTypeMap

public java.util.Map getOtherSQLTypeMap()

setOtherSQLTypeMap

public void setOtherSQLTypeMap(java.util.Map value)

getFieldClass

public java.lang.Class getFieldClass(java.lang.String name)
We override this method in the subclass in order to allow lookup of a field type that is either a parameter or a result set column.
Overrides:
getFieldClass in class ResultSetModelBase

getValue

public java.lang.Object getValue(java.lang.String name)
Returns a named value from this model. This method extends that in the base class to add provisions for lookup of parameter values.
Specified by:
getValue in interface Model
Overrides:
getValue in class DefaultModel
Parameters:
name - The name of the value to return
Returns:
The specified value. If the model has multiple values for the specified name, the first value is returned. If there is no value for the specified name, this method returns null.

getValues

public java.lang.Object[] getValues(java.lang.String name)
Returns a named set of values from this model. This method extends that in the base class to add provisions for lookup of parameter values.
Specified by:
getValues in interface Model
Overrides:
getValues in class DefaultModel
Parameters:
name - The name of the value set to return
Returns:
The specified set of values. If there is no value for the specified name, this method returns an array of zero length.

getResultParameterValue

public java.lang.Object getResultParameterValue()
Description copied from interface: StoredProcModel
Returns the result parameter value from the last execution of the procedure
Specified by:
getResultParameterValue in interface StoredProcModel

setResultParameterValue

protected void setResultParameterValue(java.lang.Object value)
Sets the RESULT parameter value. This method is used internally to store the result parameter value (if any) in the model's local data cache.
Parameters:
value - The value of the RESULT parameter

getParameterValue

public java.lang.Object getParameterValue(java.lang.String name)
Description copied from interface: StoredProcModel
Returns the named parameter value. This method is valid both before and after the procedure has been executed. If called before procedure execution, it returns the parameter value previously set under the specified logical parameter name (if any). After procedure execution, it returns the value of the OUT or INOUT parameter identified by the logical parameter name.
Specified by:
getParameterValue in interface StoredProcModel
Following copied from interface: com.iplanet.jato.model.sql.StoredProcModel
Parameters:
name - The logical parameter name. This name identifies the parameter descriptor that will be used to look up the physical parameter name used for procedure execution.

setParameterValue

public void setParameterValue(java.lang.String name,
                              java.lang.Object value)
Description copied from interface: StoredProcModel
Sets the named parameter value. This method is generally only valid before the procedure has been executed, when it sets the value of the IN or INOUT parameter specified by the provided logical parameter name.
Specified by:
setParameterValue in interface StoredProcModel
Following copied from interface: com.iplanet.jato.model.sql.StoredProcModel
Parameters:
name - The logical parameter name. This name identifies the parameter descriptor that will be used to look up the physical parameter name used for procedure execution.
value - The value of the IN or INOUT parameter to set

removeParameterValue

public void removeParameterValue(java.lang.String name)
Description copied from interface: StoredProcModel
Removes the named parameter value. This method is generally only valid before the procedure has been executed, when it clears the value of the IN, INOUT, or OUT parameter specified by the provided logical parameter name.
Specified by:
removeParameterValue in interface StoredProcModel
Following copied from interface: com.iplanet.jato.model.sql.StoredProcModel
Parameters:
name - The logical parameter name. This name identifies the parameter descriptor that will be used to look up the physical parameter name used for procedure execution.

clearParameterValues

public void clearParameterValues()
Description copied from interface: StoredProcModel
Clears all cached parameter values. This method is generally only valid before the procedure has been executed, when it clears the cached values of all IN, INOUT, or OUT parameters.
Specified by:
clearParameterValues in interface StoredProcModel

clear

public void clear()
Description copied from class: DefaultModel
Clears all values (from all rows) in this model
Overrides:
clear in class ResultSetModelBase