001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.conn.StatementContext
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.conn;
023:
024: import org.apache.derby.iapi.services.context.Context;
025:
026: import org.apache.derby.iapi.error.StandardException;
027:
028: import org.apache.derby.iapi.sql.execute.NoPutResultSet;
029:
030: import org.apache.derby.iapi.sql.Activation;
031: import org.apache.derby.iapi.sql.PreparedStatement;
032: import org.apache.derby.iapi.sql.ResultSet;
033: import org.apache.derby.iapi.sql.ParameterValueSet;
034:
035: import org.apache.derby.iapi.sql.depend.Dependency;
036:
037: import org.apache.derby.iapi.types.DataValueFactory;
038: import org.apache.derby.iapi.sql.LanguageFactory;
039:
040: /**
041: * StatementContext keeps the context for a statement.
042: */
043: public interface StatementContext extends Context {
044:
045: /**
046: * Mark this context as being in use.
047: *
048: * @param inTrigger true if the parent started in the context of a trigger
049: * @param isAtomic true if the statement must be executed
050: * atomically
051: * @param isForReadOnly true if the statement is for producing non-updatable
052: * resultset
053: * @param stmtText the text of the statement. Needed for any language
054: * statement (currently, for any statement that can cause a trigger
055: * to fire). Please set this unless you are some funky jdbc setXXX
056: * method or something.
057: * @param pvs parameter value set, if it has one
058: * @param timeoutMillis timeout value for the statement, in milliseconds.
059: * Zero means no timeout.
060: */
061: public void setInUse(boolean inTrigger, boolean isAtomic,
062: boolean isForReadOnly, String stmtText,
063: ParameterValueSet pvs, long timeoutMillis);
064:
065: /**
066: * Mark this context as not in use. This is important because we
067: * always leave the top statement context on the stack, and we don't
068: * want to clean it up if a statement level exception happens while the
069: * context is not in use.
070: */
071: public void clearInUse();
072:
073: /**
074: * Set a save point for the current statement.
075: * NOTE: This needs to be off of the StatementContext so that it gets
076: * cleared on a statement error.
077: *
078: * @exception StandardException Thrown on error
079: */
080: public void setSavePoint() throws StandardException;
081:
082: /**
083: * If this statement context has a savepoint, then
084: * it is reset to the current point. Otherwise, it
085: * is a noop.
086: *
087: * @exception StandardException Thrown on error
088: */
089: public void resetSavePoint() throws StandardException;
090:
091: /**
092: * Clear the save point for the current statement.
093: *
094: * @exception StandardException Thrown on error
095: */
096: public void clearSavePoint() throws StandardException;
097:
098: /**
099: * Set the top ResultSet in the ResultSet tree for close down on
100: * an error.
101: *
102: * @param topResultSet The top ResultSet in the ResultSet tree
103: * @param subqueryTrackingArray (Sparse) of tops of subquery ResultSet trees
104: *
105: * @exception StandardException Thrown on error
106: */
107: public void setTopResultSet(ResultSet topResultSet,
108: NoPutResultSet[] subqueryTrackingArray)
109: throws StandardException;
110:
111: /**
112: * Set the appropriate entry in the subquery tracking array for
113: * the specified subquery.
114: * Useful for closing down open subqueries on an exception.
115: *
116: * @param subqueryNumber The subquery # for this subquery
117: * @param subqueryResultSet The NoPutResultSet at the top of the subquery
118: * @param numSubqueries The total # of subqueries in the entire query
119: *
120: * @exception StandardException Thrown on error
121: */
122: public void setSubqueryResultSet(int subqueryNumber,
123: NoPutResultSet subqueryResultSet, int numSubqueries)
124: throws StandardException;
125:
126: /**
127: * Get the subquery tracking array for this query.
128: * (Useful for runtime statistics.)
129: *
130: * @return NoPutResultSet[] The (sparse) array of tops of subquery ResultSet trees
131: * @exception StandardException Thrown on error
132: */
133: public NoPutResultSet[] getSubqueryTrackingArray()
134: throws StandardException;
135:
136: /**
137: * Track a Dependency within this StatementContext.
138: * (We need to clear any dependencies added within this
139: * context on an error.
140: *
141: * @param dy The dependency to track.
142: *
143: * @exception StandardException Thrown on error
144: */
145: public void addDependency(Dependency dy) throws StandardException;
146:
147: /**
148: * Reports whether this StatementContext is on the context stack.
149: *
150: * @return true if this StatementContext is on the context stack. false otherwise.
151: */
152: public boolean onStack();
153:
154: /**
155: * Returns whether we started from within the context of a trigger
156: * or not.
157: *
158: * @return true if we are in a trigger context
159: */
160: public boolean inTrigger();
161:
162: /**
163: * Indicates whether the statement needs to be executed atomically
164: * or not, i.e., whether a commit/rollback is permitted by a
165: * connection nested in this statement.
166: *
167: * @return true if needs to be atomic
168: */
169: public boolean isAtomic();
170:
171: /**
172: * Is this statement context in use or not.
173: *
174: * @return true if in use
175: */
176: public boolean inUse();
177:
178: /**
179: * Is this statement for a read only, non-updatable ResultSet
180: * @return true if the statement is for creating a
181: * read only, non-updatable ResultSet
182: */
183: public boolean isForReadOnly();
184:
185: /**
186: * Checks if the statement which has allocated this statement context
187: * should cancel its execution.
188: *
189: * @return true if the statement execution should be cancelled.
190: **/
191: public boolean isCancelled();
192:
193: /**
194: * Indicate that the statement which has allocated this statement
195: * context should cancel its execution.
196: * Usually called as a consequence of Statement.cancel() or a query timeout
197: * set with Statement.setQueryTimeout().
198: */
199: public void cancel();
200:
201: /**
202: * Return the text of the current statement.
203: * Note that this may be null. It is currently
204: * not set up correctly for ResultSets that aren't
205: * single row result sets (e.g SELECT)
206: * and setXXXX/getXXXX jdbc methods.
207: *
208: * @return the statement text
209: */
210: public String getStatementText();
211:
212: /**
213: Set the level of SQL allowed in this and subsequent
214: nested statements due to a routine call. Value must be one of
215: RoutineAliasInfo.{MODIFIES_SQL_DATA, READS_SQL_DATA, CONTAINS_SQL, NO_SQL}
216:
217: @param force set to true to override more restrictive setting. Used to
218: reset the permissions after a function call.
219:
220: */
221: public void setSQLAllowed(short allow, boolean force);
222:
223: /**
224: Get the setting of the SQL allowed state.
225: */
226: public short getSQLAllowed();
227:
228: /**
229: Set to indicate statement is system code.
230: For example a system procedure, view, function etc.
231: */
232: public void setSystemCode();
233:
234: /**
235: Return true if this statement is system code.
236: */
237: public boolean getSystemCode();
238:
239: /**
240: Indicate that, in the event of a statement-level exception,
241: this context is NOT the last one that needs to be rolled
242: back--rather, it is nested within some other statement
243: context, and that other context needs to be rolled back,
244: too.
245: */
246: public void setParentRollback();
247:
248: }
|