KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > sql > ParameterValueSet


1 /*
2
3    Derby - Class org.apache.derby.iapi.sql.ParameterValueSet
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.sql;
23
24 import org.apache.derby.iapi.error.StandardException;
25
26 import org.apache.derby.iapi.types.DataTypeDescriptor;
27 import org.apache.derby.iapi.types.DataValueDescriptor;
28
29 /**
30  * A ParameterValueSet is a set of parameter values that can be assembled by a
31  * JDBC driver and passed to a PreparedStatement all at once. The fact that
32  * they are all passed at once can reduce the communication overhead between
33  * client and server.
34  *
35  * @author Jeff Lichtman
36  */
37 public interface ParameterValueSet
38 {
39     /**
40      * Initialize the parameter set by allocating DataValueDescriptor
41      * corresponding to the passed in type for each parameter.
42      * @param types expected to match the number of parameters.
43      */
44     void initialize(DataTypeDescriptor[] types);
45
46
47     /**
48         Set the mode of the parameter, called when setting up static method calls and stored procedures.
49         Otherwise the parameter type will default to an IN parameter.
50     */
51     void setParameterMode(int position, int mode);
52
53     //////////////////////////////////////////////////////////////////
54 //
55 // CALLABLE STATEMENT
56 //
57 //////////////////////////////////////////////////////////////////
58
59     /**
60      * Mark the parameter as an output parameter.
61      *
62      * @param parameterIndex The ordinal position of a parameter to set
63      * to the given value.
64      * @param sqlType A type from java.sql.Types
65      * @param scale the scale to use. -1 means ignore scale
66      *
67      * @exception StandardException on error
68      */
69     void registerOutParameter(int parameterIndex, int sqlType, int scale)
70         throws StandardException;
71
72     //////////////////////////////////////////////////////////////////
73 //
74 // MISC STATEMENT
75 //
76 //////////////////////////////////////////////////////////////////
77
78     /**
79      * Sets all parameters to an uninitialized state. An exception will be
80      * thrown if the caller tries to execute a PreparedStatement when one
81      * or more parameters is uninitialized (i.e. has not had
82      * setParameterValue() called on it.
83      */
84     void clearParameters();
85
86     /**
87      * Returns the number of parameters in this set.
88      *
89      * @return The number of parameters in this set.
90      */
91     public int getParameterCount();
92
93     /**
94      * Returns the parameter at the given position.
95      *
96      * @return The parameter at the given position.
97      * @exception StandardException Thrown on error
98      */
99     public DataValueDescriptor getParameter( int position ) throws StandardException;
100
101
102     /**
103      * Returns the parameter at the given position in order to set it.
104        Setting via an unknown object type must use setParameterAsObject()
105        to ensure correct typing.
106
107      *
108      * @return The parameter at the given position.
109      * @exception StandardException Thrown on error
110      */
111     public DataValueDescriptor getParameterForSet( int position ) throws StandardException;
112
113     /**
114         Set the value of this user defined parameter to the passed in Object.
115         
116           @exception StandardException Thrown on error
117     */
118     void setParameterAsObject(int parameterIndex, Object JavaDoc value) 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 ) throws StandardException;
127
128     /**
129      * Tells whether all the parameters are set and ready for execution.
130        OUT are not required to be set.
131      *
132      * @return true if all parameters are set, false if at least one
133      * parameter is not set.
134      */
135     boolean allAreSet();
136
137     /**
138      * Clone the ParameterValueSet and its contents.
139      *
140      * @return ParameterValueSet A clone of the ParameterValueSet and its contents.
141      */
142     ParameterValueSet getClone();
143
144     /**
145      * Validate the parameters. This is done for situations where
146      * we cannot validate everything in the setXXX() calls. In
147      * particular, before we do an execute() on a CallableStatement,
148      * we need to go through the parameters and make sure that
149      * all parameters are set up properly. The motivator for this
150      * is that setXXX() can be called either before or after
151      * registerOutputParamter(), we cannot be sure we have the types
152      * correct until we get to execute().
153      *
154      * @exception StandardException if the parameters aren't valid
155      */
156     void validate() throws StandardException;
157
158     /**
159      * Is there a return output parameter in this pvs. A return
160      * parameter is from a CALL statement of the following
161      * syntax: ? = CALL myMethod(). Note that a return
162      * output parameter is NOT the same thing as an output
163      * parameter; it is a special type of output parameter.
164      *
165      * @return true if it has a return parameter
166      *
167      */
168     public boolean hasReturnOutputParameter();
169
170     /**
171         Check that there are not output parameters defined
172         by the parameter set. If there are unknown parameter
173         types they are forced to input types. i.e. Cloudscape static method
174         calls with parameters that are array.
175
176         @return true if a declared Java Procedure INOUT or OUT parameter is in the set, false otherwise.
177     */
178     public boolean checkNoDeclaredOutputParameters();
179
180     /**
181      * Set the parameter values of the pvstarget to equal those
182      * set in this PVS.
183      * Used to transfer saved SPS parameters to the actual
184      * prepared statement parameters once associated parameters
185      * have been established. Assumes pvstarget is the same
186      * length as this.
187      * @param pvstarget ParameterValueSet which will recieve the values
188
189         @exception StandardException values not compatible
190      **/
191     public void transferDataValues(ParameterValueSet pvstarget) throws StandardException;
192
193     /**
194         Return the mode of the parameter according to JDBC 3.0 ParameterMetaData
195         
196      *
197      * @param parameterIndex the first parameter is 1, the second is 2, ...
198      *
199      */
200     public short getParameterMode(int parameterIndex);
201
202
203     /**
204      * Get the value of the return parameter in order to set it.
205      *
206      *
207      * @exception StandardException if a database-access error occurs.
208      */
209     DataValueDescriptor getReturnValueForSet() throws StandardException;
210
211     /**
212      * Return the scale of the given parameter index in this pvs.
213      *
214      * @param parameterIndex the first parameter is 1, the second is 2, ...
215      *
216      * @return scale
217      */
218     public int getScale(int parameterIndex);
219
220     /**
221      * Return the precision of the given parameter index in this pvs.
222      *
223      * @param parameterIndex the first parameter is 1, the second is 2, ...
224      *
225      * @return precision
226      */
227     public int getPrecision(int parameterIndex);
228
229
230 }
231
232
Popular Tags