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  ;
49  import java.util.Enumeration  ;
50  import java.util.Vector  ;
51  import java.util.Hashtable  ;
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   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   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   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, String  [] 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  [] 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   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   getTargetVTI();
554 
555     public ConstantAction   getConstantAction();
556 
557     //store a reference to the parent table result sets
558     public void setParentResultSet(TemporaryRowHolder rs, String   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   getParentResultSet(String   resultSetId);
565     
566     //clear the parent resultset hash table;
567     public void clearParentResultSets();
568 
569     public Hashtable   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  [][] 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags