001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.Activation
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.dictionary.IndexRowGenerator;
029: import org.apache.derby.iapi.sql.dictionary.TableDescriptor;
030:
031: import org.apache.derby.iapi.sql.execute.ExecPreparedStatement;
032: import org.apache.derby.iapi.sql.execute.ExecRow;
033: import org.apache.derby.iapi.sql.execute.ExecutionFactory;
034: import org.apache.derby.iapi.sql.execute.NoPutResultSet;
035: import org.apache.derby.iapi.sql.execute.ConstantAction;
036: import org.apache.derby.iapi.sql.execute.CursorResultSet;
037: import org.apache.derby.iapi.sql.execute.TemporaryRowHolder;
038:
039: import org.apache.derby.iapi.store.access.ConglomerateController;
040: import org.apache.derby.iapi.store.access.ScanController;
041: import org.apache.derby.iapi.store.access.TransactionController;
042:
043: import org.apache.derby.iapi.types.DataValueFactory;
044:
045: import org.apache.derby.iapi.types.RowLocation;
046: import org.apache.derby.iapi.types.DataTypeDescriptor;
047:
048: import java.sql.SQLWarning;
049: import java.util.Enumeration;
050: import java.util.Vector;
051: import java.util.Hashtable;
052:
053: /**
054: * An activation contains all the local state information necessary
055: * to execute a re-entrant PreparedStatement. The way it will actually work
056: * is that a PreparedStatement will have an executable plan, which will be
057: * a generated class. All of the local state will be variables in the class.
058: * Creating a new instance of the executable plan will create the local state
059: * variables. This means that an executable plan must implement this interface,
060: * and that the PreparedStatement.getActivation() method will do a
061: * "new" operation on the executable plan.
062: * <p>
063: * The fixed implementations of Activation in the Execution impl
064: * package are used as skeletons for the classes generated for statements
065: * when they are compiled.
066: * <p>
067: * There are no fixed implementations of Activation for statements;
068: * a statement has an activation generated for it when it is compiled.
069: *
070: * @author Jeff Lichtman
071: */
072:
073: public interface Activation {
074: /**
075: * Resets the activation to the "pre-execution" state -
076: * that is, the state where it can be used to begin a new execution.
077: * Frees local buffers, stops scans, resets counters to zero, sets
078: * current date and time to an unitialized state, etc.
079: *
080: * @exception StandardException thrown on failure
081: */
082: void reset() throws StandardException;
083:
084: /**
085: * JDBC requires that all select statements be converted into cursors,
086: * and that the cursor name be settable for each execution of a select
087: * statement. The Language Module will support this, so that the JDBC
088: * driver will not have to parse JSQL text. This method will have no
089: * effect when called on non-select statements.
090: * <p>
091: * There will be a JSQL statement to disable the "cursorization" of
092: * all select statements. For non-cursorized select statements, this
093: * method will have no effect.
094: * <p>
095: * This has no effect if the activation has been closed.
096: * <p>
097: * @param cursorName The cursor name to use.
098: */
099: void setCursorName(String cursorName);
100:
101: /**
102: * Temporary tables can be declared with ON COMMIT DELETE ROWS. But if the table has a held curosr open at
103: * commit time, data should not be deleted from the table. This method, (gets called at commit time) checks if this
104: * activation held cursor and if so, does that cursor reference the passed temp table name.
105: *
106: * @return true if this activation has held cursor and if it references the passed temp table name
107: */
108: public boolean checkIfThisActivationHasHoldCursor(String tableName);
109:
110: /**
111: * Gets the ParameterValueSet for this execution of the statement.
112: *
113: * @return The ParameterValueSet for this execution of the
114: * statement. Returns NULL if there are no parameters.
115: */
116: ParameterValueSet getParameterValueSet();
117:
118: /**
119: * Sets the parameter values for this execution of the statement.
120: * <p>
121: * Has no effect if the activation has been closed.
122: *
123: * <p>
124: * NOTE: The setParameters() method is currently unimplemented.
125: * A statement with parameters will generate its own ParameterValueSet,
126: * which can be gotten with the getParameterValueSet() method (above).
127: * The idea behind setParameters() is to improve performance when
128: * operating across a network by allowing all the parameters to be set
129: * in one call, as opposed to one call per parameter.
130: *
131: * @param parameterValues The values of the parameters.
132: */
133: void setParameters(ParameterValueSet parameterValues,
134: DataTypeDescriptor[] parameterTypes)
135: throws StandardException;
136:
137: /**
138: * When the prepared statement is executed, it passes
139: * execution on to the activation execution was requested for.
140: *
141: * @return the ResultSet for further manipulation, if any.
142: *
143: * @exception StandardException Thrown on failure
144: */
145: ResultSet execute() throws StandardException;
146:
147: /**
148: Closing an activation statement marks it as unusable. Any other
149: requests made on it will fail. An activation should be
150: marked closed when it is expected to not be used any longer,
151: i.e. when the connection for it is closed, or it has suffered some
152: sort of severe error. This will also close its result set and
153: release any resources it holds e.g. for parameters.
154: <P>
155: Any class that implements this must be prepared to be executed
156: from garbage collection, ie. there is no matching context stack.
157:
158: @exception StandardException Thrown on failure
159: */
160: void close() throws StandardException;
161:
162: /**
163: Find out if the activation is closed or not.
164:
165: @return true if the Activation has been closed.
166: */
167: boolean isClosed();
168:
169: /**
170: Set this Activation for a single execution.
171: E.g. a java.sql.Statement execution.
172: */
173: void setSingleExecution();
174:
175: /**
176: Returns true if this Activation is only going to be used for
177: one execution.
178: */
179: boolean isSingleExecution();
180:
181: /**
182: Returns the chained list of warnings. Returns null
183: if there are no warnings.
184: */
185: SQLWarning getWarnings();
186:
187: /**
188: Add a warning to the activation
189: */
190: void addWarning(SQLWarning w);
191:
192: /**
193: Clear the activation's warnings.
194: */
195: void clearWarnings();
196:
197: /**
198: * Get the language connection context associated with this activation
199: */
200: public LanguageConnectionContext getLanguageConnectionContext();
201:
202: /**
203: * Get the Execution TransactionController associated with this
204: * activation/lcc.
205: */
206: TransactionController getTransactionController();
207:
208: /**
209: * Returns the current result set for this activation, i.e.
210: * the one returned by the last execute() call. If there has
211: * been no execute call or the activation has been reset or closed,
212: * a null is returned.
213: *
214: * @return the current ResultSet of this activation.
215: */
216: ResultSet getResultSet();
217:
218: /**
219: * Sets the ResultSet to be returned by getResultSet() to null.
220: */
221: void clearResultSet();
222:
223: /**
224: * Generated plans have a current row field for ease in defining
225: * the methods and finding them dynamically. The interface is
226: * used to set the row before a dynamic method that uses it is
227: * invoked.
228: * <p>
229: * When all processing on the currentRow has been completed,
230: * callers should call activation.clearCurrentRow(resultSetNumber)
231: * to ensure that no unnecessary references are retained to rows.
232: * This will allow the rows no longer in use to be collected by
233: * the garbage collecter.
234: *
235: * @param currentRow The row to be operated upon.
236: * @param resultSetNumber The resultSetNumber for the current ResultSet
237: */
238: void setCurrentRow(ExecRow currentRow, int resultSetNumber);
239:
240: /**
241: * Generated plans have a current row field for ease in defining
242: * the methods and finding them dynamically. The interface is
243: * used to set the row before a dynamic method that uses it is
244: * invoked.
245: * <p>
246: * When all processing on the currentRow has been completed,
247: * callers should call activation.clearCurrentRow(resultSetNumber)
248: * to ensure that no unnecessary references are retained to rows.
249: * This will allow the rows no longer in use to be collected by
250: * the garbage collecter.
251: *
252: * @param resultSetNumber The resultSetNumber for the current ResultSet
253: */
254: /* RESOLVE - this method belongs on an internal, not external, interface */
255: void clearCurrentRow(int resultSetNumber);
256:
257: /**
258: * Get the prepared statement that this activation is for.
259: *
260: * @return the prepared statement this activation is for.
261: *
262: */
263: ExecPreparedStatement getPreparedStatement();
264:
265: /**
266: Check the validity of the current executing statement. Needs to be
267: called after a statement has obtained the relevant table locks on
268: the
269: */
270: public void checkStatementValidity() throws StandardException;
271:
272: /**
273: * Get the result description for this activation, if it has one.
274: *
275: * @return result description for this activation, if it has one;
276: * otherwise, null.
277: */
278: ResultDescription getResultDescription();
279:
280: /**
281: * Get the DataValueFactory
282: *
283: * @return DataValueFactory
284: */
285: DataValueFactory getDataValueFactory();
286:
287: /**
288: * Get the ExecutionFactory
289: *
290: * @return ExecutionFactory
291: */
292: ExecutionFactory getExecutionFactory();
293:
294: /**
295: Get the saved RowLocation.
296:
297: @param itemNumber The saved item number.
298:
299: @return A RowLocation template for the conglomerate
300: */
301: public RowLocation getRowLocationTemplate(int itemNumber);
302:
303: /**
304: Get the number of subqueries in the entire query.
305: @return int The number of subqueries in the entire query.
306: */
307: public int getNumSubqueries();
308:
309: /**
310: * Return the cursor name of this activation. This will differ
311: * from its ResultSet's cursor name if it has been
312: * altered with setCursorName. Thus this always returns the cursor
313: * name of the next execution of this activation. The cursor name
314: * of the current execution must be obtained from the ResultSet.
315: * or this.getResultSet.getCursorName() [with null checking].
316: * <p>
317: * Statements that do not support cursors will return a null.
318: * <p>
319: * @return The cursor name.
320: */
321: public String getCursorName();
322:
323: /**
324: * Return the holdability of this activation.
325: * <p>
326: * @return The holdability of this activation.
327: */
328: public boolean getResultSetHoldability();
329:
330: /**
331: * Set current resultset holdability.
332: *
333: * @param resultSetHoldability The new resultset holdability.
334: */
335: public void setResultSetHoldability(boolean resultSetHoldability);
336:
337: /**
338: * Set the auto-generated keys resultset mode to true for this activation.
339: *
340: * The specific columns for auto-generated keys resultset can be requested by
341: * passing column positions array
342: *
343: * The specific columns for auto-generated keys resultset can be requested by
344: * passing column names array
345: *
346: * Both the parameters would be null if user didn't request specific keys.
347: * Otherwise, the user could request specific columns by passing column positions
348: * or names array but not both.
349: *
350: * @param columnIndexes Request specific columns in auto-generated keys
351: * resultset by passing column positions. null means no specific columns
352: * requested by position
353: *
354: * @param columnNames Request specific columns in auto-generated keys
355: * resultset by passing column names. null means no specific columns
356: * requested by position
357: */
358: public void setAutoGeneratedKeysResultsetInfo(int[] columnIndexes,
359: String[] columnNames);
360:
361: /**
362: * Returns true if auto-generated keys resultset request was made for this
363: * avtivation.
364: * <p>
365: * @return auto-generated keys resultset mode for this activation.
366: */
367: public boolean getAutoGeneratedKeysResultsetMode();
368:
369: /**
370: * Returns the column positions array of columns requested in auto-generated
371: * keys resultset for this avtivation. Returns null if no specific column
372: * requested by positions
373: * <p>
374: * @return column positions array of columns requested.
375: */
376: public int[] getAutoGeneratedKeysColumnIndexes();
377:
378: /**
379: * Returns the column names array of columns requested in auto-generated
380: * keys resultset for this avtivation. Returns null if no specific column
381: * requested by names
382: * <p>
383: * @return column names array of columns requested.
384: */
385: public String[] getAutoGeneratedKeysColumnNames();
386:
387: /**
388: * Mark the activation as unused.
389: */
390: public void markUnused();
391:
392: /**
393: * Is the activation in use?
394: *
395: * @return true/false
396: */
397: public boolean isInUse();
398:
399: /**
400: * Tell this activation that the given ResultSet was found to have
401: * the given number of rows. This is used during execution to determine
402: * whether a table has grown or shrunk. If a table's size changes
403: * significantly, the activation may invalidate its PreparedStatement
404: * to force recompilation.
405: *
406: * Note that the association of row counts with ResultSets is kept
407: * in the activation class, not in the activation itself. This
408: * means that this method must be synchronized.
409: *
410: * This method is not required to check the number of rows on each
411: * call. Because of synchronization, this check is likely to be
412: * expensive, so it may only check every hundred calls or so.
413: *
414: * @exception StandardException Thrown on error
415: */
416: public void informOfRowCount(NoPutResultSet resultSet, long rowCount)
417: throws StandardException;
418:
419: /**
420: * Get the ConglomerateController, if any, that has already
421: * been opened for the heap when scaning for an update or delete.
422: * (Saves opening the ConglomerateController twice.)
423: *
424: * @return The ConglomerateController, if available, to use for the update.
425: */
426: public ConglomerateController getHeapConglomerateController();
427:
428: /**
429: * Set the ConglomerateController to be used for an update or delete.
430: * (Saves opening the ConglomerateController twice.)
431: *
432: * @param updateHeapCC The ConglomerateController to reuse for the update or delete.
433: */
434: public void setHeapConglomerateController(
435: ConglomerateController updateHeapCC);
436:
437: /**
438: * Clear the ConglomerateController to be used for an update or delete.
439: * (Saves opening the ConglomerateController twice.)
440: */
441: public void clearHeapConglomerateController();
442:
443: /**
444: * Get the ScanController, if any, that has already
445: * been opened for the index when scaning for an update or delete.
446: * (Saves opening the ScanController twice.)
447: *
448: * @return The ScanController, if available, to use for the update.
449: */
450: public ScanController getIndexScanController();
451:
452: /**
453: * Set the ScanController to be used for an update or delete,
454: * when scanning an index that will also be updated
455: * (Saves opening the ScanController twice.)
456: *
457: * @param indexSC The ScanController to reuse for the update or delete.
458: */
459: public void setIndexScanController(ScanController indexSC);
460:
461: /**
462: * Get the conglomerate number of the index, if any, that has already
463: * been opened for scaning for an update or delete.
464: * (Saves opening the ScanController twice.)
465: *
466: * @return The conglomerate number, if available, to use for the update.
467: */
468: public long getIndexConglomerateNumber();
469:
470: /**
471: * Set the conglomerate number of the index to be used for an update or delete,
472: * when scanning an index that will also be updated
473: * (Saves opening the ScanController twice.)
474: *
475: * @param indexConglomerateNumber The conglomerate number of the index to reuse for the update or delete.
476: */
477: public void setIndexConglomerateNumber(long indexConglomerateNumber);
478:
479: /**
480: * Clear the info for the index to be re-used for update/delete.
481: * (ScanController and conglomerate number.)
482: */
483: public void clearIndexScanInfo();
484:
485: /**
486: * Mark the Activation as being for create table.
487: * (NOTE: We can do certain optimizations for
488: * create table that we can't do for other DDL.)
489: */
490: public void setForCreateTable();
491:
492: /**
493: * Get whether or not this activation is for
494: * create table.
495: * (NOTE: We can do certain optimizations for
496: * create table that we can't do for other DDL.)
497: *
498: * @return Whether or not this activation is for
499: * create table.
500: */
501: public boolean getForCreateTable();
502:
503: /**
504: * Save the TableDescriptor for the target of
505: * DDL so that it can be passed between the
506: * various ConstantActions during execution.
507: */
508: public void setDDLTableDescriptor(TableDescriptor td);
509:
510: /**
511: * Get the TableDescriptor for the target of
512: * DDL.
513: *
514: * @return The TableDescriptor for the target of
515: * DDL.
516: */
517: public TableDescriptor getDDLTableDescriptor();
518:
519: /**
520: * Set the maximum # of rows. (# of rows that can
521: * be returned by a ResultSet. 0 means no limit.)
522: *
523: * @param maxRows Maximum # of rows. (0 means no limit.)
524: */
525: public void setMaxRows(int maxRows);
526:
527: /**
528: * Get the maximum # of rows. (# of rows that can
529: * be returned by a ResultSet. 0 means no limit.)
530: *
531: * @return Maximum # of rows. (0 means no limit.)
532: */
533: public int getMaxRows();
534:
535: /**
536: * Is this Activation for a cursor?
537: *
538: * @return Whether or not this Activation is for a cursor.
539: */
540: public boolean isCursorActivation();
541:
542: /**
543: * Save the ResultSet for the target
544: * of an update/delete to a VTI.
545: */
546: public void setTargetVTI(java.sql.ResultSet targetVTI);
547:
548: /**
549: * Get the ResultSet for the target
550: * of an update/delete to a VTI.
551: *
552: * @return The ResultSet for the target
553: * of an update/delete to a VTI.
554: */
555: public java.sql.ResultSet getTargetVTI();
556:
557: public ConstantAction getConstantAction();
558:
559: //store a reference to the parent table result sets
560: public void setParentResultSet(TemporaryRowHolder rs,
561: String resultSetId);
562:
563: /**
564: * get the reference to parent table ResultSets, that will be needed by the
565: * referential action dependent table scans.
566: */
567: public Vector getParentResultSet(String resultSetId);
568:
569: //clear the parent resultset hash table;
570: public void clearParentResultSets();
571:
572: public Hashtable getParentResultSets();
573:
574: /**
575: * beetle 3865: updateable cursor using index. A way of communication
576: * between cursor activation and update activation.
577: */
578: public void setForUpdateIndexScan(CursorResultSet forUpdateResultSet);
579:
580: public CursorResultSet getForUpdateIndexScan();
581:
582: /**
583: Return the set of dynamical created result sets, for procedures.
584: Base implementation returns null, a generated class for a procedure overwrites
585: this with a real implementation.
586: @return null if no dynamic results exists. Otherwise an array of ResultSet
587: arrays, each of length one containing null or a reference to a ResultSet.
588: */
589: public java.sql.ResultSet[][] getDynamicResults();
590:
591: /**
592: Return the maximum number of dynamical created result sets from the procedure definition.
593: Base implementation returns 0, a generated class for a procedure overwrites
594: this with a real implementation.
595: */
596: public int getMaxDynamicResults();
597: }
|