KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2
3    Derby - Class org.apache.derby.iapi.sql.PreparedStatement
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.sql.conn.LanguageConnectionContext;
27
28 import org.apache.derby.iapi.sql.depend.Dependent;
29 import org.apache.derby.iapi.sql.depend.Provider;
30
31 import org.apache.derby.iapi.types.DataTypeDescriptor;
32 import java.sql.Timestamp JavaDoc;
33 import java.sql.SQLWarning JavaDoc;
34
35 /**
36  * The PreparedStatement interface provides methods to execute prepared
37  * statements, store them, and get metadata about them.
38  *
39  * @author Jeff Lichtman
40  */
41 public interface PreparedStatement
42     extends Dependent, Provider
43 {
44
45     /**
46      * Checks whether this PreparedStatement is up to date.
47      * A PreparedStatement can become out of date if any of several
48      * things happen:
49      *
50      * A schema used by the statement is dropped
51      * A table used by the statement is dropped
52      * A table used by the statement, or a column in such a table,
53      * is altered in one of several ways: a column is dropped,
54      * a privilege is dropped, a constraint is added or
55      * dropped, an index is dropped.
56      * A view used by the statement is dropped.
57      *
58      * In general, anything that happened since the plan was generated
59      * that might cause the plan to fail, or to generate incorrect results,
60      * will cause this method to return FALSE.
61      *
62      * @return TRUE if the PreparedStatement is up to date,
63      * FALSE if it is not up to date
64      */
65     boolean upToDate() throws StandardException;
66
67     /**
68      * Re-prepare the statement if it is not up to date or,
69      * if requested, simply not optimal.
70      * If there are open cursors using this prepared statement,
71      * then we will not be able to recompile the statement.
72      *
73      * @param lcc The LanguageConnectionContext.
74      *
75      * @exception StandardException thrown if unable to perform
76      */
77     void rePrepare(LanguageConnectionContext lcc)
78         throws StandardException;
79
80     /**
81      * PreparedStatements are re-entrant - that is, more than one
82      * execution can be active at a time for a single prepared statement.
83      * An Activation contains all the local state information to
84      * execute a prepared statement (as opposed to the constant
85      * information, such as literal values and code). Each Activation
86      * class contains the code specific to the prepared statement
87      * represented by an instance of this class (PreparedStatement).
88      *
89      * @param lcc The LanguageConnectionContext.
90      * @return The new activation.
91      *
92      * @exception StandardException Thrown on failure
93      */
94     Activation getActivation(LanguageConnectionContext lcc, boolean scrollable) throws StandardException;
95
96     /**
97      * Execute the PreparedStatement and return results.
98      *<p>
99      * There is no executeQuery() or
100      * executeUpdate(); a method is provided in
101      * ResultSet to tell whether to expect rows to be returned.
102      *
103      * @param activation The activation containing all the local state
104      * to execute the plan.
105      * @param rollbackParentContext True if 1) the statement context is
106      * NOT a top-level context, AND 2) in the event of a statement-level
107      * exception, the parent context needs to be rolled back, too.
108      * @param timeoutMillis timeout value in milliseconds.
109      *
110      * @return A ResultSet for a statement. A ResultSet represents
111      * the results returned from the statement, if any.
112      * Will return NULL if the plan for the PreparedStatement
113      * has aged out of cache, or the plan is out of date.
114      *
115      * @exception StandardException Thrown on failure
116      */
117     ResultSet execute(Activation activation,
118                       boolean rollbackParentContext,
119                       long timeoutMillis)
120         throws StandardException;
121
122     /**
123         Simple form of execute(). Creates a new single use activation and executes it,
124         but also passes rollbackParentContext parameter (see above).
125     */
126     ResultSet execute(LanguageConnectionContext lcc,
127                       boolean rollbackParentContext,
128                       long timeoutMillis)
129         throws StandardException;
130
131     /**
132      * Get the ResultDescription for the statement. The ResultDescription
133      * describes what the results look like: what are the rows and columns?
134      * <p>
135      * This is available here and on the ResultSet so that users can
136      * see the shape of the result before they execute.
137      *
138      * @return A ResultDescription describing the results.
139      *
140      */
141     ResultDescription getResultDescription();
142
143     /**
144      * Return true if the query node for this statement references SESSION schema tables.
145      *
146      * @return true if references SESSION schema tables, else false
147      */
148     boolean referencesSessionSchema();
149
150     /**
151      * Get an array of DataTypeDescriptors describing the types of the
152      * parameters of this PreparedStatement. The Nth element of the array
153      * describes the Nth parameter.
154      *
155      * @return An array of DataTypeDescriptors telling the
156      * type, length, precision, scale, etc. of each
157      * parameter of this PreparedStatement.
158      */
159     DataTypeDescriptor[] getParameterTypes();
160
161     /**
162      * Return the SQL string that this statement is for.
163      *
164      * @return the SQL string this statement is for.
165      */
166     String JavaDoc getSource();
167
168     /**
169      * Return the SPS Name for this statement.
170      *
171      * @return the SPS Name for this statement
172      */
173     String JavaDoc getSPSName();
174
175     /**
176      * Get the total compile time for the associated query in milliseconds.
177      * Compile time can be divided into parse, bind, optimize and generate times.
178      *
179      * @return long The total compile time for the associated query in milliseconds.
180      */
181     public long getCompileTimeInMillis();
182
183     /**
184      * Get the parse time for the associated query in milliseconds.
185      *
186      * @return long The parse time for the associated query in milliseconds.
187      */
188     public long getParseTimeInMillis();
189
190     /**
191      * Get the bind time for the associated query in milliseconds.
192      *
193      * @return long The bind time for the associated query in milliseconds.
194      */
195     public long getBindTimeInMillis();
196
197     /**
198      * Get the optimize time for the associated query in milliseconds.
199      *
200      * @return long The optimize time for the associated query in milliseconds.
201      */
202     public long getOptimizeTimeInMillis();
203
204     /**
205      * Get the generate time for the associated query in milliseconds.
206      *
207      * @return long The generate time for the associated query in milliseconds.
208      */
209     public long getGenerateTimeInMillis();
210
211     /**
212      * Get the timestamp for the beginning of compilation
213      *
214      * @return Timestamp The timestamp for the beginning of compilation.
215      */
216     public Timestamp JavaDoc getBeginCompileTimestamp();
217
218     /**
219      * Get the timestamp for the end of compilation
220      *
221      * @return Timestamp The timestamp for the end of compilation.
222      */
223     public Timestamp JavaDoc getEndCompileTimestamp();
224
225     /**
226      * Returns whether or not this Statement requires should
227      * behave atomically -- i.e. whether a user is permitted
228      * to do a commit/rollback during the execution of this
229      * statement.
230      *
231      * @return boolean Whether or not this Statement is atomic
232      */
233     boolean isAtomic();
234
235     /**
236         Return any compile time warnings. Null if no warnings exist.
237     */
238     public SQLWarning JavaDoc getCompileTimeWarnings();
239
240 }
241
Popular Tags