TransactionController


1   /*
2   
3      Derby - Class org.apache.derby.iapi.store.access.TransactionController
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.store.access;
23  
24  import java.util.Properties  ;
25  
26  import java.io.Serializable  ;
27  
28  import org.apache.derby.iapi.services.context.ContextManager;
29  import org.apache.derby.iapi.services.property.PersistentSet;
30  import org.apache.derby.iapi.services.io.Storable;
31  
32  import org.apache.derby.iapi.error.StandardException;
33  
34  import org.apache.derby.iapi.store.raw.Loggable;
35  import org.apache.derby.iapi.store.raw.Transaction;
36  
37  import org.apache.derby.iapi.types.DataValueDescriptor;
38  
39  import org.apache.derby.iapi.store.access.BackingStoreHashtable;
40  import org.apache.derby.iapi.services.io.FormatableBitSet;
41  
42  import org.apache.derby.iapi.store.access.DatabaseInstant;
43  import org.apache.derby.iapi.error.ExceptionSeverity;
44  /**
45  
46  The TransactionController interface provides methods that an access client
47  can use to control a transaction, which include the methods for
48  gaining access to resources (conglomerates, scans, etc.) in the transaction
49  controller's storage manager.  TransactionControllers are obtained
50  from an AccessFactory via the getTransaction method.
51  <P>
52  Each transaction controller is associated with a transaction context which
53  provides error cleanup when standard exceptions are thrown anywhere in the
54  system.  The transaction context performs the following actions in response
55  to cleanupOnError:
56  <UL>
57  <LI>
58  If the error is an instance of StandardException that has a severity less
59  than ExceptionSeverity.TRANSACTION_SEVERITY all resources remain unaffected.
60  <LI>
61  If the error is an instance of StandardException that has a severity equal
62  to ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released.  An attempt
63  to use any resource obtained from this transaction controller after
64  such an error will result in an error.  The transaction controller itself remains
65  valid, however.
66  <LI>
67  If the error is an instance of StandardException that has a severity greater
68  than ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released and the
69  context is popped from the stack.  Attempting to use this controller or any
70  resources obtained from it will result in an error.
71  </UL>
72  Transactions are obtained from an AccessFactory.
73  @see AccessFactory#getTransaction
74  @see org.apache.derby.iapi.error.StandardException
75  @see PersistentSet
76  
77  
78  **/
79  
80  public interface TransactionController
81      extends PersistentSet
82  {
83  
84      /**
85       * Constant used for the lock_level argument to openConglomerate() and 
86       * openScan() calls.  Pass in MODE_RECORD if you want the conglomerate
87       * to be opened with record level locking (but the system may override
88       * this choice and provide table level locking instead).  
89       **/
90      static final int MODE_RECORD    = 6;
91      /**
92       * Constant used for the lock_level argument to openConglomerate() and 
93       * openScan() calls.  Pass in MODE_TABLE if you want the conglomerate
94       * to be opened with table level locking - if this mode is passed in the
95       * system will never use record level locking for the open scan or 
96       * controller.
97       **/
98      static final int MODE_TABLE     = 7;
99  
100     /**
101      * Constants used for the isolation_level argument to openConglomerate() and
102      * openScan() calls.
103      **/
104 
105     /**
106      * 
107      * No locks are requested for data that is read only.  Uncommitted data
108      * may be returned.  Writes only visible previous to commit.
109      * Exclusive transaction length locks are set on data that is written, no
110      * lock is set on data that is read.  No table level intent lock is held
111      * so it is up to caller to insure that table is not dropped while being
112      * accessed (RESOLVE - this issue may need to be resolved differently if
113      * we can't figure out a non-locked based way to prevent ddl during
114      * read uncommitted access).
115      *
116      * ONLY USED INTERNALLY BY ACCESS, NOT VALID FOR EXTERNAL USERS.
117      **/
118     static final int ISOLATION_NOLOCK = 0;
119 
120     /**
121      * No locks are requested for data that is read only.  Uncommitted data
122      * may be returned.  Writes only visible previous to commit.
123      * Exclusive transaction length locks are set on data that is written, no
124      * lock is set on data that is read.  No table level intent lock is held
125      * so it is up to caller to insure that table is not dropped while being
126      * accessed (RESOLVE - this issue may need to be resolved differently if
127      * we can't figure out a non-locked based way to prevent ddl during
128      * read uncommitted access).
129      *
130      * Note that this is currently only supported in heap scans.
131      *
132      * TODO - work in progress to support this locking mode in the 5.1 
133      * storage system.  
134      **/
135     static final int ISOLATION_READ_UNCOMMITTED = 1;
136 
137     /**
138      * No lost updates, no dirty reads, only committed data is returned.  
139      * Writes only visible when committed.  Exclusive transaction
140      * length locks are set on data that is written, short term locks (
141      * possibly instantaneous duration locks) are set
142      * on data that is read.  
143      **/
144     static final int ISOLATION_READ_COMMITTED = 2;
145 
146     /**
147      * No lost updates, no dirty reads, only committed data is returned.  
148      * Writes only visible when committed.  Exclusive transaction
149      * length locks are set on data that is written, short term locks (
150      * possibly instantaneous duration locks) are set
151      * on data that is read.  Read locks are requested for "zero" duration,
152      * thus upon return from access no read row lock is held.
153      **/
154     static final int ISOLATION_READ_COMMITTED_NOHOLDLOCK = 3;
155 
156     /**
157      * Read and write locks are held until end of transaction, but no
158      * phantom protection is performed (ie no previous key locking).
159      * Writes only visible when committed. 
160      *
161      * Note this constant is currently mapped to ISOLATION_SERIALIZABLE.  
162      * The constant is provided so that code which only requires repeatable 
163      * read can be coded with the right isolation level, and will just work when
164      * store provided real repeatable read isolation.
165      **/
166     static final int ISOLATION_REPEATABLE_READ = 4;
167 
168     /**
169      * Gray's isolation degree 3, "Serializable, Repeatable Read".  Note that
170      * some conglomerate implementations may only be able to provide 
171      * phantom protection under MODE_TABLE, while others can support this
172      * under MODE_RECORD.
173      **/
174     static final int ISOLATION_SERIALIZABLE = 5;
175 
176     /**
177      * Constants used for the flag argument to openConglomerate() and 
178      * openScan() calls.
179      *
180      * NOTE - The values of these constants must correspond to their associated
181      * constants in 
182      * protocol.Database.Storage.RawStore.Interface.ContainerHandle, do not
183      * add constants to this file without first adding there.
184      **/
185 
186     /**
187      * Use this mode to the openScan() call to indicate the scan should get
188      * update locks during scan, and either promote the update locks to 
189      * exclusive locks if the row is changed or demote the lock if the row
190      * is not updated.  The lock demotion depends on the isolation level of
191      * the scan.  If isolation level is ISOLATION_SERIALIZABLE or 
192      * ISOLATION_REPEATABLE_READ
193      * then the lock will be converted to a read lock.  If the isolation level 
194      * ISOLATION_READ_COMMITTED then the lock is released when the scan moves
195      * off the row.
196      * <p>
197      * Note that one must still set OPENMODE_FORUPDATE to be able to change
198      * rows in the scan.  So to enable update locks for an updating scan one
199      * provides (OPENMODE_FORUPDATE | OPENMODE_USE_UPDATE_LOCKS)
200      **/
201     static final int OPENMODE_USE_UPDATE_LOCKS      = 0x00001000;
202 
203     /**
204      * Use this mode to the openConglomerate() call which opens the base
205      * table to be used in a index to base row probe.  This will cause
206      * the openConglomerate() call to not get any row locks as part of
207      * it's fetches.
208      * It is important when using this mode that the secondary index table be
209      * successfully opened before opening the base table so that
210      * proper locking protocol is followed.
211      **/
212     static final int OPENMODE_SECONDARY_LOCKED      = 0x00002000;
213 
214     /**
215      * Use this mode to the openConglomerate() call used to open the
216      * secondary indices of a table for inserting new rows in the table.
217      * This will let the secondaryindex know that the base row being inserted
218      * has already been locked and only previous key locks need be obtained.
219      * 
220      * It is important when using this mode that the base table be
221      * successfully opened before opening the secondaryindex so that
222      * proper locking protocol is followed.
223      **/
224     static final int OPENMODE_BASEROW_INSERT_LOCKED = 0x00004000;
225 
226     /**
227      * open table for update, if not specified table will be opened for read.
228      **/
229     static final int OPENMODE_FORUPDATE             = 0x00000004;
230 
231     /**
232      * Use this mode to the openConglomerate() call used to just get the
233      * table lock on the conglomerate without actually doing anything else.
234      * Any operations other than close() performed on the "opened" container
235      * will fail.
236      **/
237     static final int OPENMODE_FOR_LOCK_ONLY         = 0x00000040;
238 
239     /**
240      * The table lock request will not wait.
241      * <p>
242      * The request to get the table lock (any table lock including intent or
243      * "real" table level lock), will not wait if it can't be granted.   A
244      * lock timeout will be returned.  Note that subsequent row locks will
245      * wait if the application has not set a 0 timeout and if the call does
246      * not have a wait parameter (like OpenConglomerate.fetch().
247      **/
248     static final int OPENMODE_LOCK_NOWAIT           = 0x00000080;
249 
250     /**
251      * Constants used for the countOpen() call.
252      **/
253     public static final int OPEN_CONGLOMERATE   = 0x01;
254     public static final int OPEN_SCAN           = 0x02;
255     public static final int OPEN_CREATED_SORTS  = 0x03;
256     public static final int OPEN_SORT           = 0x04;
257     public static final int OPEN_TOTAL          = 0x05;
258 
259 
260     static final byte IS_DEFAULT    =   (byte) 0x00; // initialize the flag
261     static final byte IS_TEMPORARY  =   (byte) 0x01; // conglom is temporary
262     static final byte IS_KEPT       =   (byte) 0x02; // no auto remove
263 
264 
265     /**************************************************************************
266      * Interfaces previously defined in TcAccessIface:
267      **************************************************************************
268      */
269 
270     /**
271     Check whether a conglomerate exists.
272 
273     @param  conglomId  The identifier of the conglomerate to check for.
274 
275     @return  true if the conglomerate exists, false otherwise.
276 
277     @exception StandardException   only thrown if something goes
278     wrong in the lower levels.
279     **/
280     boolean conglomerateExists(long conglomId)
281         throws StandardException;
282 
283     /**
284     Create a conglomerate.
285     <p>
286     Currently, only "heap"'s and ""btree secondary index"'s are supported, 
287     and all the features are not completely implemented.  
288     For now, create conglomerates like this:
289     <p>
290     <blockquote><pre>
291         TransactionController tc;
292         long conglomId = tc.createConglomerate(
293             "heap", // we're requesting a heap conglomerate
294             template, // a populated template is required for heap and btree.
295             null, // default properties
296             0); // not temporary
297     </blockquote></pre>
298 
299     Each implementation of a conglomerate takes a possibly different set
300     of properties.  The "heap" implementation currently takes no properties.
301 
302     The "btree secondary index" requires the following set of properties:
303     <UL>
304     <LI> "baseConglomerateId" (integer).  The conglomerate id of the base
305     conglomerate is never actually accessed by the b-tree secondary
306     index implementation, it only serves as a namespace for row locks.
307     This property is required.
308     <LI> "rowLocationColumn" (integer).  The zero-based index into the row which
309     the b-tree secondary index will assume holds a @see RowLocation of
310     the base row in the base conglomerate.  This value will be used
311     for acquiring locks.  In this implementation RowLocationColumn must be 
312     the last key column.
313     This property is required.
314     <LI>"allowDuplicates" (boolean).  If set to true the table will allow 
315     rows which are duplicate in key column's 0 through (nUniqueColumns - 1).
316     Currently only supports "false".
317     This property is optional, defaults to false.
318     <LI>"nKeyFields"  (integer) Columns 0 through (nKeyFields - 1) will be 
319     included in key of the conglomerate.
320     This implementation requires that "nKeyFields" must be the same as the
321     number of fields in the conglomerate, including the rowLocationColumn.
322     Other implementations may relax this restriction to allow non-key fields
323     in the index.
324     This property is required.
325     <LI>"nUniqueColumns" (integer) Columns 0 through "nUniqueColumns" will be 
326     used to check for uniqueness.  So for a standard SQL non-unique index 
327     implementation set "nUniqueColumns" to the same value as "nKeyFields"; and
328     for a unique index set "nUniqueColumns" to "nKeyFields - 1 (ie. don't 
329     include the rowLocationColumn in the uniqueness check).
330     This property is required.
331     <LI>"maintainParentLinks" (boolean)
332     Whether the b-tree pages maintain the page number of their parent.  Only
333     used for consistency checking.  It takes a certain amount more effort to
334     maintain these links, but they're really handy for ensuring that the index
335     is consistent.
336     This property is optional, defaults to true.
337     </UL>
338 
339     A secondary index i (a, b) on table t (a, b, c) would have rows
340     which looked like (a, b, row_location).  baseConglomerateId is set to the
341     conglomerate id of t.  rowLocationColumns is set to 2.  allowsDuplicates
342     would be set to false.  To create a unique
343     secondary index set uniquenessColumns to 2, this means that the btree
344     code will compare the key values but not the row id when determing
345     uniqueness.  To create a nonunique secondary index set uniquenessColumns
346     to 3, this would mean that the uniqueness test would include the row
347     location and since all row locations will be unique  all rows inserted
348     into the index will be differentiated (at least) by row location.
349 
350     @return The identifier to be used to open the conglomerate later.
351 
352     @param implementation Specifies what kind of conglomerate to create.
353     THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.
354     For now, use "BTREE" or "heap" for a local access manager.
355 
356     @param template A row which describes the prototypical
357     row that the conglomerate will be holding.
358     Typically this row gives the conglomerate
359     information about the number and type of
360     columns it will be holding.  The implementation
361     may require a specific subclass of row type.
362     Note that the createConglomerate call reads the template and makes a copy
363     of any necessary information from the template, no reference to the
364     template is kept (and thus this template can be re-used in subsequent
365     calls - such as openScan()).  This field is required when creating either
366     a heap or btree conglomerate.
367 
368     @param columnOrder Specifies the colummns sort order.
369     Useful only when the conglomerate is of type BTREE, default
370     value is 'null', which means all columns needs to be sorted in 
371     Ascending order.
372 
373 
374     @param properties Implementation-specific properties of the
375     conglomerate.  
376 
377     @param  temporaryFlag
378     Where temporaryFlag can have the following values:
379     IS_DEFAULT      - no bit is set.
380     IS_TEMPORARY    - if set, the conglomerate is temporary
381     IS_KEPT         - only looked at if IS_TEMPORARY,
382                       if set, the temporary container is not
383                       removed automatically by store when
384                       transaction terminates.
385 
386     If IS_TEMPORARY is set, the conglomerate is temporary.
387     Temporary conglomerates are only visible through the transaction
388     controller that created them.  Otherwise, they are opened,
389     scanned, and dropped in the same way as permanent conglomerates.
390     Changes to temporary conglomerates persist across commits, but
391     temporary conglomerates are truncated on abort (or rollback
392     to savepoint).  Updates to temporary conglomerates are not 
393     locked or logged.
394 
395     A temporary conglomerate is only visible to the transaction
396     controller that created it, even if the conglomerate IS_KEPT
397     when the transaction termination.
398 
399     All temporary conglomerate is removed by store when the
400     conglomerate controller is destroyed, or if it is dropped by an explicit
401     dropConglomerate.  If cloudscape reboots, all temporary
402     conglomerates are removed.
403 
404     @exception  StandardException  if the conglomerate could
405     not be created for some reason.
406     **/
407     long createConglomerate(
408     String                    implementation,
409     DataValueDescriptor[]   template,
410     ColumnOrdering[]        columnOrder,
411     Properties                properties,
412     int                     temporaryFlag)
413         throws StandardException;
414 
415     /**
416     Create a conglomerate and load (filled) it with rows that comes from the
417     row source without loggging.  
418 
419     <p>Individual rows that are loaded into the conglomerate are not
420     logged. After this operation, the underlying database must be backed up
421     with a database backup rather than an transaction log backup (when we have
422     them). This warning is put here for the benefit of future generation.
423 
424     <p>
425     This function behaves the same as @see createConglomerate except it also
426     populates the conglomerate with rows from the row source and the rows that
427     are inserted are not logged.
428 
429     @param implementation Specifies what kind of conglomerate to create.
430     THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.
431     For now, use "BTREE" or "heap" for a local access manager.
432 
433     @param rowSource the interface to recieve rows to load into the
434     conglomerate. 
435 
436     @param rowCount - if not null the number of rows loaded into the table
437     will be returned as the first element of the array.
438 
439     @exception StandardException if the conglomerate could not be created or
440     loaded for some reason.  Throws 
441     SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION if
442     the conglomerate supports uniqueness checks and has been created to
443     disallow duplicates, and one of the rows being loaded had key columns which
444     were duplicate of a row already in the conglomerate.
445     **/
446     long createAndLoadConglomerate(
447     String                    implementation,
448     DataValueDescriptor[]   template,
449     ColumnOrdering[]        columnOrder,
450     Properties                properties,
451     int                     temporaryFlag,
452     RowLocationRetRowSource rowSource,
453     long[] rowCount)
454     throws StandardException;
455 
456     /**
457     Recreate a conglomerate and possibly load it with new rows that come from
458     the new row source.
459 
460     <p>
461     This function behaves the same as @see createConglomerate except it also
462     populates the conglomerate with rows from the row source and the rows that
463     are inserted are not logged.
464 
465     <p>Individual rows that are loaded into the conglomerate are not
466     logged. After this operation, the underlying database must be backed up
467     with a database backup rather than an transaction log backup (when we have
468     them). This warning is put here for the benefit of future generation.
469 
470     @param implementation Specifies what kind of conglomerate to create.
471     THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.
472     For now, use "BTREE" or "heap" for a local access manager.
473 
474     @param recreate_ifempty If false, and the rowsource used to load the new
475                             conglomerate returns no rows, then the original
476                             conglomid will be returned.  To the client it will
477                             be as if no call was made.  Underlying 
478                             implementations may actually create and drop a 
479                             container.
480                             If true, then a new empty container will be 
481                             created and it's conglomid will be returned.
482 
483     @param template A row which describes the prototypical
484     row that the conglomerate will be holding.
485     Typically this row gives the conglomerate
486     information about the number and type of
487     columns it will be holding.  The implementation
488     may require a specific subclass of row type.
489     Note that the createConglomerate call reads the template and makes a copy
490     of any necessary information from the template, no reference to the
491     template is kept (and thus this template can be re-used in subsequent
492     calls - such as openScan()).  This field is required when creating either
493     a heap or btree conglomerate.
494 
495     @param columnOrder  Specifies the colummns sort order.
496     Useful only when the conglomerate is of type BTREE, default
497     value is 'null', which means all columns needs to be sorted in 
498     Ascending order.
499 
500     @param properties Implementation-specific properties of the conglomerate.  
501 
502     @param  temporaryFlag  If true, the conglomerate is temporary.
503     Temporary conglomerates are only visible through the transaction
504     controller that created them.  Otherwise, they are opened,
505     scanned, and dropped in the same way as permanent conglomerates.
506     Changes to temporary conglomerates persist across commits, but
507     temporary conglomerates are truncated on abort (or rollback
508     to savepoint).  Updates to temporary conglomerates are not 
509     locked or logged.
510 
511     @param orig_conglomId The conglomid of the original conglomerate.
512 
513     @param rowSource interface to receive rows to load into the conglomerate. 
514 
515     @param rowCount - if not null the number of rows loaded into the table
516     will be returned as the first element of the array.
517 
518     @exception StandardException if the conglomerate could not be created or
519     loaded for some reason.  Throws 
520     SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION if
521     the conglomerate supports uniqueness checks and has been created to
522     disallow duplicates, and one of the rows being loaded had key columns which
523     were duplicate of a row already in the conglomerate.
524     **/
525     long recreateAndLoadConglomerate(
526     String                    implementation,
527     boolean                 recreate_ifempty,
528     DataValueDescriptor[]   template,
529     ColumnOrdering[]        columnOrder,
530     Properties                properties,
531     int                     temporaryFlag,
532     long                    orig_conglomId,
533     RowLocationRetRowSource rowSource,
534     long[] rowCount
535     )
536         throws StandardException;
537 
538     /**
539     Add a column to a conglomerate.  
540     
541     The Storage system will block this action until it can get an exclusive
542     container level lock on the conglomerate.  The conglomerate must not be
543     open in the current transaction, this means that within the current 
544     transaction there must be no open ConglomerateController's or 
545     ScanControllers.  It may not be possible in some implementations of the
546     system to catch this error in the store, so it is up to the caller to 
547     insure this.
548 
549     The column can only be added at the spot just after the current set of
550     columns.  
551 
552     The template_column must be nullable.  
553     
554     After this call has been made, all fetches of this column from rows that
555     existed in the table prior to this call will return "null".
556 
557     @param conglomId        The identifier of the conglomerate to alter.
558     @param column_id        The column number to add this column at.
559     @param template_column  An instance of the column to be added to table.
560 
561     @exception StandardException Only some types of conglomerates can support
562         adding a column, for instance "heap" conglomerates support adding a 
563         column while "btree" conglomerates do not.  If the column can not be
564         added an exception will be thrown.
565     **/
566     public void addColumnToConglomerate(
567     long        conglomId, 
568     int         column_id, 
569     Storable    template_column)
570         throws StandardException;
571 
572 
573     /**
574     Drop a conglomerate.  The conglomerate must not be open in
575     the current transaction.  This also means that there must
576     not be any active scans on it.
577 
578     @param conglomId The identifier of the conglomerate to drop.
579 
580     @exception StandardException if the conglomerate could not be
581      dropped for some reason.
582     **/
583     void dropConglomerate(long conglomId)
584         throws StandardException;
585 
586     /**
587      * For debugging, find the conglomid given the containerid.
588      * <p>
589      *
590      * @return the conglomid, which contains the container with containerid.
591      *
592      * @exception  StandardException  Standard exception policy.
593      **/
594     long findConglomid(long containerid)
595         throws StandardException;
596 
597     /**
598      * For debugging, find the containerid given the conglomid.
599      * <p>
600      * Will have to change if we ever have more than one container in 
601      * a conglomerate.
602      *
603      * @return the containerid of container implementing conglomerate with 
604      *             "conglomid."
605      *
606      * @exception  StandardException  Standard exception policy.
607      **/
608     long findContainerid(long conglomid)
609         throws StandardException;
610 
611     /**
612      * Get an nested user transaction.
613      * <p>
614      * A nested user transaction can be used exactly as any other 
615      * TransactionController, except as follows.  For this discussion let the 
616      * parent transaction be the transaction used to make the 
617      * startNestedUserTransaction() call, and let the child transaction be the
618      * transaction returned by the startNestedUserTransaction() call.
619      * <p>
620      * Only 1 non-readOnly nested user transaction can exist.  If a subsequent
621      * non-readOnly transaction creation is attempted prior to destroying an
622      * existing write nested user transaction an exception will be thrown.  
623      * <p>
624      * The nesting is limited to one level deep.  An exception will be thrown
625      * if a subsequent getNestedUserTransaction() is called on the child
626      * transaction.
627      * <p>
628      * The locks in the child transaction of a readOnly nested user transaction
629      * will be compatible with the locks of the parent transaction.  The
630      * locks in the child transaction of a non-readOnly nested user transaction
631      * will NOT be compatible with those of the parent transaction - this is
632      * necessary for correct recovery behavior.
633      * <p>
634      * A commit in the child transaction will release locks associated with
635      * the child transaction only, work can continue in the parent transaction
636      * at this point.  
637      * <p>
638      * Any abort of the child transaction will result in an abort of both
639      * the child transaction and parent transaction, either initiated by
640      * an explict abort() call or by an exception that results in an abort.
641      * <p>
642      * A TransactionController.destroy() call should be made on the child
643      * transaction once all child work is done, and the caller wishes to 
644      * continue work in the parent transaction.
645      * <p>
646      * AccessFactory.getTransaction() will always return the "parent" 
647      * transaction, never the child transaction.  Thus clients using 
648      * nested user transactions must keep track of the transaction, as there
649      * is no interface to query the storage system to get the current
650      * child transaction.  The idea is that a nested user transaction should
651      * be used to for a limited amount of work, committed, and then work
652      * continues in the parent transaction.
653      * <p>
654      * Nested User transactions are meant to be used to implement 
655      * system work necessary to commit as part of implementing a user's
656      * request, but where holding the lock for the duration of the user
657      * transaction is not acceptable.  2 examples of this are system catalog
658      * read locks accumulated while compiling a plan, and auto-increment.
659      * <p>
660      * Once the first write of a non-readOnly nested transaction is done,
661      * then the nested user transaction must be committed or aborted before
662      * any write operation is attempted in the parent transaction.  
663      *
664      * @param readOnly  Is transaction readonly?  Only 1 non-readonly nested
665      *                  transaction is allowed per transaction.
666      *
667      * @return The new nested user transaction.
668      *
669      * @exception  StandardException  Standard exception policy.
670      **/
671     public TransactionController startNestedUserTransaction(boolean readOnly)
672         throws StandardException;
673 
674     /**
675      * A superset of properties that "users" can specify.
676      * <p>
677      * A superset of properties that "users" (ie. from sql) can specify.  Store
678      * may implement other properties which should not be specified by users.
679      * Layers above access may implement properties which are not known at
680      * all to Access.
681      * <p>
682      * This list is a superset, as some properties may not be implemented by
683      * certain types of conglomerates.  For instant an in-memory store may not
684      * implement a pageSize property.  Or some conglomerates may not support
685      * pre-allocation.
686      * <p>
687      * This interface is meant to be used by the SQL parser to do validation
688      * of properties passsed to the create table statement, and also by the
689      * various user interfaces which present table information back to the 
690      * user.
691      * <p>
692      * Currently this routine returns the following list:
693      *      derby.storage.initialPages
694      *      derby.storage.minimumRecordSize
695      *      derby.storage.pageReservedSpace
696      *      derby.storage.pageSize
697      *
698      * @return The superset of properties that "users" can specify.
699      *
700      **/
701     Properties   getUserCreateConglomPropList();
702 
703     /**
704      * Open a conglomerate for use.  
705      * <p>
706      * The lock level indicates the minimum lock level to get locks at, the
707      * underlying conglomerate implementation may actually lock at a higher
708      * level (ie. caller may request MODE_RECORD, but the table may be locked
709      * at MODE_TABLE instead).
710      * <p>
711      * The close method is on the ConglomerateController interface.
712      *
713      * @return a ConglomerateController to manipulate the conglomerate.
714      *
715      * @param conglomId         The identifier of the conglomerate to open.
716      *
717      * @param hold              If true, will be maintained open over commits.
718      *
719      * @param open_mode         Specifiy flags to control opening of table.  
720      *                          OPENMODE_FORUPDATE - if set open the table for
721      *                          update otherwise open table shared.
722      *
723      * @param lock_level        One of (MODE_TABLE, MODE_RECORD).
724      *
725      * @param isolation_level   The isolation level to lock the conglomerate at.
726      *                          One of (ISOLATION_READ_COMMITTED, 
727      *                          ISOLATION_REPEATABLE_READ or 
728      *                          ISOLATION_SERIALIZABLE).
729      *
730      * @exception  StandardException  if the conglomerate could not be opened 
731      *                                for some reason.  Throws 
732      *                                SQLState.STORE_CONGLOMERATE_DOES_NOT_EXIST
733      *                                if the conglomId being requested does not
734      *                                exist for some reason (ie. someone has 
735      *                                dropped it).
736      **/
737     ConglomerateController openConglomerate(
738     long                            conglomId, 
739     boolean                         hold,
740     int                             open_mode,
741     int                             lock_level,
742     int                             isolation_level)
743         throws StandardException;
744 
745     /**
746      * Open a conglomerate for use, optionally include "compiled" info.  
747      * <p>
748      * Same as openConglomerate(), except that one can optionally provide
749      * "compiled" static_info and/or dynamic_info.  This compiled information
750      * must have be gotten from getDynamicCompiledConglomInfo() and/or
751      * getStaticCompiledConglomInfo() calls on the same conglomid being opened.
752      * It is up to caller that "compiled" information is still valid and
753      * is appropriately multi-threaded protected.
754      * <p>
755      *
756      * @see TransactionController#openConglomerate
757      * @see TransactionController#getDynamicCompiledConglomInfo
758      * @see TransactionController#getStaticCompiledConglomInfo
759      * @see DynamicCompiledOpenConglomInfo
760      * @see StaticCompiledOpenConglomInfo
761      *
762      * @return The identifier to be used to open the conglomerate later.
763      *
764      * @param hold              If true, will be maintained open over commits.
765      * @param open_mode         Specifiy flags to control opening of table.  
766      * @param lock_level        One of (MODE_TABLE, MODE_RECORD).
767      * @param isolation_level   The isolation level to lock the conglomerate at.
768      *                          One of (ISOLATION_READ_COMMITTED, 
769      *                          ISOLATION_REPEATABLE_READ or 
770      *                          ISOLATION_SERIALIZABLE).
771      * @param static_info       object returned from 
772      *                          getStaticCompiledConglomInfo() call on this id.
773      * @param dynamic_info      object returned from
774      *                          getDynamicCompiledConglomInfo() call on this id.
775      *
776      * @exception  StandardException  Standard exception policy.
777      **/
778     ConglomerateController openCompiledConglomerate(
779     boolean                         hold,
780     int                             open_mode,
781     int                             lock_level,
782     int                             isolation_level,
783     StaticCompiledOpenConglomInfo   static_info,
784     DynamicCompiledOpenConglomInfo  dynamic_info)
785         throws StandardException;
786 
787 
788     /**
789      * Create a HashSet which contains all rows that qualify for the 
790      * described scan.
791      * <p>
792      * All parameters shared between openScan() and this routine are 
793      * interpreted exactly the same.  Logically this routine calls
794      * openScan() with the passed in set of parameters, and then places
795      * all returned rows into a newly created HashSet and returns, actual
796      * implementations will likely perform better than actually calling
797      * openScan() and doing this.  For documentation of the openScan 
798      * parameters see openScan().
799      * <p>
800      *
801      * @return the BackingStoreHashtable which was created.
802      *
803      * @param conglomId             see openScan()
804      * @param open_mode             see openScan()
805      * @param lock_level            see openScan()
806      * @param isolation_level       see openScan()
807      * @param scanColumnList        see openScan()
808      * @param startKeyValue         see openScan()
809      * @param startSearchOperator   see openScan()
810      * @param qualifier             see openScan()
811      * @param stopKeyValue          see openScan()
812      * @param stopSearchOperator    see openScan()
813      *
814      * @param max_rowcnt            The maximum number of rows to insert into 
815      *                              the HashSet.  Pass in -1 if there is no 
816      *                              maximum.
817      * @param key_column_numbers    The column numbers of the columns in the
818      *                              scan result row to be the key to the 
819      *                              Hashtable.  "0" is the first column in the 
820      *                              scan result row (which may be different 
821      *                              than the first row in the table of the 
822      *                              scan).
823      * @param remove_duplicates     Should the HashSet automatically remove
824      *                              duplicates, or should it create the Vector 
825      *                              of duplicates?
826      * @param estimated_rowcnt      The number of rows that the caller 
827      *                              estimates will be inserted into the sort. 
828      *                              -1 indicates that the caller has no idea.
829      *                              Used by the sort to make good choices about
830      *                              in-memory vs. external sorting, and to size
831      *                              merge runs.
832      * @param max_inmemory_rowcnt   The number of rows at which the underlying
833      *                              Hashtable implementation should cut over
834      *                              from an in-memory hash to a disk based
835      *                              access method.
836      * @param initialCapacity       If not "-1" used to initialize the java
837      *                              Hashtable.
838      * @param loadFactor            If not "-1" used to initialize the java
839      *                              Hashtable.
840      * @param collect_runtimestats  If true will collect up runtime stats during
841      *                              scan processing for retrieval by
842      *                              BackingStoreHashtable.getRuntimeStats().
843      * @param skipNullKeyColumns    Whether or not to skip rows with 1 or more null key columns
844      *
845      * @see BackingStoreHashtable
846      * @see TransactionController#openScan
847      *
848      * @exception  StandardException  Standard exception policy.
849      **/
850     BackingStoreHashtable createBackingStoreHashtableFromScan(
851     long                    conglomId,
852     int                     open_mode,
853     int                     lock_level,
854     int                     isolation_level,
855     FormatableBitSet        scanColumnList,
856     DataValueDescriptor[]   startKeyValue,
857     int                     startSearchOperator,
858     Qualifier               qualifier[][],
859     DataValueDescriptor[]   stopKeyValue,
860     int                     stopSearchOperator,
861     long                    max_rowcnt,
862     int[]                   key_column_numbers,
863     boolean                 remove_duplicates,
864     long                    estimated_rowcnt,
865     long                    max_inmemory_rowcnt,
866     int                     initialCapacity,
867     float                   loadFactor,
868     boolean                 collect_runtimestats,
869     boolean                 skipNullKeyColumns)
870         throws StandardException;
871 
872 
873     /**
874     Open a scan on a conglomerate.  The scan will return all
875     rows in the conglomerate which are between the
876     positions defined by {startKeyValue, startSearchOperator} and
877     {stopKeyValue, stopSearchOperator}, which also match the qualifier.
878     <P>
879     The way that starting and stopping keys and operators are used
880     may best be described by example. Say there's an ordered conglomerate
881     with two columns, where the 0-th column is named 'x', and the 1st
882     column is named 'y'.  The values of the columns are as follows:
883     <blockquote><pre>
884       x: 1 3 4 4 4 5 5 5 6 7 9
885       y: 1 1 2 4 6 2 4 6 1 1 1
886     </blockquote></pre>
887     <P>
888     A {start key, search op} pair of {{5.2}, GE} would position on
889     {x=5, y=2}, whereas the pair {{5}, GT} would position on {x=6, y=1}.
890     <P>
891     Partial keys are used to implement partial key scans in SQL.
892     For example, the SQL "select * from t where x = 5" would
893     open a scan on the conglomerate (or a useful index) of t
894     using a starting position partial key of {{5}, GE} and
895     a stopping position partial key of {{5}, GT}.
896     <P>
897     Some more examples:
898     <p>
899     <blockquote><pre>
900     +-------------------+------------+-----------+--------------+--------------+
901     | predicate         | start key  | stop key  | rows         | rows locked  |
902     |                   | value | op | value |op | returned     |serialization |
903     +-------------------+-------+----+-------+---+--------------+--------------+
904     | x = 5             | {5}   | GE | {5}   |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
905     | x > 5             | {5}   | GT | null  |   |{6,1} .. {9,1}|{5,6} .. {9,1}|
906     | x >= 5            | {5}   | GE | null  |   |{5,2} .. {9,1}|{4,6} .. {9,1}|
907     | x <= 5            | null  |    | {5}   |GT |{1,1} .. {5,6}|first .. {5,6}|
908     | x < 5             | null  |    | {5}   |GE |{1,1} .. {4,6}|first .. {4,6}|
909     | x >= 5 and x <= 7 | {5},  | GE | {7}   |GT |{5,2} .. {7,1}|{4,6} .. {7,1}|
910     | x = 5  and y > 2  | {5,2} | GT | {5}   |GT |{5,4} .. {5,6}|{5,2} .. {5,6}|
911     | x = 5  and y >= 2 | {5,2} | GE | {5}   |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
912     | x = 5  and y < 5  | {5}   | GE | {5,5} |GE |{5,2} .. {5,4}|{4,6} .. {5,4}|
913     | x = 2             | {2}   | GE | {2}   |GT | none         |{1,1} .. {1,1}|
914     +-------------------+-------+----+-------+---+--------------+--------------+
915     </blockquote></pre>
916     <P>
917     As the above table implies, the underlying scan may lock
918     more rows than it returns in order to guarantee serialization.
919     <P>
920     For each row which meets the start and stop position, as described above
921     the row is "qualified" to see whether it should be returned.  The
922     qualification is a 2 dimensional array of @see Qualifiers, which represents
923     the qualification in conjunctive normal form (CNF).  Conjunctive normal
924     form is an "and'd" set of "or'd" Qualifiers.
925     <P>
926     For example x = 5 would be represented is pseudo code as:
927     
928     qualifier_cnf[][] = new Qualifier[1];
929     qualifier_cnf[0]  = new Qualifier[1];
930 
931     qualifier_cnr[0][0] = new Qualifer(x = 5)
932 
933     <P>
934     For example (x = 5) or (y = 6) would be represented is pseudo code as:
935 
936     qualifier_cnf[][] = new Qualifier[1];
937     qualifier_cnf[0]  = new Qualifier[2];
938 
939     qualifier_cnr[0][0] = new Qualifer(x = 5)
940     qualifier_cnr[0][1] = new Qualifer(y = 6)
941 
942     <P>
943     For example ((x = 5) or (x = 6)) and ((y = 1) or (y = 2)) would be 
944     represented is pseudo code as:
945 
946     qualifier_cnf[][] = new Qualifier[2];
947     qualifier_cnf[0]  = new Qualifier[2];
948 
949     qualifier_cnr[0][0] = new Qualifer(x = 5)
950     qualifier_cnr[0][1] = new Qualifer(x = 6)
951 
952     qualifier_cnr[0][0] = new Qualifer(y = 5)
953     qualifier_cnr[0][1] = new Qualifer(y = 6)
954 
955     <P>
956     For each row the CNF qualfier is processed and it is determined whether
957     or not the row should be returned to the caller.
958 
959     The following pseudo-code describes how this is done:
960 
961     <blockquote><pre>
962     if (qualifier != null)
963     {
964         <blockquote><pre>
965         for (int and_clause; and_clause < qualifier.length; and_clause++)
966         {
967             boolean or_qualifies = false;
968 
969             for (int or_clause; or_clause < qualifier[and_clause].length; or_clause++)
970             {
971                 <blockquote><pre>
972                 DataValueDescriptor key     = 
973                     qualifier[and_clause][or_clause].getOrderable();
974 
975                 DataValueDescriptor row_col = 
976                     get row column[qualifier[and_clause][or_clause].getColumnId()];
977 
978                 boolean or_qualifies = 
979                 row_col.compare(qualifier[i].getOperator,
980                 <blockquote><pre>
981                 key,
982                 qualifier[i].getOrderedNulls,
983                 qualifier[i].getUnknownRV);
984                 </blockquote></pre>
985 
986                 if (or_qualifies)
987                 {
988                     break;
989                 }
990             }
991 
992             if (!or_qualifies)
993             {
994                 <blockquote><pre>
995                 don't return this row to the client - proceed to next row;
996                 </blockquote></pre>
997             }
998             </blockquote></pre>
999 
1000        }
1001        </blockquote></pre>
1002    }
1003    </blockquote></pre>
1004
1005
1006    @param conglomId The identifier of the conglomerate
1007    to open the scan for.
1008
1009    @param hold If true, this scan will be maintained open over
1010    commits.
1011
1012    @param open_mode         Specifiy flags to control opening of table.  
1013                             OPENMODE_FORUPDATE - if set open the table for
1014                             update otherwise open table shared.
1015
1016    @param lock_level        One of (MODE_TABLE, MODE_RECORD).
1017
1018    @param isolation_level   The isolation level to lock the conglomerate at.
1019                             One of (ISOLATION_READ_COMMITTED, 
1020                             ISOLATION_REPEATABLE_READ or 
1021                             ISOLATION_SERIALIZABLE).
1022
1023    @param scanColumnList A description of which columns to return from 
1024    every fetch in the scan.  template, and scanColumnList
1025    work together to describe the row to be returned by the scan - see RowUtil
1026    for description of how these three parameters work together to describe
1027    a "row".
1028
1029    @param startKeyValue  An indexable row which holds a 
1030    (partial) key value which, in combination with the
1031    startSearchOperator, defines the starting position of
1032    the scan.  If null, the starting position of the scan
1033    is the first row of the conglomerate.
1034    The startKeyValue must only reference columns included
1035    in the scanColumnList.
1036    
1037    @param startSearchOperator an operator which defines
1038    how the startKeyValue is to be searched for.  If 
1039    startSearchOperation is ScanController.GE, the scan starts on
1040    the first row which is greater than or equal to the 
1041    startKeyValue.  If startSearchOperation is ScanController.GT,
1042    the scan starts on the first row whose key is greater than
1043    startKeyValue.  The startSearchOperation parameter is 
1044    ignored if the startKeyValue parameter is null.
1045
1046    @param qualifier A 2 dimensional array encoding a conjunctive normal
1047    form (CNF) datastructure of of qualifiers which, applied
1048    to each key, restrict the rows returned by the scan.  Rows
1049    for which the CNF expression returns false are not
1050    returned by the scan. If null, all rows are returned.
1051    Qualifiers can only reference columns which are included in the
1052    scanColumnList.  The column id that a qualifier returns is the
1053    column id the table, not the column id in the partial row being
1054    returned.
1055
1056    For detailed description of 2-dimensional array passing @see Qualifier
1057
1058    @param stopKeyValue  An indexable row which holds a 
1059    (partial) key value which, in combination with the
1060    stopSearchOperator, defines the ending position of
1061    the scan.  If null, the ending position of the scan
1062    is the last row of the conglomerate.
1063    The stopKeyValue must only reference columns included
1064    in the scanColumnList.
1065    
1066    @param stopSearchOperator an operator which defines
1067    how the stopKeyValue is used to determine the scan stopping
1068    position. If stopSearchOperation is ScanController.GE, the scan 
1069    stops just before the first row which is greater than or
1070    equal to the stopKeyValue.  If stopSearchOperation is
1071    ScanController.GT, the scan stops just before the first row whose
1072    key is greater than startKeyValue.  The stopSearchOperation
1073    parameter is ignored if the stopKeyValue parameter is null.
1074
1075    @exception StandardException if the scan could not be
1076    opened for some reason.  Throws SQLState.STORE_CONGLOMERATE_DOES_NOT_EXIST
1077    if the conglomId being requested does not exist for some reason (ie. 
1078    someone has dropped it).
1079
1080    @see RowUtil
1081    @see ScanController
1082    **/
1083    ScanController openScan(
1084        long                            conglomId,
1085        boolean                         hold,
1086        int                             open_mode,
1087        int                             lock_level,
1088        int                             isolation_level,
1089        FormatableBitSet                scanColumnList,
1090        DataValueDescriptor[]           startKeyValue,
1091        int                             startSearchOperator,
1092        Qualifier                       qualifier[][],
1093        DataValueDescriptor[]           stopKeyValue,
1094        int                             stopSearchOperator)
1095            throws StandardException;
1096
1097
1098    /**
1099     * Open a scan on a conglomerate, optionally providing compiled info.
1100     * <p>
1101     * Same as openScan(), except that one can optionally provide
1102     * "compiled" static_info and/or dynamic_info.  This compiled information
1103     * must have be gotten from getDynamicCompiledConglomInfo() and/or
1104     * getStaticCompiledConglomInfo() calls on the same conglomid being opened.
1105     * It is up to caller that "compiled" information is still valid and
1106     * is appropriately multi-threaded protected.
1107     * <p>
1108     *
1109     * @see TransactionController#openScan
1110     * @see TransactionController#getDynamicCompiledConglomInfo
1111     * @see TransactionController#getStaticCompiledConglomInfo
1112     * @see DynamicCompiledOpenConglomInfo
1113     * @see StaticCompiledOpenConglomInfo
1114     *
1115     * @return The identifier to be used to open the conglomerate later.
1116     *
1117     * @param open_mode             see openScan()
1118     * @param lock_level            see openScan()
1119     * @param isolation_level       see openScan()
1120     * @param scanColumnList        see openScan()
1121     * @param startKeyValue         see openScan()
1122     * @param startSearchOperator   see openScan()
1123     * @param qualifier             see openScan()
1124     * @param stopKeyValue          see openScan()
1125     * @param stopSearchOperator    see openScan()
1126     * @param static_info       object returned from 
1127     *                          getStaticCompiledConglomInfo() call on this id.
1128     * @param dynamic_info      object returned from
1129     *                          getDynamicCompiledConglomInfo() call on this id.
1130     *
1131     * @exception  StandardException  Standard exception policy.
1132     **/
1133    ScanController openCompiledScan(
1134        boolean                         hold,
1135        int                             open_mode,
1136        int                             lock_level,
1137        int                             isolation_level,
1138        FormatableBitSet                scanColumnList,
1139        DataValueDescriptor[]           startKeyValue,
1140        int                             startSearchOperator,
1141        Qualifier                       qualifier[][],
1142        DataValueDescriptor[]           stopKeyValue,
1143        int                             stopSearchOperator,
1144        StaticCompiledOpenConglomInfo   static_info,
1145        DynamicCompiledOpenConglomInfo  dynamic_info)
1146            throws StandardException;
1147
1148
1149    /**
1150     * Open a scan which gets copies of multiple rows at a time.
1151     * <p>
1152     * All inputs work exactly as in openScan().  The return is 
1153     * a GroupFetchScanController, which only allows fetches of groups
1154     * of rows from the conglomerate.
1155     * <p>
1156     *
1157     * @return The GroupFetchScanController to be used to fetch the rows.
1158     *
1159     * @param conglomId             see openScan()
1160     * @param open_mode             see openScan()
1161     * @param lock_level            see openScan()
1162     * @param isolation_level       see openScan()
1163     * @param scanColumnList        see openScan()
1164     * @param startKeyValue         see openScan()
1165     * @param startSearchOperator   see openScan()
1166     * @param qualifier             see openScan()
1167     * @param stopKeyValue          see openScan()
1168     * @param stopSearchOperator    see openScan()
1169     *
1170     * @exception  StandardException  Standard exception policy.
1171     *
1172     * @see ScanController
1173     * @see GroupFetchScanController
1174     **/
1175    GroupFetchScanController openGroupFetchScan(
1176        long                            conglomId,
1177        boolean                         hold,
1178        int                             open_mode,
1179        int                             lock_level,
1180        int                             isolation_level,
1181        FormatableBitSet                         scanColumnList,
1182        DataValueDescriptor[]           startKeyValue,
1183        int                             startSearchOperator,
1184        Qualifier                       qualifier[][],
1185        DataValueDescriptor[]           stopKeyValue,
1186        int                             stopSearchOperator)
1187            throws StandardException;
1188
1189    /**
1190     * Compress table in place.
1191     * <p>
1192     * Returns a GroupFetchScanController which can be used to move rows
1193     * around in a table, creating a block of free pages at the end of the
1194     * table.  The process will move rows from the end of the table toward
1195     * the beginning.  The GroupFetchScanController will return the 
1196     * old row location, the new row location, and the actual data of any
1197     * row moved.  Note that this scan only returns moved rows, not an
1198     * entire set of rows, the scan is designed specifically to be
1199     * used by either explicit user call of the SYSCS_ONLINE_COMPRESS_TABLE()
1200     * procedure, or internal background calls to compress the table.
1201     *
1202     * The old and new row locations are returned so that the caller can
1203     * update any indexes necessary.
1204     *
1205     * This scan always returns all collumns of the row.
1206     * 
1207     * All inputs work exactly as in openScan().  The return is 
1208     * a GroupFetchScanController, which only allows fetches of groups
1209     * of rows from the conglomerate.
1210     * <p>
1211     *
1212     * @return The GroupFetchScanController to be used to fetch the rows.
1213     *
1214     * @param conglomId             see openScan()
1215     * @param hold                  see openScan()
1216     * @param open_mode             see openScan()
1217     * @param lock_level            see openScan()
1218     * @param isolation_level       see openScan()
1219     *
1220     * @exception  StandardException  Standard exception policy.
1221     *
1222     * @see ScanController
1223     * @see GroupFetchScanController
1224     **/
1225    GroupFetchScanController defragmentConglomerate(
1226        long                            conglomId,
1227        boolean                         online,
1228        boolean                         hold,
1229        int                             open_mode,
1230        int                             lock_level,
1231        int                             isolation_level)
1232            throws StandardException;
1233
1234    /**
1235     * Purge all committed deleted rows from the conglomerate.
1236     * <p>
1237     * This call will purge committed deleted rows from the conglomerate,
1238     * that space will be available for future inserts into the conglomerate.
1239     * <p>
1240     *
1241     * @param conglomId Id of the conglomerate to purge.
1242     *
1243     * @exception  StandardException  Standard exception policy.
1244     **/
1245    void purgeConglomerate(long conglomId)
1246            throws StandardException;
1247
1248    /**
1249     * Return free space from the conglomerate back to the OS.
1250     * <p>
1251     * Returns free space from the conglomerate back to the OS.  Currently
1252     * only the sequential free pages at the "end" of the conglomerate can
1253     * be returned to the OS.
1254     * <p>
1255     *
1256     * @param conglomId Id of the conglomerate to purge.
1257     *
1258     * @exception  StandardException  Standard exception policy.
1259     **/
1260    void compressConglomerate(long conglomId)
1261            throws StandardException;
1262
1263
1264    /**
1265     * Retrieve the maximum value row in an ordered conglomerate.
1266     * <p>
1267     * Returns true and fetches the rightmost non-null row of an ordered 
1268     * conglomerate into "fetchRow" if there is at least one non-null row in 
1269     * the conglomerate.  If there are no non-null rows in the conglomerate it 
1270     * returns false.  Any row with
1271     * a first column with a Null is considered a "null" row.
1272     * <p>
1273     * Non-ordered conglomerates will not implement this interface, calls
1274     * will generate a StandardException.
1275     * <p>
1276     * RESOLVE - this interface is temporary, long term equivalent (and more) 
1277     * functionality will be provided by the openBackwardScan() interface.  
1278     * <p>
1279     * ISOLATION_SERIALIZABLE and MODE_RECORD locking for btree max:
1280     * The "BTREE" implementation will at the very least get a shared row lock
1281     * on the max key row and the key previous to the max.  
1282     * This will be the case where the max row exists in the rightmost page of
1283     * the btree.  These locks won't be released.  If the row does not exist in
1284     * the last page of the btree then a scan of the entire btree will be
1285     * performed, locks acquired in this scan will not be released.
1286     * <p>
1287     * Note that under ISOLATION_READ_COMMITTED, all locks on the table
1288     * are released before returning from this call.
1289     *
1290     * @param conglomId       The identifier of the conglomerate
1291     *                        to open the scan for.
1292     *
1293     * @param open_mode       Specifiy flags to control opening of table.  
1294     *                        OPENMODE_FORUPDATE - if set open the table for
1295     *                        update otherwise open table shared.
1296     * @param lock_level      One of (MODE_TABLE, MODE_RECORD).
1297     *
1298     * @param isolation_level   The isolation level to lock the conglomerate at.
1299     *                          One of (ISOLATION_READ_COMMITTED, 
1300     *                          ISOLATION_REPEATABLE_READ or 
1301     *                          ISOLATION_SERIALIZABLE).
1302     *
1303     * @param scanColumnList  A description of which columns to return from 
1304     *                        every fetch in the scan.  template, and 
1305     *                        scanColumnList work together
1306     *                        to describe the row to be returned by the scan - 
1307     *                        see RowUtil for description of how these three 
1308     *                        parameters work together to describe a "row".
1309     *
1310     * @param fetchRow        The row to retrieve the maximum value into.
1311     *
1312     * @return boolean indicating if a row was found and retrieved or not.
1313     *
1314     * @exception  StandardException  Standard exception policy.
1315     **/
1316    boolean fetchMaxOnBtree(
1317        long                    conglomId,
1318        int                     open_mode,
1319        int                     lock_level,
1320        int                     isolation_level,
1321        FormatableBitSet                 scanColumnList,
1322        DataValueDescriptor[]   fetchRow)
1323            throws StandardException;
1324
1325
1326    /**
1327     * Return an open StoreCostController for the given conglomid.
1328     * <p>
1329     * Return an open StoreCostController which can be used to ask about 
1330     * the estimated row counts and costs of ScanController and 
1331     * ConglomerateController operations, on the given conglomerate.
1332     * <p>
1333     *
1334     * @return The open StoreCostController.
1335     *
1336     * @param conglomId The identifier of the conglomerate to open.
1337     *
1338     * @exception  StandardException  Standard exception policy.
1339     *
1340     * @see StoreCostController
1341     **/
1342    StoreCostController openStoreCost(
1343    long        conglomId)
1344        throws StandardException;
1345
1346
1347    /**
1348     * Report on the number of open conglomerates in the transaction.
1349     * <p>
1350     * There are 4 types of open "conglomerates" that can be tracked, those
1351     * opened by each of the following: openConglomerate(), openScan(), 
1352     * createSort(),  and openSort().  Scans opened by openSortScan() are 
1353     * tracked the same as those opened by openScan().  This routine can be
1354     * used to either report on the number of all opens, or may be used to
1355     * track one particular type of open.
1356     * <p>
1357     * This routine is expected to be used for debugging only.  An 
1358     * implementation may only track this info under SanityManager.DEBUG mode.
1359     * If the implementation does not track the info it will return -1 (so
1360     * code using this call to verify that no congloms are open should check
1361     * for return <= 0 rather than == 0).
1362     * <p>
1363     * The return value depends on the "which_to_count" parameter as follows:
1364     * <UL>
1365     * <LI>
1366     * OPEN_CONGLOMERATE  - return # of openConglomerate() calls not close()'d.
1367     * <LI>
1368     * OPEN_SCAN          - return # of openScan() + openSortScan() calls not
1369     *                      close()'d.
1370     * <LI>
1371     * OPEN_CREATED_SORTS - return # of sorts created (createSort()) in 
1372     *                      current xact.  There is currently no way to get
1373     *                      rid of these sorts before end of transaction.
1374     * <LI>
1375     * OPEN_SORT          - return # of openSort() calls not close()'d.
1376     * <LI>
1377     * OPEN_TOTAL         - return total # of all above calls not close()'d.
1378     * </UL>
1379     *     - note an implementation may return -1 if it does not track the
1380     *       above information.
1381     * <p>
1382     * @return The nunber of open's of a type indicated by "which_to_count"
1383     *         parameter.
1384     *
1385     * @param which_to_count Which kind of open to report on.
1386     *
1387     * @exception  StandardException  Standard exception policy.
1388     **/
1389    public int countOpens(int which_to_count)
1390        throws StandardException;
1391
1392
1393    /**
1394     * Return a string with debug information about opened congloms/scans/sorts.
1395     * <p>
1396     * Return a string with debugging information about current opened
1397     * congloms/scans/sorts which have not been close()'d.
1398     * Calls to this routine are only valid under code which is conditional
1399     * on SanityManager.DEBUG.
1400     * <p>
1401     *
1402     * @return String with debugging information.
1403     *
1404     * @exception  StandardException  Standard exception policy.
1405     **/
1406    public String   debugOpened() throws StandardException;
1407
1408
1409    /**
1410        Get an object to handle non-transactional files.
1411    */
1412    public FileResource getFileHandler();
1413
1414    /**
1415        Return an object that when used as the compatability space *and*
1416        group for a lock request, guarantees that the lock will be removed
1417        on a commit or an abort.
1418    */
1419    public Object   getLockObject();
1420
1421    /**
1422     * Return static information about the conglomerate to be included in a
1423     * a compiled plan.
1424     * <p>
1425     * The static info would be valid until any ddl was executed on the 
1426     * conglomid, and would be up to the caller to throw away when that 
1427     * happened.  This ties in with what language already does for other 
1428     * invalidation of static info.  The type of info in this would be 
1429     * containerid and array of format id's from which templates can be created.
1430     * The info in this object is read only and can be shared among as many 
1431     * threads as necessary.
1432     * <p>
1433     *
1434     * @return The static compiled information.
1435     *
1436     * @param conglomId The identifier of the conglomerate to open.
1437     *
1438     * @exception  StandardException  Standard exception policy.
1439     **/
1440    public StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo(
1441    long        conglomId)
1442        throws StandardException;
1443
1444    /**
1445     * Return dynamic information about the conglomerate to be dynamically 
1446     * reused in repeated execution of a statement.
1447     * <p>
1448     * The dynamic info is a set of variables to be used in a given 
1449     * ScanController or ConglomerateController.  It can only be used in one 
1450     * controller at a time.  It is up to the caller to insure the correct 
1451     * thread access to this info.  The type of info in this is a scratch 
1452     * template for btree traversal, other scratch variables for qualifier 
1453     * evaluation, ...
1454     * <p>
1455     *
1456     * @return The dynamic information.
1457     *
1458     * @param conglomId The identifier of the conglomerate to open.
1459     *
1460     * @exception  StandardException  Standard exception policy.
1461     **/
1462    public DynamicCompiledOpenConglomInfo getDynamicCompiledConglomInfo(
1463    long        conglomId)
1464        throws StandardException;
1465
1466    /**************************************************************************
1467     * Interfaces previously defined in TcCacheStatIface:
1468     **************************************************************************
1469     */
1470
1471    /**
1472        Get cache statistics for the specified cache
1473    */
1474    public long[] getCacheStats(String   cacheName);
1475
1476    /**
1477        Reset the cache statistics for the specified cache
1478    */
1479    public void resetCacheStats(String   cacheName);
1480
1481
1482    /**************************************************************************
1483     * Interfaces previously defined in TcLogIface:
1484     **************************************************************************
1485     */
1486    /**
1487    Log an operation and then action it in the context of this
1488    transaction.
1489
1490    <P>This simply passes the operation to the RawStore which logs and
1491    does it.
1492    
1493
1494    @param operation the operation that is to be applied
1495
1496    @see org.apache.derby.iapi.store.raw.Loggable
1497    @see org.apache.derby.iapi.store.raw.Transaction#logAndDo
1498    @exception StandardException  Standard cloudscape exception policy
1499    **/
1500    public void logAndDo(Loggable operation) throws StandardException;
1501
1502
1503    /**************************************************************************
1504     * Interfaces previously defined in TcSortIface:
1505     **************************************************************************
1506     */
1507
1508    /**
1509    Create a sort.  Rows are inserted into the sort with a
1510    sort controller, and subsequently retrieved with a
1511    sort scan controller. The rows come out in the order
1512    specified by the parameters.
1513    <p>
1514    Sorts also do aggregation. The input (unaggregated) rows
1515    have the same format as the aggregated rows, and the
1516    aggregate results are part of the both rows.  The sorter,
1517    when it notices that a row is a duplicate of another,
1518    calls a user-supplied aggregation method (see interface
1519    Aggregator), passing it both rows.  One row is known as
1520    the 'addend' and the other the 'accumulator'. The
1521    aggregation method is assumed to merge the addend
1522    into the accumulator. The sort then discards the addend
1523    row.
1524    <p>
1525    So, for the query:
1526    <pre><blockquote>
1527        select a, sum(b)
1528        from t
1529        group by a
1530    </blockquote></pre>
1531    The input row to the sorter would have one column for
1532    a and another column for sum(b).  It is up to the caller
1533    to get the format of the row correct, and to initialize
1534    the aggregate values correctly (null for most aggregates,
1535    0 for count).
1536    <p>
1537    Nulls are always considered to be ordered in a sort, that is,
1538    null compares equal to null, and less than anything else.
1539
1540    @param implParameters  Properties which help in choosing
1541    implementation-specific sort options.  If null, a
1542    "generally useful" sort will be used.
1543    
1544    @param template  A row which is prototypical for the sort.
1545    All rows inserted into the sort controller must have 
1546    exactly the same number of columns as the template row.
1547    Every column in an inserted row must have the same type
1548    as the corresponding column in the template.
1549
1550    @param columnOrdering  An array which specifies which columns
1551    participate in ordering - see interface ColumnOrdering for
1552    details.  The column referenced in the 0th columnOrdering
1553    object is compared first, then the 1st, etc.  To sort on a single
1554    column specify an array with a single entry.
1555
1556    @param sortObserver  An object that is used to observe
1557    the sort.  It is used to provide a callback into the sorter.
1558    If the sortObserver is null, then the sort proceeds as normal.
1559    If the sortObserver is non null, then it is called as 
1560    rows are loaded into the sorter.  It can be used to implement
1561    a distinct sort, aggregates, etc.
1562
1563    @param alreadyInOrder  Indicates that the rows inserted into
1564    the sort controller will already be in order.  This is used
1565    to perform aggregation only.
1566
1567    @param estimatedRows  The number of rows that the caller 
1568    estimates will be inserted into the sort.  -1 indicates that
1569    the caller has no idea.  Used by the sort to make good choices
1570    about in-memory vs. external sorting, and to size merge runs.
1571
1572    @param estimatedRowSize  The estimated average row size of the
1573    rows being sorted.  This is the client portion of the rowsize, it should
1574    not attempt to calculate Store's overhead.  -1 indicates that the caller
1575    has no idea (and the sorter will use 100 bytes in that case.  Used by the 
1576    sort to make good choices about in-memory vs. external sorting, and to size
1577    merge runs.  The client is not expected to estimate the per column/
1578    per row overhead of raw store, just to make a guess about the storage
1579    associated with each row (ie. reasonable estimates for some implementations
1580    would be 4 for int, 8 for long, 102 for char(100),
1581    202 for varchar(200), a number out of hat for user types, ...).
1582
1583    @return The sort identifier which can be used subsequently to
1584    open sort controllers and scans.
1585    
1586    @see SortObserver
1587    @see ColumnOrdering
1588    @see ScanController
1589    @see SortController
1590
1591    @exception StandardException From a lower-level exception.
1592    **/
1593    long createSort(
1594    Properties                implParameters,
1595    DataValueDescriptor[]   template,
1596    ColumnOrdering          columnOrdering[],
1597    SortObserver            sortObserver,
1598    boolean                 alreadyInOrder,
1599    long                    estimatedRows,
1600    int                     estimatedRowSize)
1601        throws StandardException;
1602    /**
1603    Drop a sort. 
1604    <p>
1605    Drop a sort created by a call to createSort() within the current 
1606    transaction (sorts are automatically "dropped" at the end of a 
1607    transaction.  This call should only be made after all openSortScan()'s
1608    and openSort()'s have been closed.
1609
1610    @param sortid The identifier of the sort to drop, as returned from 
1611                  createSort.
1612    <p>
1613    @exception StandardException From a lower-level exception.
1614    **/
1615    void dropSort(long sortid) throws StandardException;
1616
1617    /**
1618    Open a sort controller for a sort previously created in this
1619    transaction.  Sort controllers are used to insert rows into
1620    the sort.
1621    <p>
1622    There may (in the future) be multiple sort inserters
1623    for a given sort, the idea being that the various threads of
1624    a parallel query plan can all insert into the sort.  For now,
1625    however, only a single sort controller per sort is supported.
1626
1627    @param id The identifier of the sort to open, as returned from
1628    createSort.
1629
1630    @return A sort controller to use for inserting.
1631
1632    @exception StandardException From a lower-level exception.
1633    **/
1634    
1635    SortController openSort(long id)
1636        throws StandardException;
1637
1638    /**
1639     * Return an open SortCostController.
1640     * <p>
1641     * Return an open SortCostController which can be used to ask about 
1642     * the estimated costs of SortController() operations.
1643     * <p>
1644     * @param implParameters  Properties which help in choosing 
1645     *                        implementation-specific sort options.  If null, a
1646     *                        "generally useful" sort will be used.
1647     *
1648     * @return The open StoreCostController.
1649     *
1650     * @exception  StandardException  Standard exception policy.
1651     *
1652     * @see StoreCostController
1653     **/
1654    SortCostController openSortCostController(
1655    Properties    implParameters)
1656        throws StandardException;
1657
1658    /**
1659    Open a scan for retrieving rows from a sort.  Returns a RowSource for
1660    retrieving rows from the sort.
1661
1662    @param id  The identifier of the sort to scan, as returned
1663    from createSort.
1664
1665    @return The RowSource
1666
1667    @exception StandardException From a lower-level exception.
1668    **/
1669    RowLocationRetRowSource openSortRowSource(long id)
1670         throws StandardException;
1671
1672    /**
1673    Open a scan for retrieving rows from a sort.  Returns a
1674    scan controller for retrieving rows from the sort (NOTE:
1675    the only legal methods to use on the returned sort controller
1676    are next() and fetch() - probably there should be scan
1677    controllers and updatable scan controllers).
1678    <p>
1679    In the future, multiple sort scans on the same sort will
1680    be supported (for parallel execution across a uniqueness
1681    sort in which the order of the resulting rows is not
1682    important).  Currently, only a single sort scan is allowed
1683    per sort.
1684    <p>
1685    In the future, it will be possible to open a sort scan
1686    and start retrieving rows before the last row is inserted.
1687    The sort controller would block till rows were available
1688    to return.  Currently, an attempt to retrieve a row before
1689    the sort controller is closed will cause an exception.
1690
1691    @param id   The identifier of the sort to scan, as returned from createSort.
1692    @param hold If true, this scan will be maintained open over commits.
1693
1694    @return The sort controller.
1695
1696    @exception StandardException From a lower-level exception.
1697    **/
1698
1699    ScanController openSortScan(
1700    long    id,
1701    boolean hold)
1702        throws StandardException;
1703
1704
1705    /**************************************************************************
1706     * Interfaces previously defined in TcTransactionIface:
1707     **************************************************************************
1708     */
1709
1710    /**
1711    Return true if any transaction is blocked (even if not by this one).
1712
1713    */
1714    public boolean anyoneBlocked();
1715
1716    /**
1717    Abort all changes made by this transaction since the last commit, abort
1718    or the point the transaction was started, whichever is the most recent.
1719    All savepoints within this transaction are released, and all resources
1720    are released (held or non-held).
1721
1722    @exception StandardException Only exceptions with severities greater than
1723    ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
1724    **/
1725    public void abort()
1726        throws StandardException;
1727
1728    /**
1729    Commit this transaction.  All savepoints within this transaction are 
1730    released.  All non-held conglomerates and scans are closed.
1731
1732    @exception StandardException Only exceptions with severities greater than
1733    ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
1734    If an exception is thrown, the transaction will not (necessarily) have 
1735    been aborted.  The standard error handling mechanism is expected to do the 
1736    appropriate cleanup.  In other words, if commit() encounters an error, the 
1737    exception is propagated up to the the standard exception handler, which 
1738    initiates cleanupOnError() processing, which will eventually abort the 
1739    transaction.
1740    **/
1741    public void commit()
1742        throws StandardException;
1743
1744    /**
1745    "Commit" this transaction without sync'ing the log.  Everything else is
1746    identical to commit(), use this at your own risk.
1747
1748    <BR>bits in the commitflag can turn on to fine tuned the "commit":
1749    KEEP_LOCKS                          - no locks will be released by the 
1750                                          commit and no post commit processing 
1751                                          will be initiated.  If, for some 
1752                                          reasons, the locks cannot be kept 
1753                                          even if this flag is set, then the 
1754                                          commit will sync the log, i.e., it 
1755                                          will revert to the normal commit.
1756
1757    READONLY_TRANSACTION_INITIALIZATION - Special case used for processing
1758                                          while creating the transaction.  
1759                                          Should only be used by the system
1760                                          while creating the transaction to
1761                                          commit readonly work that may have
1762                                          been done using the transaction
1763                                          while getting it setup to be used
1764                                          by the user.  In the future we should
1765                                          instead use a separate tranaction to
1766                                          do this initialization.  Will fail
1767                                          if called on a transaction which
1768                                          has done any updates.
1769    @see TransactionController#commit
1770
1771    @exception StandardException Only exceptions with severities greater than
1772    ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
1773    If an exception is thrown, the transaction will not (necessarily) have 
1774    been aborted.  The standard error handling mechanism is expected to do the 
1775    appropriate cleanup.  In other words, if commit() encounters an error, the 
1776    exception is propagated up to the the standard exception handler, which 
1777    initiates cleanupOnError() processing, which will eventually abort the 
1778    transaction.
1779    **/
1780    public DatabaseInstant commitNoSync(int commitflag)
1781        throws StandardException;
1782
1783    public final int RELEASE_LOCKS                          = 0x1;
1784    public final int KEEP_LOCKS                             = 0x2;
1785    public final int READONLY_TRANSACTION_INITIALIZATION    = 0x4;
1786
1787    /**
1788    Abort the current transaction and pop the context.
1789    **/
1790    public void destroy();
1791
1792    /**
1793     * Get the context manager that the transaction was created with.
1794     * <p>
1795     *
1796     * @return The context manager that the transaction was created with.
1797     *
1798     **/
1799    public ContextManager getContextManager();
1800
1801    /**
1802     * Get string id of the transaction.
1803     * <p>
1804     * This transaction "name" will be the same id which is returned in
1805     * the TransactionInfo information, used by the lock and transaction
1806     * vti's to identify transactions.
1807     * <p>
1808     * Although implementation specific, the transaction id is usually a number
1809     * which is bumped every time a commit or abort is issued.
1810     * <p>
1811     *
1812     * @return The a string which identifies the transaction.  
1813     **/
1814    public String   getTransactionIdString();
1815
1816    /**
1817     * Get string id of the transaction that would be when the Transaction
1818     * is IN active state. This method increments the Tx id of  current Tx
1819     * object if it is in idle state. 
1820     * Note: Use this method only  getTransactionIdString() is not suitable.
1821     * @return The string which identifies the transaction.  
1822     **/
1823    public String   getActiveStateTxIdString();
1824    
1825
1826    /**
1827     * Reveals whether the transaction has ever read or written data.
1828     *
1829     * @return true If the transaction has never read or written data.
1830     **/
1831    boolean isIdle();
1832
1833    /**
1834     * Reveals whether the transaction is a global or local transaction.
1835     *
1836     * @return true If the transaction was either started by 
1837     *         AccessFactory.startXATransaction() or was morphed to a global
1838     *         transaction by calling createXATransactionFromLocalTransaction().
1839     * 
1840     * @see AccessFactory#startXATransaction
1841     * @see TransactionController#createXATransactionFromLocalTransaction
1842     *
1843     **/
1844    boolean isGlobal();
1845
1846    /**
1847     * Reveals whether the transaction is read only.
1848     *
1849     * @return true If the transaction is read only to this point.
1850     *
1851     **/
1852    boolean isPristine();
1853
1854    /**
1855    Release the save point of the given name. Releasing a savepoint removes all
1856    knowledge from this transaction of the named savepoint and any savepoints
1857    set since the named savepoint was set.
1858
1859    @param name     The user provided name of the savepoint, set by the user
1860                    in the setSavePoint() call.
1861      @param    kindOfSavepoint  A NULL value means it is an internal savepoint (ie not a user defined savepoint)
1862                    Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
1863                    A String value for kindOfSavepoint would mean it is SQL savepoint
1864                    A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
1865    @return returns savepoint position in the stack.
1866
1867    @exception StandardException  Standard cloudscape exception policy.  A 
1868                                  statement level exception is thrown if
1869                                  no savepoint exists with the given name.
1870    **/
1871    public int releaseSavePoint(String   name, Object   kindOfSavepoint) throws StandardException;
1872
1873    /**
1874    Rollback all changes made since the named savepoint was set. The named
1875    savepoint is not released, it remains valid within this transaction, and
1876    thus can be named it future rollbackToSavePoint() calls. Any savepoints
1877    set since this named savepoint are released (and their changes rolled back).
1878    <p>
1879    if "close_controllers" is true then all conglomerates and scans are closed
1880    (held or non-held).  
1881    <p>
1882    If "close_controllers" is false then no cleanup is done by the 
1883    TransactionController.  It is then the responsibility of the caller to
1884    close all resources that may have been affected by the statements 
1885    backed out by the call.  This option is meant to be used by the Language
1886    implementation of statement level backout, where the system "knows" what
1887    could be affected by the scope of the statements executed within the 
1888    statement.
1889    <p>
1890
1891    @param name               The identifier of the SavePoint to roll back to.
1892    @param close_controllers  boolean indicating whether or not the controller 
1893                              should close open controllers.
1894      @param    kindOfSavepoint  A NULL value means it is an internal savepoint (ie not a user defined savepoint)
1895      Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
1896      A String value for kindOfSavepoint would mean it is SQL savepoint
1897      A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
1898    @return returns savepoint position in the stack.
1899
1900    @exception StandardException  Standard cloudscape exception policy.  A 
1901                                  statement level exception is thrown if
1902                                  no savepoint exists with the given name.
1903    **/
1904    public int rollbackToSavePoint(
1905    String    name,
1906    boolean close_controllers, Object   kindOfSavepoint)
1907        throws StandardException;
1908
1909
1910    /**
1911    Set a save point in the current transaction. A save point defines a point in
1912    time in the transaction that changes can be rolled back to. Savepoints
1913    can be nested and they behave like a stack. Setting save points "one" and
1914    "two" and the rolling back "one" will rollback all the changes made since
1915    "one" (including those made since "two") and release savepoint "two".
1916
1917    @param name     The user provided name of the savepoint.
1918      @param    kindOfSavepoint  A NULL value means it is an internal savepoint (ie not a user defined savepoint)
1919      Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
1920      A String value for kindOfSavepoint would mean it is SQL savepoint
1921      A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
1922    @return returns savepoint position in the stack.
1923
1924    @exception StandardException  Standard cloudscape exception policy.  A 
1925                                  statement level exception is thrown if
1926                                  no savepoint exists with the given name.
1927    **/
1928    public int setSavePoint(String   name, Object   kindOfSavepoint) throws StandardException;
1929
1930    /**
1931     * Convert a local transaction to a global transaction.
1932     * <p>
1933     * Get a transaction controller with which to manipulate data within
1934     * the access manager.  Tbis controller allows one to manipulate a
1935     * global XA conforming transaction.
1936     * <p>
1937     * Must only be called a previous local transaction was created and exists
1938     * in the context.  Can only be called if the current transaction is in
1939     * the idle state.  Upon return from this call the old tc will be unusable,
1940     * and all references to it should be dropped (it will have been implicitly
1941     * destroy()'d by this call.
1942     * <p>
1943     * The (format_id, global_id, branch_id) triplet is meant to come exactly
1944     * from a javax.transaction.xa.Xid.  We don't use Xid so that the system
1945     * can be delivered on a non-1.2 vm system and not require the javax classes
1946     * in the path.  
1947     *
1948     * @param global_id the global transaction identifier part of XID - ie.
1949     *                  Xid.getGlobalTransactionId().
1950     * @param branch_id The branch qualifier of the Xid - ie. 
1951     *                  Xid.getBranchQaulifier()
1952     *  
1953     * @exception StandardException Standard exception policy.
1954     * @see TransactionController
1955     **/
1956    /* XATransactionController */ Object   createXATransactionFromLocalTransaction(
1957    int                     format_id,
1958    byte[]                  global_id,
1959    byte[]                  branch_id)
1960        throws StandardException;
1961
1962}
1963
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags