--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.sql.PreparedStatement\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.sql;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import org.apache.derby.iapi.sql.conn.LanguageConnectionContext;\r
+\r
+import org.apache.derby.iapi.sql.depend.Dependent;\r
+import org.apache.derby.iapi.sql.depend.Provider;\r
+\r
+import org.apache.derby.iapi.types.DataTypeDescriptor;\r
+import java.sql.Timestamp;\r
+import java.sql.SQLWarning;\r
+\r
+/**\r
+ * The PreparedStatement interface provides methods to execute prepared\r
+ * statements, store them, and get metadata about them.\r
+ *\r
+ */\r
+public interface PreparedStatement\r
+ extends Dependent\r
+{\r
+\r
+ /**\r
+ * Checks whether this PreparedStatement is up to date.\r
+ * A PreparedStatement can become out of date if any of several\r
+ * things happen:\r
+ *\r
+ * A schema used by the statement is dropped\r
+ * A table used by the statement is dropped\r
+ * A table used by the statement, or a column in such a table,\r
+ * is altered in one of several ways: a column is dropped,\r
+ * a privilege is dropped, a constraint is added or\r
+ * dropped, an index is dropped.\r
+ * A view used by the statement is dropped.\r
+ *\r
+ * In general, anything that happened since the plan was generated\r
+ * that might cause the plan to fail, or to generate incorrect results,\r
+ * will cause this method to return FALSE.\r
+ *\r
+ * @return TRUE if the PreparedStatement is up to date,\r
+ * FALSE if it is not up to date\r
+ */\r
+ boolean upToDate() throws StandardException;\r
+\r
+ /**\r
+ * Re-prepare the statement if it is not up to date or,\r
+ * if requested, simply not optimal.\r
+ * If there are open cursors using this prepared statement,\r
+ * then we will not be able to recompile the statement.\r
+ *\r
+ * @param lcc The LanguageConnectionContext.\r
+ *\r
+ * @exception StandardException thrown if unable to perform\r
+ */\r
+ void rePrepare(LanguageConnectionContext lcc) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * PreparedStatements are re-entrant - that is, more than one\r
+ * execution can be active at a time for a single prepared statement.\r
+ * An Activation contains all the local state information to\r
+ * execute a prepared statement (as opposed to the constant\r
+ * information, such as literal values and code). Each Activation\r
+ * class contains the code specific to the prepared statement\r
+ * represented by an instance of this class (PreparedStatement).\r
+ *\r
+ * @param lcc The LanguageConnectionContext.\r
+ * @return The new activation.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ */\r
+ Activation getActivation(LanguageConnectionContext lcc, boolean scrollable) throws StandardException;\r
+\r
+ /**\r
+ * Execute the PreparedStatement and return results.\r
+ *<p>\r
+ * There is no executeQuery() or\r
+ * executeUpdate(); a method is provided in\r
+ * ResultSet to tell whether to expect rows to be returned.\r
+ *\r
+ * @param activation The activation containing all the local state\r
+ * to execute the plan.\r
+ * @param rollbackParentContext True if 1) the statement context is\r
+ * NOT a top-level context, AND 2) in the event of a statement-level\r
+ * exception, the parent context needs to be rolled back, too.\r
+ * @param timeoutMillis timeout value in milliseconds.\r
+ *\r
+ * @return A ResultSet for a statement. A ResultSet represents\r
+ * the results returned from the statement, if any.\r
+ * Will return NULL if the plan for the PreparedStatement\r
+ * has aged out of cache, or the plan is out of date.\r
+ *\r
+ * @exception StandardException Thrown on failure\r
+ */\r
+ ResultSet execute(Activation activation,\r
+ boolean rollbackParentContext,\r
+ long timeoutMillis)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Simple form of execute(). Creates a new single use activation and executes it,\r
+ but also passes rollbackParentContext parameter (see above).\r
+ */\r
+ ResultSet execute(LanguageConnectionContext lcc,\r
+ boolean rollbackParentContext,\r
+ long timeoutMillis)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Get the ResultDescription for the statement. The ResultDescription\r
+ * describes what the results look like: what are the rows and columns?\r
+ * <p>\r
+ * This is available here and on the ResultSet so that users can\r
+ * see the shape of the result before they execute.\r
+ *\r
+ * @return A ResultDescription describing the results.\r
+ *\r
+ */\r
+ ResultDescription getResultDescription();\r
+\r
+ /**\r
+ * Return true if the query node for this statement references SESSION schema tables.\r
+ *\r
+ * @return true if references SESSION schema tables, else false\r
+ */\r
+ boolean referencesSessionSchema();\r
+\r
+ /**\r
+ * Get an array of DataTypeDescriptors describing the types of the\r
+ * parameters of this PreparedStatement. The Nth element of the array\r
+ * describes the Nth parameter.\r
+ *\r
+ * @return An array of DataTypeDescriptors telling the\r
+ * type, length, precision, scale, etc. of each\r
+ * parameter of this PreparedStatement.\r
+ */\r
+ DataTypeDescriptor[] getParameterTypes();\r
+\r
+ /**\r
+ * Return the SQL string that this statement is for.\r
+ *\r
+ * @return the SQL string this statement is for.\r
+ */\r
+ String getSource();\r
+\r
+ /**\r
+ * Return the SPS Name for this statement.\r
+ *\r
+ * @return the SPS Name for this statement\r
+ */\r
+ String getSPSName();\r
+\r
+ /**\r
+ * Get the total compile time for the associated query in milliseconds.\r
+ * Compile time can be divided into parse, bind, optimize and generate times.\r
+ * \r
+ * @return long The total compile time for the associated query in milliseconds.\r
+ */\r
+ public long getCompileTimeInMillis();\r
+\r
+ /**\r
+ * Get the parse time for the associated query in milliseconds.\r
+ * \r
+ * @return long The parse time for the associated query in milliseconds.\r
+ */\r
+ public long getParseTimeInMillis();\r
+\r
+ /**\r
+ * Get the bind time for the associated query in milliseconds.\r
+ * \r
+ * @return long The bind time for the associated query in milliseconds.\r
+ */\r
+ public long getBindTimeInMillis();\r
+\r
+ /**\r
+ * Get the optimize time for the associated query in milliseconds.\r
+ * \r
+ * @return long The optimize time for the associated query in milliseconds.\r
+ */\r
+ public long getOptimizeTimeInMillis();\r
+\r
+ /**\r
+ * Get the generate time for the associated query in milliseconds.\r
+ * \r
+ * @return long The generate time for the associated query in milliseconds.\r
+ */\r
+ public long getGenerateTimeInMillis();\r
+\r
+ /**\r
+ * Get the timestamp for the beginning of compilation\r
+ *\r
+ * @return Timestamp The timestamp for the beginning of compilation.\r
+ */\r
+ public Timestamp getBeginCompileTimestamp();\r
+\r
+ /**\r
+ * Get the timestamp for the end of compilation\r
+ *\r
+ * @return Timestamp The timestamp for the end of compilation.\r
+ */\r
+ public Timestamp getEndCompileTimestamp();\r
+\r
+ /**\r
+ * Returns whether or not this Statement requires should\r
+ * behave atomically -- i.e. whether a user is permitted\r
+ * to do a commit/rollback during the execution of this\r
+ * statement.\r
+ *\r
+ * @return boolean Whether or not this Statement is atomic\r
+ */\r
+ boolean isAtomic();\r
+\r
+ /**\r
+ Return any compile time warnings. Null if no warnings exist.\r
+ */\r
+ public SQLWarning getCompileTimeWarnings();\r
+\r
+}\r