org.apache.derby.iapi.sql
Interface ParameterValueSet

All Known Implementing Classes:
GenericParameterValueSet

public interface ParameterValueSet

A ParameterValueSet is a set of parameter values that can be assembled by a JDBC driver and passed to a PreparedStatement all at once. The fact that they are all passed at once can reduce the communication overhead between client and server.

Author:
Jeff Lichtman

Method Summary
 boolean allAreSet()
          Tells whether all the parameters are set and ready for execution.
 boolean checkNoDeclaredOutputParameters()
          Check that there are not output parameters defined by the parameter set.
 void clearParameters()
          Sets all parameters to an uninitialized state.
 ParameterValueSet getClone()
          Clone the ParameterValueSet and its contents.
 java.lang.Object getObject(int parameterIndex)
          Get the value of a parameter as a Java object.
 DataValueDescriptor getParameter(int position)
          Returns the parameter at the given position.
 int getParameterCount()
          Returns the number of parameters in this set.
 DataValueDescriptor getParameterForGet(int position)
           
 DataValueDescriptor getParameterForSet(int position)
          Returns the parameter at the given position in order to set it.
 short getParameterMode(int parameterIndex)
          Return the mode of the parameter according to JDBC 3.0 ParameterMetaData
 int getPrecision(int parameterIndex)
          Return the precision of the given parameter index in this pvs.
 int getScale(int parameterIndex)
          Return the scale of the given parameter index in this pvs.
 boolean hasReturnOutputParameter()
          Is there a return output parameter in this pvs.
 boolean isUsingParameterValueSet()
          Is this pvs for using clause.
 void registerOutParameter(int parameterIndex, int sqlType, int scale)
          Mark the parameter as an output parameter.
 void setParameterAsObject(int parameterIndex, java.lang.Object value)
          Set the value of this parameter to the passed in Object.
 void setParameterMode(int position, int mode)
          Set the mode of the parameter, called when setting up static method calls and stored procedures.
 void setReturnValue(java.lang.Object value)
          Set the value of the return parameter as a Java object.
 void setStorableDataValue(DataValueDescriptor sdv, int position, int jdbcTypeId, java.lang.String className)
          Set a parameter position to a DataValueDescriptor.
 void setUsingParameterValueSet()
          Setthis pvs for using clause.
 void transferDataValues(ParameterValueSet pvstarget)
          Set the parameter values of the pvstarget to equal those set in this PVS.
 void validate()
          Validate the parameters.
 

Method Detail

setParameterMode

public void setParameterMode(int position,
                             int mode)
Set the mode of the parameter, called when setting up static method calls and stored procedures. Otherwise the parameter type will default to an IN parameter.


setStorableDataValue

public void setStorableDataValue(DataValueDescriptor sdv,
                                 int position,
                                 int jdbcTypeId,
                                 java.lang.String className)
Set a parameter position to a DataValueDescriptor. NOTE: This method assumes the caller will not pass a position that's out of range. The implementation may have an assertion that the position is in range.

Parameters:
sdv - The DataValueDescriptor to set
position - The parameter position to set it at
jdbcTypeId - The corresponding JDBC types from java.sql.Types
className - The declared class name for the type.

registerOutParameter

public void registerOutParameter(int parameterIndex,
                                 int sqlType,
                                 int scale)
                          throws StandardException
Mark the parameter as an output parameter.

Parameters:
parameterIndex - The ordinal position of a parameter to set to the given value.
sqlType - A type from java.sql.Types
scale - the scale to use. -1 means ignore scale
Throws:
StandardException - on error

getObject

public java.lang.Object getObject(int parameterIndex)
                           throws StandardException
Get the value of a parameter as a Java object.

This method returns a Java object whose type coresponds to the SQL type that was registered for this parameter using registerOutParameter.

Note that this method may be used to read datatabase-specific, abstract data types. This is done by specifying a targetSqlType of java.sql.types.OTHER, which allows the driver to return a database-specific Java type.

Parameters:
parameterIndex - The first parameter is 1, the second is 2, ...
Returns:
A java.lang.Object holding the OUT parameter value.
Throws:
StandardException - if a database-access error occurs.
See Also:
Types

clearParameters

public void clearParameters()
Sets all parameters to an uninitialized state. An exception will be thrown if the caller tries to execute a PreparedStatement when one or more parameters is uninitialized (i.e. has not had setParameterValue() called on it.

Returns:
Nothing

getParameterCount

public int getParameterCount()
Returns the number of parameters in this set.

Returns:
The number of parameters in this set.

getParameter

public DataValueDescriptor getParameter(int position)
                                 throws StandardException
Returns the parameter at the given position.

Returns:
The parameter at the given position.
Throws:
StandardException - Thrown on error

getParameterForSet

public DataValueDescriptor getParameterForSet(int position)
                                       throws StandardException
Returns the parameter at the given position in order to set it. Setting via an unknown object type must use setParameterAsObject() to ensure correct typing.

Returns:
The parameter at the given position.
Throws:
StandardException - Thrown on error

setParameterAsObject

public void setParameterAsObject(int parameterIndex,
                                 java.lang.Object value)
                          throws StandardException
Set the value of this parameter to the passed in Object.

Returns:
The parameter at the given position.
Throws:
StandardException - Thrown on error

getParameterForGet

public DataValueDescriptor getParameterForGet(int position)
                                       throws StandardException
Throws:
StandardException

allAreSet

public boolean allAreSet()
Tells whether all the parameters are set and ready for execution. OUT and Cloudscape static method INOUT parameters are not required to be set.

Returns:
true if all parameters are set, false if at least one parameter is not set.

getClone

public ParameterValueSet getClone()
Clone the ParameterValueSet and its contents.

Returns:
ParameterValueSet A clone of the ParameterValueSet and its contents.

validate

public void validate()
              throws StandardException
Validate the parameters. This is done for situations where we cannot validate everything in the setXXX() calls. In particular, before we do an execute() on a CallableStatement, we need to go through the parameters and make sure that all parameters are set up properly. The motivator for this is that setXXX() can be called either before or after registerOutputParamter(), we cannot be sure we have the types correct until we get to execute().

Throws:
StandardException - if the parameters aren't valid

hasReturnOutputParameter

public boolean hasReturnOutputParameter()
Is there a return output parameter in this pvs. A return parameter is from a CALL statement of the following syntax: ? = CALL myMethod(). Note that a return output parameter is NOT the same thing as an output parameter; it is a special type of output parameter.

Returns:
true if it has a return parameter

checkNoDeclaredOutputParameters

public boolean checkNoDeclaredOutputParameters()
Check that there are not output parameters defined by the parameter set. If there are unknown parameter types they are forced to input types. i.e. Cloudscape static method calls with parameters that are array.

Returns:
true if a declared Java Procedure INOUT or OUT parameter is in the set, false otherwise.

isUsingParameterValueSet

public boolean isUsingParameterValueSet()
Is this pvs for using clause.

Returns:
true if it has a output parameter

setUsingParameterValueSet

public void setUsingParameterValueSet()
Setthis pvs for using clause.


transferDataValues

public void transferDataValues(ParameterValueSet pvstarget)
                        throws StandardException
Set the parameter values of the pvstarget to equal those set in this PVS. Used to transfer saved SPS parameters to the actual prepared statement parameters once associated parameters have been established. Assumes pvstarget is the same length as this.

Parameters:
pvstarget - ParameterValueSet which will recieve the values
Throws:
StandardException - values not compatible

getParameterMode

public short getParameterMode(int parameterIndex)
Return the mode of the parameter according to JDBC 3.0 ParameterMetaData

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...

setReturnValue

public void setReturnValue(java.lang.Object value)
                    throws StandardException
Set the value of the return parameter as a Java object.

Parameters:
value - the return value
Throws:
StandardException - if a database-access error occurs.

getScale

public int getScale(int parameterIndex)
Return the scale of the given parameter index in this pvs.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
scale

getPrecision

public int getPrecision(int parameterIndex)
Return the precision of the given parameter index in this pvs.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
precision


Apache Derby V10.0 Engine Documentation - Copyright © 1997,2004 The Apache Software Foundation or its licensors, as applicable.