KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2
3    Derby - Class org.apache.derby.iapi.sql.Activation
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.dictionary.IndexRowGenerator;
29 import org.apache.derby.iapi.sql.dictionary.TableDescriptor;
30
31 import org.apache.derby.iapi.sql.execute.ExecPreparedStatement;
32 import org.apache.derby.iapi.sql.execute.ExecRow;
33 import org.apache.derby.iapi.sql.execute.ExecutionFactory;
34 import org.apache.derby.iapi.sql.execute.NoPutResultSet;
35 import org.apache.derby.iapi.sql.execute.ConstantAction;
36 import org.apache.derby.iapi.sql.execute.CursorResultSet;
37 import org.apache.derby.iapi.sql.execute.TemporaryRowHolder;
38
39 import org.apache.derby.iapi.store.access.ConglomerateController;
40 import org.apache.derby.iapi.store.access.ScanController;
41 import org.apache.derby.iapi.store.access.TransactionController;
42
43 import org.apache.derby.iapi.types.DataValueFactory;
44
45 import org.apache.derby.iapi.types.RowLocation;
46 import org.apache.derby.iapi.types.DataTypeDescriptor;
47
48 import java.sql.SQLWarning JavaDoc;
49 import java.util.Enumeration JavaDoc;
50 import java.util.Vector JavaDoc;
51 import java.util.Hashtable JavaDoc;
52
53
54 /**
55  * An activation contains all the local state information necessary
56  * to execute a re-entrant PreparedStatement. The way it will actually work
57  * is that a PreparedStatement will have an executable plan, which will be
58  * a generated class. All of the local state will be variables in the class.
59  * Creating a new instance of the executable plan will create the local state
60  * variables. This means that an executable plan must implement this interface,
61  * and that the PreparedStatement.getActivation() method will do a
62  * "new" operation on the executable plan.
63  * <p>
64  * The fixed implementations of Activation in the Execution impl
65  * package are used as skeletons for the classes generated for statements
66  * when they are compiled.
67  * <p>
68  * There are no fixed implementations of Activation for statements;
69  * a statement has an activation generated for it when it is compiled.
70  *
71  * @author Jeff Lichtman
72  */

73
74 public interface Activation
75 {
76     /**
77      * Resets the activation to the "pre-execution" state -
78      * that is, the state where it can be used to begin a new execution.
79      * Frees local buffers, stops scans, resets counters to zero, sets
80      * current date and time to an unitialized state, etc.
81      *
82      * @exception StandardException thrown on failure
83      */

84     void reset() throws StandardException;
85
86     /**
87      * JDBC requires that all select statements be converted into cursors,
88      * and that the cursor name be settable for each execution of a select
89      * statement. The Language Module will support this, so that the JDBC
90      * driver will not have to parse JSQL text. This method will have no
91      * effect when called on non-select statements.
92      * <p>
93      * There will be a JSQL statement to disable the "cursorization" of
94      * all select statements. For non-cursorized select statements, this
95      * method will have no effect.
96      * <p>
97      * This has no effect if the activation has been closed.
98      * <p>
99      * @param cursorName The cursor name to use.
100      */

101     void setCursorName(String JavaDoc cursorName);
102
103     /**
104      * Temporary tables can be declared with ON COMMIT DELETE ROWS. But if the table has a held curosr open at
105      * commit time, data should not be deleted from the table. This method, (gets called at commit time) checks if this
106      * activation held cursor and if so, does that cursor reference the passed temp table name.
107      *
108      * @return true if this activation has held cursor and if it references the passed temp table name
109      */

110     public boolean checkIfThisActivationHasHoldCursor(String JavaDoc tableName);
111
112     /**
113      * Gets the ParameterValueSet for this execution of the statement.
114      *
115      * @return The ParameterValueSet for this execution of the
116      * statement. Returns NULL if there are no parameters.
117      */

118     ParameterValueSet getParameterValueSet();
119
120     /**
121      * Sets the parameter values for this execution of the statement.
122      * <p>
123      * Has no effect if the activation has been closed.
124      *
125      * <p>
126      * NOTE: The setParameters() method is currently unimplemented.
127      * A statement with parameters will generate its own ParameterValueSet,
128      * which can be gotten with the getParameterValueSet() method (above).
129      * The idea behind setParameters() is to improve performance when
130      * operating across a network by allowing all the parameters to be set
131      * in one call, as opposed to one call per parameter.
132      *
133      * @param parameterValues The values of the parameters.
134      */

135     void setParameters(ParameterValueSet parameterValues, DataTypeDescriptor[] parameterTypes) 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 JavaDoc getWarnings();
186
187     /**
188       Add a warning to the activation
189       */

190     void addWarning(SQLWarning JavaDoc 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 JavaDoc 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, String JavaDoc[] columnNames);
359
360     /**
361      * Returns true if auto-generated keys resultset request was made for this
362      * avtivation.
363      * <p>
364      * @return auto-generated keys resultset mode for this activation.
365      */

366     public boolean getAutoGeneratedKeysResultsetMode();
367
368     /**
369      * Returns the column positions array of columns requested in auto-generated
370      * keys resultset for this avtivation. Returns null if no specific column
371      * requested by positions
372      * <p>
373      * @return column positions array of columns requested.
374      */

375     public int[] getAutoGeneratedKeysColumnIndexes();
376
377     /**
378      * Returns the column names array of columns requested in auto-generated
379      * keys resultset for this avtivation. Returns null if no specific column
380      * requested by names
381      * <p>
382      * @return column names array of columns requested.
383      */

384     public String JavaDoc[] getAutoGeneratedKeysColumnNames();
385
386     /**
387      * Mark the activation as unused.
388      */

389     public void markUnused();
390
391     /**
392      * Is the activation in use?
393      *
394      * @return true/false
395      */

396     public boolean isInUse();
397
398     /**
399      * Tell this activation that the given ResultSet was found to have
400      * the given number of rows. This is used during execution to determine
401      * whether a table has grown or shrunk. If a table's size changes
402      * significantly, the activation may invalidate its PreparedStatement
403      * to force recompilation.
404      *
405      * Note that the association of row counts with ResultSets is kept
406      * in the activation class, not in the activation itself. This
407      * means that this method must be synchronized.
408      *
409      * This method is not required to check the number of rows on each
410      * call. Because of synchronization, this check is likely to be
411      * expensive, so it may only check every hundred calls or so.
412      *
413      * @exception StandardException Thrown on error
414      */

415     public void informOfRowCount(NoPutResultSet resultSet, long rowCount)
416                     throws StandardException;
417
418     /**
419      * Get the ConglomerateController, if any, that has already
420      * been opened for the heap when scaning for an update or delete.
421      * (Saves opening the ConglomerateController twice.)
422      *
423      * @return The ConglomerateController, if available, to use for the update.
424      */

425     public ConglomerateController getHeapConglomerateController();
426
427     /**
428      * Set the ConglomerateController to be used for an update or delete.
429      * (Saves opening the ConglomerateController twice.)
430      *
431      * @param updateHeapCC The ConglomerateController to reuse for the update or delete.
432      */

433     public void setHeapConglomerateController(ConglomerateController updateHeapCC);
434
435     /**
436      * Clear the ConglomerateController to be used for an update or delete.
437      * (Saves opening the ConglomerateController twice.)
438      */

439     public void clearHeapConglomerateController();
440
441     /**
442      * Get the ScanController, if any, that has already
443      * been opened for the index when scaning for an update or delete.
444      * (Saves opening the ScanController twice.)
445      *
446      * @return The ScanController, if available, to use for the update.
447      */

448     public ScanController getIndexScanController();
449
450     /**
451      * Set the ScanController to be used for an update or delete,
452      * when scanning an index that will also be updated
453      * (Saves opening the ScanController twice.)
454      *
455      * @param indexSC The ScanController to reuse for the update or delete.
456      */

457     public void setIndexScanController(ScanController indexSC);
458
459     /**
460      * Get the conglomerate number of the index, if any, that has already
461      * been opened for scaning for an update or delete.
462      * (Saves opening the ScanController twice.)
463      *
464      * @return The conglomerate number, if available, to use for the update.
465      */

466     public long getIndexConglomerateNumber();
467
468     /**
469      * Set the conglomerate number of the index to be used for an update or delete,
470      * when scanning an index that will also be updated
471      * (Saves opening the ScanController twice.)
472      *
473      * @param indexConglomerateNumber The conglomerate number of the index to reuse for the update or delete.
474      */

475     public void setIndexConglomerateNumber(long indexConglomerateNumber);
476
477     /**
478      * Clear the info for the index to be re-used for update/delete.
479      * (ScanController and conglomerate number.)
480      */

481     public void clearIndexScanInfo();
482
483     /**
484      * Mark the Activation as being for create table.
485      * (NOTE: We can do certain optimizations for
486      * create table that we can't do for other DDL.)
487      */

488     public void setForCreateTable();
489
490     /**
491      * Get whether or not this activation is for
492      * create table.
493      * (NOTE: We can do certain optimizations for
494      * create table that we can't do for other DDL.)
495      *
496      * @return Whether or not this activation is for
497      * create table.
498      */

499     public boolean getForCreateTable();
500
501     /**
502      * Save the TableDescriptor for the target of
503      * DDL so that it can be passed between the
504      * various ConstantActions during execution.
505      */

506     public void setDDLTableDescriptor(TableDescriptor td);
507
508     /**
509      * Get the TableDescriptor for the target of
510      * DDL.
511      *
512      * @return The TableDescriptor for the target of
513      * DDL.
514      */

515     public TableDescriptor getDDLTableDescriptor();
516
517     /**
518      * Set the maximum # of rows. (# of rows that can
519      * be returned by a ResultSet. 0 means no limit.)
520      *
521      * @param maxRows Maximum # of rows. (0 means no limit.)
522      */

523     public void setMaxRows(int maxRows);
524
525     /**
526      * Get the maximum # of rows. (# of rows that can
527      * be returned by a ResultSet. 0 means no limit.)
528      *
529      * @return Maximum # of rows. (0 means no limit.)
530      */

531     public int getMaxRows();
532
533     /**
534      * Is this Activation for a cursor?
535      *
536      * @return Whether or not this Activation is for a cursor.
537      */

538     public boolean isCursorActivation();
539
540     /**
541      * Save the ResultSet for the target
542      * of an update/delete to a VTI.
543      */

544     public void setTargetVTI(java.sql.ResultSet JavaDoc targetVTI);
545
546     /**
547      * Get the ResultSet for the target
548      * of an update/delete to a VTI.
549      *
550      * @return The ResultSet for the target
551      * of an update/delete to a VTI.
552      */

553     public java.sql.ResultSet JavaDoc getTargetVTI();
554
555     public ConstantAction getConstantAction();
556
557     //store a reference to the parent table result sets
558
public void setParentResultSet(TemporaryRowHolder rs, String JavaDoc resultSetId);
559
560     /**
561      * get the reference to parent table ResultSets, that will be needed by the
562      * referential action dependent table scans.
563      */

564     public Vector JavaDoc getParentResultSet(String JavaDoc resultSetId);
565     
566     //clear the parent resultset hash table;
567
public void clearParentResultSets();
568
569     public Hashtable JavaDoc getParentResultSets();
570
571     /**
572      * beetle 3865: updateable cursor using index. A way of communication
573      * between cursor activation and update activation.
574      */

575     public void setForUpdateIndexScan(CursorResultSet forUpdateResultSet);
576
577     public CursorResultSet getForUpdateIndexScan();
578
579     /**
580         Return the set of dynamical created result sets, for procedures.
581         Base implementation returns null, a generated class for a procedure overwrites
582         this with a real implementation.
583         @return null if no dynamic results exists. Otherwise an array of ResultSet
584         arrays, each of length one containing null or a reference to a ResultSet.
585     */

586     public java.sql.ResultSet JavaDoc[][] getDynamicResults();
587
588     /**
589         Return the maximum number of dynamical created result sets from the procedure definition.
590         Base implementation returns 0, a generated class for a procedure overwrites
591         this with a real implementation.
592     */

593     public int getMaxDynamicResults();
594 }
595
Popular Tags