001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.PreparedStatement
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.sql.conn.LanguageConnectionContext;
027:
028: import org.apache.derby.iapi.sql.depend.Dependent;
029: import org.apache.derby.iapi.sql.depend.Provider;
030:
031: import org.apache.derby.iapi.types.DataTypeDescriptor;
032: import java.sql.Timestamp;
033: import java.sql.SQLWarning;
034:
035: /**
036: * The PreparedStatement interface provides methods to execute prepared
037: * statements, store them, and get metadata about them.
038: *
039: * @author Jeff Lichtman
040: */
041: public interface PreparedStatement extends Dependent, Provider {
042:
043: /**
044: * Checks whether this PreparedStatement is up to date.
045: * A PreparedStatement can become out of date if any of several
046: * things happen:
047: *
048: * A schema used by the statement is dropped
049: * A table used by the statement is dropped
050: * A table used by the statement, or a column in such a table,
051: * is altered in one of several ways: a column is dropped,
052: * a privilege is dropped, a constraint is added or
053: * dropped, an index is dropped.
054: * A view used by the statement is dropped.
055: *
056: * In general, anything that happened since the plan was generated
057: * that might cause the plan to fail, or to generate incorrect results,
058: * will cause this method to return FALSE.
059: *
060: * @return TRUE if the PreparedStatement is up to date,
061: * FALSE if it is not up to date
062: */
063: boolean upToDate() throws StandardException;
064:
065: /**
066: * Re-prepare the statement if it is not up to date or,
067: * if requested, simply not optimal.
068: * If there are open cursors using this prepared statement,
069: * then we will not be able to recompile the statement.
070: *
071: * @param lcc The LanguageConnectionContext.
072: *
073: * @exception StandardException thrown if unable to perform
074: */
075: void rePrepare(LanguageConnectionContext lcc)
076: throws StandardException;
077:
078: /**
079: * PreparedStatements are re-entrant - that is, more than one
080: * execution can be active at a time for a single prepared statement.
081: * An Activation contains all the local state information to
082: * execute a prepared statement (as opposed to the constant
083: * information, such as literal values and code). Each Activation
084: * class contains the code specific to the prepared statement
085: * represented by an instance of this class (PreparedStatement).
086: *
087: * @param lcc The LanguageConnectionContext.
088: * @return The new activation.
089: *
090: * @exception StandardException Thrown on failure
091: */
092: Activation getActivation(LanguageConnectionContext lcc,
093: boolean scrollable) throws StandardException;
094:
095: /**
096: * Execute the PreparedStatement and return results.
097: *<p>
098: * There is no executeQuery() or
099: * executeUpdate(); a method is provided in
100: * ResultSet to tell whether to expect rows to be returned.
101: *
102: * @param activation The activation containing all the local state
103: * to execute the plan.
104: * @param rollbackParentContext True if 1) the statement context is
105: * NOT a top-level context, AND 2) in the event of a statement-level
106: * exception, the parent context needs to be rolled back, too.
107: * @param timeoutMillis timeout value in milliseconds.
108: *
109: * @return A ResultSet for a statement. A ResultSet represents
110: * the results returned from the statement, if any.
111: * Will return NULL if the plan for the PreparedStatement
112: * has aged out of cache, or the plan is out of date.
113: *
114: * @exception StandardException Thrown on failure
115: */
116: ResultSet execute(Activation activation,
117: boolean rollbackParentContext, long timeoutMillis)
118: throws StandardException;
119:
120: /**
121: Simple form of execute(). Creates a new single use activation and executes it,
122: but also passes rollbackParentContext parameter (see above).
123: */
124: ResultSet execute(LanguageConnectionContext lcc,
125: boolean rollbackParentContext, long timeoutMillis)
126: throws StandardException;
127:
128: /**
129: * Get the ResultDescription for the statement. The ResultDescription
130: * describes what the results look like: what are the rows and columns?
131: * <p>
132: * This is available here and on the ResultSet so that users can
133: * see the shape of the result before they execute.
134: *
135: * @return A ResultDescription describing the results.
136: *
137: */
138: ResultDescription getResultDescription();
139:
140: /**
141: * Return true if the query node for this statement references SESSION schema tables.
142: *
143: * @return true if references SESSION schema tables, else false
144: */
145: boolean referencesSessionSchema();
146:
147: /**
148: * Get an array of DataTypeDescriptors describing the types of the
149: * parameters of this PreparedStatement. The Nth element of the array
150: * describes the Nth parameter.
151: *
152: * @return An array of DataTypeDescriptors telling the
153: * type, length, precision, scale, etc. of each
154: * parameter of this PreparedStatement.
155: */
156: DataTypeDescriptor[] getParameterTypes();
157:
158: /**
159: * Return the SQL string that this statement is for.
160: *
161: * @return the SQL string this statement is for.
162: */
163: String getSource();
164:
165: /**
166: * Return the SPS Name for this statement.
167: *
168: * @return the SPS Name for this statement
169: */
170: String getSPSName();
171:
172: /**
173: * Get the total compile time for the associated query in milliseconds.
174: * Compile time can be divided into parse, bind, optimize and generate times.
175: *
176: * @return long The total compile time for the associated query in milliseconds.
177: */
178: public long getCompileTimeInMillis();
179:
180: /**
181: * Get the parse time for the associated query in milliseconds.
182: *
183: * @return long The parse time for the associated query in milliseconds.
184: */
185: public long getParseTimeInMillis();
186:
187: /**
188: * Get the bind time for the associated query in milliseconds.
189: *
190: * @return long The bind time for the associated query in milliseconds.
191: */
192: public long getBindTimeInMillis();
193:
194: /**
195: * Get the optimize time for the associated query in milliseconds.
196: *
197: * @return long The optimize time for the associated query in milliseconds.
198: */
199: public long getOptimizeTimeInMillis();
200:
201: /**
202: * Get the generate time for the associated query in milliseconds.
203: *
204: * @return long The generate time for the associated query in milliseconds.
205: */
206: public long getGenerateTimeInMillis();
207:
208: /**
209: * Get the timestamp for the beginning of compilation
210: *
211: * @return Timestamp The timestamp for the beginning of compilation.
212: */
213: public Timestamp getBeginCompileTimestamp();
214:
215: /**
216: * Get the timestamp for the end of compilation
217: *
218: * @return Timestamp The timestamp for the end of compilation.
219: */
220: public Timestamp getEndCompileTimestamp();
221:
222: /**
223: * Returns whether or not this Statement requires should
224: * behave atomically -- i.e. whether a user is permitted
225: * to do a commit/rollback during the execution of this
226: * statement.
227: *
228: * @return boolean Whether or not this Statement is atomic
229: */
230: boolean isAtomic();
231:
232: /**
233: Return any compile time warnings. Null if no warnings exist.
234: */
235: public SQLWarning getCompileTimeWarnings();
236:
237: }
|