001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.ParameterValueSet
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.sql;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: import org.apache.derby.iapi.types.DataTypeDescriptor;
027: import org.apache.derby.iapi.types.DataValueDescriptor;
028:
029: /**
030: * A ParameterValueSet is a set of parameter values that can be assembled by a
031: * JDBC driver and passed to a PreparedStatement all at once. The fact that
032: * they are all passed at once can reduce the communication overhead between
033: * client and server.
034: *
035: * @author Jeff Lichtman
036: */
037: public interface ParameterValueSet {
038: /**
039: * Initialize the parameter set by allocating DataValueDescriptor
040: * corresponding to the passed in type for each parameter.
041: * @param types expected to match the number of parameters.
042: */
043: void initialize(DataTypeDescriptor[] types);
044:
045: /**
046: Set the mode of the parameter, called when setting up static method calls and stored procedures.
047: Otherwise the parameter type will default to an IN parameter.
048: */
049: void setParameterMode(int position, int mode);
050:
051: //////////////////////////////////////////////////////////////////
052: //
053: // CALLABLE STATEMENT
054: //
055: //////////////////////////////////////////////////////////////////
056:
057: /**
058: * Mark the parameter as an output parameter.
059: *
060: * @param parameterIndex The ordinal position of a parameter to set
061: * to the given value.
062: * @param sqlType A type from java.sql.Types
063: * @param scale the scale to use. -1 means ignore scale
064: *
065: * @exception StandardException on error
066: */
067: void registerOutParameter(int parameterIndex, int sqlType, int scale)
068: throws StandardException;
069:
070: //////////////////////////////////////////////////////////////////
071: //
072: // MISC STATEMENT
073: //
074: //////////////////////////////////////////////////////////////////
075:
076: /**
077: * Sets all parameters to an uninitialized state. An exception will be
078: * thrown if the caller tries to execute a PreparedStatement when one
079: * or more parameters is uninitialized (i.e. has not had
080: * setParameterValue() called on it.
081: */
082: void clearParameters();
083:
084: /**
085: * Returns the number of parameters in this set.
086: *
087: * @return The number of parameters in this set.
088: */
089: public int getParameterCount();
090:
091: /**
092: * Returns the parameter at the given position.
093: *
094: * @return The parameter at the given position.
095: * @exception StandardException Thrown on error
096: */
097: public DataValueDescriptor getParameter(int position)
098: throws StandardException;
099:
100: /**
101: * Returns the parameter at the given position in order to set it.
102: Setting via an unknown object type must use setParameterAsObject()
103: to ensure correct typing.
104:
105: *
106: * @return The parameter at the given position.
107: * @exception StandardException Thrown on error
108: */
109: public DataValueDescriptor getParameterForSet(int position)
110: throws StandardException;
111:
112: /**
113: Set the value of this user defined parameter to the passed in Object.
114:
115: @exception StandardException Thrown on error
116: */
117: void setParameterAsObject(int parameterIndex, Object value)
118: throws StandardException;
119:
120: /**
121: * Get the DataValueDescriptor for an INOUT or OUT parameter.
122: * @param position Zero based index of the parameter.
123: * @return Parameter's value holder.
124: * @throws StandardException Position out of range or the parameter is not INOUT or OUT.
125: */
126: public DataValueDescriptor getParameterForGet(int position)
127: throws StandardException;
128:
129: /**
130: * Tells whether all the parameters are set and ready for execution.
131: OUT are not required to be set.
132: *
133: * @return true if all parameters are set, false if at least one
134: * parameter is not set.
135: */
136: boolean allAreSet();
137:
138: /**
139: * Clone the ParameterValueSet and its contents.
140: *
141: * @return ParameterValueSet A clone of the ParameterValueSet and its contents.
142: */
143: ParameterValueSet getClone();
144:
145: /**
146: * Validate the parameters. This is done for situations where
147: * we cannot validate everything in the setXXX() calls. In
148: * particular, before we do an execute() on a CallableStatement,
149: * we need to go through the parameters and make sure that
150: * all parameters are set up properly. The motivator for this
151: * is that setXXX() can be called either before or after
152: * registerOutputParamter(), we cannot be sure we have the types
153: * correct until we get to execute().
154: *
155: * @exception StandardException if the parameters aren't valid
156: */
157: void validate() throws StandardException;
158:
159: /**
160: * Is there a return output parameter in this pvs. A return
161: * parameter is from a CALL statement of the following
162: * syntax: ? = CALL myMethod(). Note that a return
163: * output parameter is NOT the same thing as an output
164: * parameter; it is a special type of output parameter.
165: *
166: * @return true if it has a return parameter
167: *
168: */
169: public boolean hasReturnOutputParameter();
170:
171: /**
172: Check that there are not output parameters defined
173: by the parameter set. If there are unknown parameter
174: types they are forced to input types. i.e. Cloudscape static method
175: calls with parameters that are array.
176:
177: @return true if a declared Java Procedure INOUT or OUT parameter is in the set, false otherwise.
178: */
179: public boolean checkNoDeclaredOutputParameters();
180:
181: /**
182: * Set the parameter values of the pvstarget to equal those
183: * set in this PVS.
184: * Used to transfer saved SPS parameters to the actual
185: * prepared statement parameters once associated parameters
186: * have been established. Assumes pvstarget is the same
187: * length as this.
188: * @param pvstarget ParameterValueSet which will recieve the values
189:
190: @exception StandardException values not compatible
191: **/
192: public void transferDataValues(ParameterValueSet pvstarget)
193: throws StandardException;
194:
195: /**
196: Return the mode of the parameter according to JDBC 3.0 ParameterMetaData
197:
198: *
199: * @param parameterIndex the first parameter is 1, the second is 2, ...
200: *
201: */
202: public short getParameterMode(int parameterIndex);
203:
204: /**
205: * Get the value of the return parameter in order to set it.
206: *
207: *
208: * @exception StandardException if a database-access error occurs.
209: */
210: DataValueDescriptor getReturnValueForSet() throws StandardException;
211:
212: /**
213: * Return the scale of the given parameter index in this pvs.
214: *
215: * @param parameterIndex the first parameter is 1, the second is 2, ...
216: *
217: * @return scale
218: */
219: public int getScale(int parameterIndex);
220:
221: /**
222: * Return the precision of the given parameter index in this pvs.
223: *
224: * @param parameterIndex the first parameter is 1, the second is 2, ...
225: *
226: * @return precision
227: */
228: public int getPrecision(int parameterIndex);
229:
230: }
|