0001: /*
0002:
0003: Derby - Class org.apache.derby.iapi.store.access.TransactionController
0004:
0005: Licensed to the Apache Software Foundation (ASF) under one or more
0006: contributor license agreements. See the NOTICE file distributed with
0007: this work for additional information regarding copyright ownership.
0008: The ASF licenses this file to you under the Apache License, Version 2.0
0009: (the "License"); you may not use this file except in compliance with
0010: the License. You may obtain a copy of the License at
0011:
0012: http://www.apache.org/licenses/LICENSE-2.0
0013:
0014: Unless required by applicable law or agreed to in writing, software
0015: distributed under the License is distributed on an "AS IS" BASIS,
0016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0017: See the License for the specific language governing permissions and
0018: limitations under the License.
0019:
0020: */
0021:
0022: package org.apache.derby.iapi.store.access;
0023:
0024: import java.util.Properties;
0025:
0026: import java.io.Serializable;
0027:
0028: import org.apache.derby.iapi.services.context.ContextManager;
0029: import org.apache.derby.iapi.services.property.PersistentSet;
0030: import org.apache.derby.iapi.services.io.Storable;
0031:
0032: import org.apache.derby.iapi.error.StandardException;
0033:
0034: import org.apache.derby.iapi.store.raw.Loggable;
0035: import org.apache.derby.iapi.store.raw.Transaction;
0036:
0037: import org.apache.derby.iapi.types.DataValueDescriptor;
0038:
0039: import org.apache.derby.iapi.store.access.BackingStoreHashtable;
0040: import org.apache.derby.iapi.services.io.FormatableBitSet;
0041:
0042: import org.apache.derby.iapi.store.access.DatabaseInstant;
0043: import org.apache.derby.iapi.error.ExceptionSeverity;
0044:
0045: /**
0046:
0047: The TransactionController interface provides methods that an access client
0048: can use to control a transaction, which include the methods for
0049: gaining access to resources (conglomerates, scans, etc.) in the transaction
0050: controller's storage manager. TransactionControllers are obtained
0051: from an AccessFactory via the getTransaction method.
0052: <P>
0053: Each transaction controller is associated with a transaction context which
0054: provides error cleanup when standard exceptions are thrown anywhere in the
0055: system. The transaction context performs the following actions in response
0056: to cleanupOnError:
0057: <UL>
0058: <LI>
0059: If the error is an instance of StandardException that has a severity less
0060: than ExceptionSeverity.TRANSACTION_SEVERITY all resources remain unaffected.
0061: <LI>
0062: If the error is an instance of StandardException that has a severity equal
0063: to ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released. An attempt
0064: to use any resource obtained from this transaction controller after
0065: such an error will result in an error. The transaction controller itself remains
0066: valid, however.
0067: <LI>
0068: If the error is an instance of StandardException that has a severity greater
0069: than ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released and the
0070: context is popped from the stack. Attempting to use this controller or any
0071: resources obtained from it will result in an error.
0072: </UL>
0073: Transactions are obtained from an AccessFactory.
0074: @see AccessFactory#getTransaction
0075: @see org.apache.derby.iapi.error.StandardException
0076: @see PersistentSet
0077:
0078:
0079: **/
0080:
0081: public interface TransactionController extends PersistentSet {
0082:
0083: /**
0084: * Constant used for the lock_level argument to openConglomerate() and
0085: * openScan() calls. Pass in MODE_RECORD if you want the conglomerate
0086: * to be opened with record level locking (but the system may override
0087: * this choice and provide table level locking instead).
0088: **/
0089: static final int MODE_RECORD = 6;
0090: /**
0091: * Constant used for the lock_level argument to openConglomerate() and
0092: * openScan() calls. Pass in MODE_TABLE if you want the conglomerate
0093: * to be opened with table level locking - if this mode is passed in the
0094: * system will never use record level locking for the open scan or
0095: * controller.
0096: **/
0097: static final int MODE_TABLE = 7;
0098:
0099: /**
0100: * Constants used for the isolation_level argument to openConglomerate() and
0101: * openScan() calls.
0102: **/
0103:
0104: /**
0105: *
0106: * No locks are requested for data that is read only. Uncommitted data
0107: * may be returned. Writes only visible previous to commit.
0108: * Exclusive transaction length locks are set on data that is written, no
0109: * lock is set on data that is read. No table level intent lock is held
0110: * so it is up to caller to insure that table is not dropped while being
0111: * accessed (RESOLVE - this issue may need to be resolved differently if
0112: * we can't figure out a non-locked based way to prevent ddl during
0113: * read uncommitted access).
0114: *
0115: * ONLY USED INTERNALLY BY ACCESS, NOT VALID FOR EXTERNAL USERS.
0116: **/
0117: static final int ISOLATION_NOLOCK = 0;
0118:
0119: /**
0120: * No locks are requested for data that is read only. Uncommitted data
0121: * may be returned. Writes only visible previous to commit.
0122: * Exclusive transaction length locks are set on data that is written, no
0123: * lock is set on data that is read. No table level intent lock is held
0124: * so it is up to caller to insure that table is not dropped while being
0125: * accessed (RESOLVE - this issue may need to be resolved differently if
0126: * we can't figure out a non-locked based way to prevent ddl during
0127: * read uncommitted access).
0128: *
0129: * Note that this is currently only supported in heap scans.
0130: *
0131: * TODO - work in progress to support this locking mode in the 5.1
0132: * storage system.
0133: **/
0134: static final int ISOLATION_READ_UNCOMMITTED = 1;
0135:
0136: /**
0137: * No lost updates, no dirty reads, only committed data is returned.
0138: * Writes only visible when committed. Exclusive transaction
0139: * length locks are set on data that is written, short term locks (
0140: * possibly instantaneous duration locks) are set
0141: * on data that is read.
0142: **/
0143: static final int ISOLATION_READ_COMMITTED = 2;
0144:
0145: /**
0146: * No lost updates, no dirty reads, only committed data is returned.
0147: * Writes only visible when committed. Exclusive transaction
0148: * length locks are set on data that is written, short term locks (
0149: * possibly instantaneous duration locks) are set
0150: * on data that is read. Read locks are requested for "zero" duration,
0151: * thus upon return from access no read row lock is held.
0152: **/
0153: static final int ISOLATION_READ_COMMITTED_NOHOLDLOCK = 3;
0154:
0155: /**
0156: * Read and write locks are held until end of transaction, but no
0157: * phantom protection is performed (ie no previous key locking).
0158: * Writes only visible when committed.
0159: *
0160: * Note this constant is currently mapped to ISOLATION_SERIALIZABLE.
0161: * The constant is provided so that code which only requires repeatable
0162: * read can be coded with the right isolation level, and will just work when
0163: * store provided real repeatable read isolation.
0164: **/
0165: static final int ISOLATION_REPEATABLE_READ = 4;
0166:
0167: /**
0168: * Gray's isolation degree 3, "Serializable, Repeatable Read". Note that
0169: * some conglomerate implementations may only be able to provide
0170: * phantom protection under MODE_TABLE, while others can support this
0171: * under MODE_RECORD.
0172: **/
0173: static final int ISOLATION_SERIALIZABLE = 5;
0174:
0175: /**
0176: * Constants used for the flag argument to openConglomerate() and
0177: * openScan() calls.
0178: *
0179: * NOTE - The values of these constants must correspond to their associated
0180: * constants in
0181: * protocol.Database.Storage.RawStore.Interface.ContainerHandle, do not
0182: * add constants to this file without first adding there.
0183: **/
0184:
0185: /**
0186: * Use this mode to the openScan() call to indicate the scan should get
0187: * update locks during scan, and either promote the update locks to
0188: * exclusive locks if the row is changed or demote the lock if the row
0189: * is not updated. The lock demotion depends on the isolation level of
0190: * the scan. If isolation level is ISOLATION_SERIALIZABLE or
0191: * ISOLATION_REPEATABLE_READ
0192: * then the lock will be converted to a read lock. If the isolation level
0193: * ISOLATION_READ_COMMITTED then the lock is released when the scan moves
0194: * off the row.
0195: * <p>
0196: * Note that one must still set OPENMODE_FORUPDATE to be able to change
0197: * rows in the scan. So to enable update locks for an updating scan one
0198: * provides (OPENMODE_FORUPDATE | OPENMODE_USE_UPDATE_LOCKS)
0199: **/
0200: static final int OPENMODE_USE_UPDATE_LOCKS = 0x00001000;
0201:
0202: /**
0203: * Use this mode to the openConglomerate() call which opens the base
0204: * table to be used in a index to base row probe. This will cause
0205: * the openConglomerate() call to not get any row locks as part of
0206: * it's fetches.
0207: * It is important when using this mode that the secondary index table be
0208: * successfully opened before opening the base table so that
0209: * proper locking protocol is followed.
0210: **/
0211: static final int OPENMODE_SECONDARY_LOCKED = 0x00002000;
0212:
0213: /**
0214: * Use this mode to the openConglomerate() call used to open the
0215: * secondary indices of a table for inserting new rows in the table.
0216: * This will let the secondaryindex know that the base row being inserted
0217: * has already been locked and only previous key locks need be obtained.
0218: *
0219: * It is important when using this mode that the base table be
0220: * successfully opened before opening the secondaryindex so that
0221: * proper locking protocol is followed.
0222: **/
0223: static final int OPENMODE_BASEROW_INSERT_LOCKED = 0x00004000;
0224:
0225: /**
0226: * open table for update, if not specified table will be opened for read.
0227: **/
0228: static final int OPENMODE_FORUPDATE = 0x00000004;
0229:
0230: /**
0231: * Use this mode to the openConglomerate() call used to just get the
0232: * table lock on the conglomerate without actually doing anything else.
0233: * Any operations other than close() performed on the "opened" container
0234: * will fail.
0235: **/
0236: static final int OPENMODE_FOR_LOCK_ONLY = 0x00000040;
0237:
0238: /**
0239: * The table lock request will not wait.
0240: * <p>
0241: * The request to get the table lock (any table lock including intent or
0242: * "real" table level lock), will not wait if it can't be granted. A
0243: * lock timeout will be returned. Note that subsequent row locks will
0244: * wait if the application has not set a 0 timeout and if the call does
0245: * not have a wait parameter (like OpenConglomerate.fetch().
0246: **/
0247: static final int OPENMODE_LOCK_NOWAIT = 0x00000080;
0248:
0249: /**
0250: * Constants used for the countOpen() call.
0251: **/
0252: public static final int OPEN_CONGLOMERATE = 0x01;
0253: public static final int OPEN_SCAN = 0x02;
0254: public static final int OPEN_CREATED_SORTS = 0x03;
0255: public static final int OPEN_SORT = 0x04;
0256: public static final int OPEN_TOTAL = 0x05;
0257:
0258: static final byte IS_DEFAULT = (byte) 0x00; // initialize the flag
0259: static final byte IS_TEMPORARY = (byte) 0x01; // conglom is temporary
0260: static final byte IS_KEPT = (byte) 0x02; // no auto remove
0261:
0262: /**************************************************************************
0263: * Interfaces previously defined in TcAccessIface:
0264: **************************************************************************
0265: */
0266:
0267: /**
0268: Check whether a conglomerate exists.
0269:
0270: @param conglomId The identifier of the conglomerate to check for.
0271:
0272: @return true if the conglomerate exists, false otherwise.
0273:
0274: @exception StandardException only thrown if something goes
0275: wrong in the lower levels.
0276: **/
0277: boolean conglomerateExists(long conglomId) throws StandardException;
0278:
0279: /**
0280: Create a conglomerate.
0281: <p>
0282: Currently, only "heap"'s and ""btree secondary index"'s are supported,
0283: and all the features are not completely implemented.
0284: For now, create conglomerates like this:
0285: <p>
0286: <blockquote><pre>
0287: TransactionController tc;
0288: long conglomId = tc.createConglomerate(
0289: "heap", // we're requesting a heap conglomerate
0290: template, // a populated template is required for heap and btree.
0291: null, // default properties
0292: 0); // not temporary
0293: </blockquote></pre>
0294:
0295: Each implementation of a conglomerate takes a possibly different set
0296: of properties. The "heap" implementation currently takes no properties.
0297:
0298: The "btree secondary index" requires the following set of properties:
0299: <UL>
0300: <LI> "baseConglomerateId" (integer). The conglomerate id of the base
0301: conglomerate is never actually accessed by the b-tree secondary
0302: index implementation, it only serves as a namespace for row locks.
0303: This property is required.
0304: <LI> "rowLocationColumn" (integer). The zero-based index into the row which
0305: the b-tree secondary index will assume holds a @see RowLocation of
0306: the base row in the base conglomerate. This value will be used
0307: for acquiring locks. In this implementation RowLocationColumn must be
0308: the last key column.
0309: This property is required.
0310: <LI>"allowDuplicates" (boolean). If set to true the table will allow
0311: rows which are duplicate in key column's 0 through (nUniqueColumns - 1).
0312: Currently only supports "false".
0313: This property is optional, defaults to false.
0314: <LI>"nKeyFields" (integer) Columns 0 through (nKeyFields - 1) will be
0315: included in key of the conglomerate.
0316: This implementation requires that "nKeyFields" must be the same as the
0317: number of fields in the conglomerate, including the rowLocationColumn.
0318: Other implementations may relax this restriction to allow non-key fields
0319: in the index.
0320: This property is required.
0321: <LI>"nUniqueColumns" (integer) Columns 0 through "nUniqueColumns" will be
0322: used to check for uniqueness. So for a standard SQL non-unique index
0323: implementation set "nUniqueColumns" to the same value as "nKeyFields"; and
0324: for a unique index set "nUniqueColumns" to "nKeyFields - 1 (ie. don't
0325: include the rowLocationColumn in the uniqueness check).
0326: This property is required.
0327: <LI>"maintainParentLinks" (boolean)
0328: Whether the b-tree pages maintain the page number of their parent. Only
0329: used for consistency checking. It takes a certain amount more effort to
0330: maintain these links, but they're really handy for ensuring that the index
0331: is consistent.
0332: This property is optional, defaults to true.
0333: </UL>
0334:
0335: A secondary index i (a, b) on table t (a, b, c) would have rows
0336: which looked like (a, b, row_location). baseConglomerateId is set to the
0337: conglomerate id of t. rowLocationColumns is set to 2. allowsDuplicates
0338: would be set to false. To create a unique
0339: secondary index set uniquenessColumns to 2, this means that the btree
0340: code will compare the key values but not the row id when determing
0341: uniqueness. To create a nonunique secondary index set uniquenessColumns
0342: to 3, this would mean that the uniqueness test would include the row
0343: location and since all row locations will be unique all rows inserted
0344: into the index will be differentiated (at least) by row location.
0345:
0346: @return The identifier to be used to open the conglomerate later.
0347:
0348: @param implementation Specifies what kind of conglomerate to create.
0349: THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.
0350: For now, use "BTREE" or "heap" for a local access manager.
0351:
0352: @param template A row which describes the prototypical
0353: row that the conglomerate will be holding.
0354: Typically this row gives the conglomerate
0355: information about the number and type of
0356: columns it will be holding. The implementation
0357: may require a specific subclass of row type.
0358: Note that the createConglomerate call reads the template and makes a copy
0359: of any necessary information from the template, no reference to the
0360: template is kept (and thus this template can be re-used in subsequent
0361: calls - such as openScan()). This field is required when creating either
0362: a heap or btree conglomerate.
0363:
0364: @param columnOrder Specifies the colummns sort order.
0365: Useful only when the conglomerate is of type BTREE, default
0366: value is 'null', which means all columns needs to be sorted in
0367: Ascending order.
0368:
0369:
0370: @param properties Implementation-specific properties of the
0371: conglomerate.
0372:
0373: @param temporaryFlag
0374: Where temporaryFlag can have the following values:
0375: IS_DEFAULT - no bit is set.
0376: IS_TEMPORARY - if set, the conglomerate is temporary
0377: IS_KEPT - only looked at if IS_TEMPORARY,
0378: if set, the temporary container is not
0379: removed automatically by store when
0380: transaction terminates.
0381:
0382: If IS_TEMPORARY is set, the conglomerate is temporary.
0383: Temporary conglomerates are only visible through the transaction
0384: controller that created them. Otherwise, they are opened,
0385: scanned, and dropped in the same way as permanent conglomerates.
0386: Changes to temporary conglomerates persist across commits, but
0387: temporary conglomerates are truncated on abort (or rollback
0388: to savepoint). Updates to temporary conglomerates are not
0389: locked or logged.
0390:
0391: A temporary conglomerate is only visible to the transaction
0392: controller that created it, even if the conglomerate IS_KEPT
0393: when the transaction termination.
0394:
0395: All temporary conglomerate is removed by store when the
0396: conglomerate controller is destroyed, or if it is dropped by an explicit
0397: dropConglomerate. If cloudscape reboots, all temporary
0398: conglomerates are removed.
0399:
0400: @exception StandardException if the conglomerate could
0401: not be created for some reason.
0402: **/
0403: long createConglomerate(String implementation,
0404: DataValueDescriptor[] template,
0405: ColumnOrdering[] columnOrder, Properties properties,
0406: int temporaryFlag) throws StandardException;
0407:
0408: /**
0409: Create a conglomerate and load (filled) it with rows that comes from the
0410: row source without loggging.
0411:
0412: <p>Individual rows that are loaded into the conglomerate are not
0413: logged. After this operation, the underlying database must be backed up
0414: with a database backup rather than an transaction log backup (when we have
0415: them). This warning is put here for the benefit of future generation.
0416:
0417: <p>
0418: This function behaves the same as @see createConglomerate except it also
0419: populates the conglomerate with rows from the row source and the rows that
0420: are inserted are not logged.
0421:
0422: @param implementation Specifies what kind of conglomerate to create.
0423: THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.
0424: For now, use "BTREE" or "heap" for a local access manager.
0425:
0426: @param rowSource the interface to recieve rows to load into the
0427: conglomerate.
0428:
0429: @param rowCount - if not null the number of rows loaded into the table
0430: will be returned as the first element of the array.
0431:
0432: @exception StandardException if the conglomerate could not be created or
0433: loaded for some reason. Throws
0434: SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION if
0435: the conglomerate supports uniqueness checks and has been created to
0436: disallow duplicates, and one of the rows being loaded had key columns which
0437: were duplicate of a row already in the conglomerate.
0438: **/
0439: long createAndLoadConglomerate(String implementation,
0440: DataValueDescriptor[] template,
0441: ColumnOrdering[] columnOrder, Properties properties,
0442: int temporaryFlag, RowLocationRetRowSource rowSource,
0443: long[] rowCount) throws StandardException;
0444:
0445: /**
0446: Recreate a conglomerate and possibly load it with new rows that come from
0447: the new row source.
0448:
0449: <p>
0450: This function behaves the same as @see createConglomerate except it also
0451: populates the conglomerate with rows from the row source and the rows that
0452: are inserted are not logged.
0453:
0454: <p>Individual rows that are loaded into the conglomerate are not
0455: logged. After this operation, the underlying database must be backed up
0456: with a database backup rather than an transaction log backup (when we have
0457: them). This warning is put here for the benefit of future generation.
0458:
0459: @param implementation Specifies what kind of conglomerate to create.
0460: THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.
0461: For now, use "BTREE" or "heap" for a local access manager.
0462:
0463: @param recreate_ifempty If false, and the rowsource used to load the new
0464: conglomerate returns no rows, then the original
0465: conglomid will be returned. To the client it will
0466: be as if no call was made. Underlying
0467: implementations may actually create and drop a
0468: container.
0469: If true, then a new empty container will be
0470: created and it's conglomid will be returned.
0471:
0472: @param template A row which describes the prototypical
0473: row that the conglomerate will be holding.
0474: Typically this row gives the conglomerate
0475: information about the number and type of
0476: columns it will be holding. The implementation
0477: may require a specific subclass of row type.
0478: Note that the createConglomerate call reads the template and makes a copy
0479: of any necessary information from the template, no reference to the
0480: template is kept (and thus this template can be re-used in subsequent
0481: calls - such as openScan()). This field is required when creating either
0482: a heap or btree conglomerate.
0483:
0484: @param columnOrder Specifies the colummns sort order.
0485: Useful only when the conglomerate is of type BTREE, default
0486: value is 'null', which means all columns needs to be sorted in
0487: Ascending order.
0488:
0489: @param properties Implementation-specific properties of the conglomerate.
0490:
0491: @param temporaryFlag If true, the conglomerate is temporary.
0492: Temporary conglomerates are only visible through the transaction
0493: controller that created them. Otherwise, they are opened,
0494: scanned, and dropped in the same way as permanent conglomerates.
0495: Changes to temporary conglomerates persist across commits, but
0496: temporary conglomerates are truncated on abort (or rollback
0497: to savepoint). Updates to temporary conglomerates are not
0498: locked or logged.
0499:
0500: @param orig_conglomId The conglomid of the original conglomerate.
0501:
0502: @param rowSource interface to receive rows to load into the conglomerate.
0503:
0504: @param rowCount - if not null the number of rows loaded into the table
0505: will be returned as the first element of the array.
0506:
0507: @exception StandardException if the conglomerate could not be created or
0508: loaded for some reason. Throws
0509: SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION if
0510: the conglomerate supports uniqueness checks and has been created to
0511: disallow duplicates, and one of the rows being loaded had key columns which
0512: were duplicate of a row already in the conglomerate.
0513: **/
0514: long recreateAndLoadConglomerate(String implementation,
0515: boolean recreate_ifempty, DataValueDescriptor[] template,
0516: ColumnOrdering[] columnOrder, Properties properties,
0517: int temporaryFlag, long orig_conglomId,
0518: RowLocationRetRowSource rowSource, long[] rowCount)
0519: throws StandardException;
0520:
0521: /**
0522: Add a column to a conglomerate.
0523:
0524: The Storage system will block this action until it can get an exclusive
0525: container level lock on the conglomerate. The conglomerate must not be
0526: open in the current transaction, this means that within the current
0527: transaction there must be no open ConglomerateController's or
0528: ScanControllers. It may not be possible in some implementations of the
0529: system to catch this error in the store, so it is up to the caller to
0530: insure this.
0531:
0532: The column can only be added at the spot just after the current set of
0533: columns.
0534:
0535: The template_column must be nullable.
0536:
0537: After this call has been made, all fetches of this column from rows that
0538: existed in the table prior to this call will return "null".
0539:
0540: @param conglomId The identifier of the conglomerate to alter.
0541: @param column_id The column number to add this column at.
0542: @param template_column An instance of the column to be added to table.
0543:
0544: @exception StandardException Only some types of conglomerates can support
0545: adding a column, for instance "heap" conglomerates support adding a
0546: column while "btree" conglomerates do not. If the column can not be
0547: added an exception will be thrown.
0548: **/
0549: public void addColumnToConglomerate(long conglomId, int column_id,
0550: Storable template_column) throws StandardException;
0551:
0552: /**
0553: Drop a conglomerate. The conglomerate must not be open in
0554: the current transaction. This also means that there must
0555: not be any active scans on it.
0556:
0557: @param conglomId The identifier of the conglomerate to drop.
0558:
0559: @exception StandardException if the conglomerate could not be
0560: dropped for some reason.
0561: **/
0562: void dropConglomerate(long conglomId) throws StandardException;
0563:
0564: /**
0565: * For debugging, find the conglomid given the containerid.
0566: * <p>
0567: *
0568: * @return the conglomid, which contains the container with containerid.
0569: *
0570: * @exception StandardException Standard exception policy.
0571: **/
0572: long findConglomid(long containerid) throws StandardException;
0573:
0574: /**
0575: * For debugging, find the containerid given the conglomid.
0576: * <p>
0577: * Will have to change if we ever have more than one container in
0578: * a conglomerate.
0579: *
0580: * @return the containerid of container implementing conglomerate with
0581: * "conglomid."
0582: *
0583: * @exception StandardException Standard exception policy.
0584: **/
0585: long findContainerid(long conglomid) throws StandardException;
0586:
0587: /**
0588: * Get an nested user transaction.
0589: * <p>
0590: * A nested user transaction can be used exactly as any other
0591: * TransactionController, except as follows. For this discussion let the
0592: * parent transaction be the transaction used to make the
0593: * startNestedUserTransaction() call, and let the child transaction be the
0594: * transaction returned by the startNestedUserTransaction() call.
0595: * <p>
0596: * Only 1 non-readOnly nested user transaction can exist. If a subsequent
0597: * non-readOnly transaction creation is attempted prior to destroying an
0598: * existing write nested user transaction an exception will be thrown.
0599: * <p>
0600: * The nesting is limited to one level deep. An exception will be thrown
0601: * if a subsequent getNestedUserTransaction() is called on the child
0602: * transaction.
0603: * <p>
0604: * The locks in the child transaction of a readOnly nested user transaction
0605: * will be compatible with the locks of the parent transaction. The
0606: * locks in the child transaction of a non-readOnly nested user transaction
0607: * will NOT be compatible with those of the parent transaction - this is
0608: * necessary for correct recovery behavior.
0609: * <p>
0610: * A commit in the child transaction will release locks associated with
0611: * the child transaction only, work can continue in the parent transaction
0612: * at this point.
0613: * <p>
0614: * Any abort of the child transaction will result in an abort of both
0615: * the child transaction and parent transaction, either initiated by
0616: * an explict abort() call or by an exception that results in an abort.
0617: * <p>
0618: * A TransactionController.destroy() call should be made on the child
0619: * transaction once all child work is done, and the caller wishes to
0620: * continue work in the parent transaction.
0621: * <p>
0622: * AccessFactory.getTransaction() will always return the "parent"
0623: * transaction, never the child transaction. Thus clients using
0624: * nested user transactions must keep track of the transaction, as there
0625: * is no interface to query the storage system to get the current
0626: * child transaction. The idea is that a nested user transaction should
0627: * be used to for a limited amount of work, committed, and then work
0628: * continues in the parent transaction.
0629: * <p>
0630: * Nested User transactions are meant to be used to implement
0631: * system work necessary to commit as part of implementing a user's
0632: * request, but where holding the lock for the duration of the user
0633: * transaction is not acceptable. 2 examples of this are system catalog
0634: * read locks accumulated while compiling a plan, and auto-increment.
0635: * <p>
0636: * Once the first write of a non-readOnly nested transaction is done,
0637: * then the nested user transaction must be committed or aborted before
0638: * any write operation is attempted in the parent transaction.
0639: *
0640: * @param readOnly Is transaction readonly? Only 1 non-readonly nested
0641: * transaction is allowed per transaction.
0642: *
0643: * @return The new nested user transaction.
0644: *
0645: * @exception StandardException Standard exception policy.
0646: **/
0647: public TransactionController startNestedUserTransaction(
0648: boolean readOnly) throws StandardException;
0649:
0650: /**
0651: * A superset of properties that "users" can specify.
0652: * <p>
0653: * A superset of properties that "users" (ie. from sql) can specify. Store
0654: * may implement other properties which should not be specified by users.
0655: * Layers above access may implement properties which are not known at
0656: * all to Access.
0657: * <p>
0658: * This list is a superset, as some properties may not be implemented by
0659: * certain types of conglomerates. For instant an in-memory store may not
0660: * implement a pageSize property. Or some conglomerates may not support
0661: * pre-allocation.
0662: * <p>
0663: * This interface is meant to be used by the SQL parser to do validation
0664: * of properties passsed to the create table statement, and also by the
0665: * various user interfaces which present table information back to the
0666: * user.
0667: * <p>
0668: * Currently this routine returns the following list:
0669: * derby.storage.initialPages
0670: * derby.storage.minimumRecordSize
0671: * derby.storage.pageReservedSpace
0672: * derby.storage.pageSize
0673: *
0674: * @return The superset of properties that "users" can specify.
0675: *
0676: **/
0677: Properties getUserCreateConglomPropList();
0678:
0679: /**
0680: * Open a conglomerate for use.
0681: * <p>
0682: * The lock level indicates the minimum lock level to get locks at, the
0683: * underlying conglomerate implementation may actually lock at a higher
0684: * level (ie. caller may request MODE_RECORD, but the table may be locked
0685: * at MODE_TABLE instead).
0686: * <p>
0687: * The close method is on the ConglomerateController interface.
0688: *
0689: * @return a ConglomerateController to manipulate the conglomerate.
0690: *
0691: * @param conglomId The identifier of the conglomerate to open.
0692: *
0693: * @param hold If true, will be maintained open over commits.
0694: *
0695: * @param open_mode Specifiy flags to control opening of table.
0696: * OPENMODE_FORUPDATE - if set open the table for
0697: * update otherwise open table shared.
0698: *
0699: * @param lock_level One of (MODE_TABLE, MODE_RECORD).
0700: *
0701: * @param isolation_level The isolation level to lock the conglomerate at.
0702: * One of (ISOLATION_READ_COMMITTED,
0703: * ISOLATION_REPEATABLE_READ or
0704: * ISOLATION_SERIALIZABLE).
0705: *
0706: * @exception StandardException if the conglomerate could not be opened
0707: * for some reason. Throws
0708: * SQLState.STORE_CONGLOMERATE_DOES_NOT_EXIST
0709: * if the conglomId being requested does not
0710: * exist for some reason (ie. someone has
0711: * dropped it).
0712: **/
0713: ConglomerateController openConglomerate(long conglomId,
0714: boolean hold, int open_mode, int lock_level,
0715: int isolation_level) throws StandardException;
0716:
0717: /**
0718: * Open a conglomerate for use, optionally include "compiled" info.
0719: * <p>
0720: * Same as openConglomerate(), except that one can optionally provide
0721: * "compiled" static_info and/or dynamic_info. This compiled information
0722: * must have be gotten from getDynamicCompiledConglomInfo() and/or
0723: * getStaticCompiledConglomInfo() calls on the same conglomid being opened.
0724: * It is up to caller that "compiled" information is still valid and
0725: * is appropriately multi-threaded protected.
0726: * <p>
0727: *
0728: * @see TransactionController#openConglomerate
0729: * @see TransactionController#getDynamicCompiledConglomInfo
0730: * @see TransactionController#getStaticCompiledConglomInfo
0731: * @see DynamicCompiledOpenConglomInfo
0732: * @see StaticCompiledOpenConglomInfo
0733: *
0734: * @return The identifier to be used to open the conglomerate later.
0735: *
0736: * @param hold If true, will be maintained open over commits.
0737: * @param open_mode Specifiy flags to control opening of table.
0738: * @param lock_level One of (MODE_TABLE, MODE_RECORD).
0739: * @param isolation_level The isolation level to lock the conglomerate at.
0740: * One of (ISOLATION_READ_COMMITTED,
0741: * ISOLATION_REPEATABLE_READ or
0742: * ISOLATION_SERIALIZABLE).
0743: * @param static_info object returned from
0744: * getStaticCompiledConglomInfo() call on this id.
0745: * @param dynamic_info object returned from
0746: * getDynamicCompiledConglomInfo() call on this id.
0747: *
0748: * @exception StandardException Standard exception policy.
0749: **/
0750: ConglomerateController openCompiledConglomerate(boolean hold,
0751: int open_mode, int lock_level, int isolation_level,
0752: StaticCompiledOpenConglomInfo static_info,
0753: DynamicCompiledOpenConglomInfo dynamic_info)
0754: throws StandardException;
0755:
0756: /**
0757: * Create a HashSet which contains all rows that qualify for the
0758: * described scan.
0759: * <p>
0760: * All parameters shared between openScan() and this routine are
0761: * interpreted exactly the same. Logically this routine calls
0762: * openScan() with the passed in set of parameters, and then places
0763: * all returned rows into a newly created HashSet and returns, actual
0764: * implementations will likely perform better than actually calling
0765: * openScan() and doing this. For documentation of the openScan
0766: * parameters see openScan().
0767: * <p>
0768: *
0769: * @return the BackingStoreHashtable which was created.
0770: *
0771: * @param conglomId see openScan()
0772: * @param open_mode see openScan()
0773: * @param lock_level see openScan()
0774: * @param isolation_level see openScan()
0775: * @param scanColumnList see openScan()
0776: * @param startKeyValue see openScan()
0777: * @param startSearchOperator see openScan()
0778: * @param qualifier see openScan()
0779: * @param stopKeyValue see openScan()
0780: * @param stopSearchOperator see openScan()
0781: *
0782: * @param max_rowcnt The maximum number of rows to insert into
0783: * the HashSet. Pass in -1 if there is no
0784: * maximum.
0785: * @param key_column_numbers The column numbers of the columns in the
0786: * scan result row to be the key to the
0787: * Hashtable. "0" is the first column in the
0788: * scan result row (which may be different
0789: * than the first row in the table of the
0790: * scan).
0791: * @param remove_duplicates Should the HashSet automatically remove
0792: * duplicates, or should it create the Vector
0793: * of duplicates?
0794: * @param estimated_rowcnt The number of rows that the caller
0795: * estimates will be inserted into the sort.
0796: * -1 indicates that the caller has no idea.
0797: * Used by the sort to make good choices about
0798: * in-memory vs. external sorting, and to size
0799: * merge runs.
0800: * @param max_inmemory_rowcnt The number of rows at which the underlying
0801: * Hashtable implementation should cut over
0802: * from an in-memory hash to a disk based
0803: * access method.
0804: * @param initialCapacity If not "-1" used to initialize the java
0805: * Hashtable.
0806: * @param loadFactor If not "-1" used to initialize the java
0807: * Hashtable.
0808: * @param collect_runtimestats If true will collect up runtime stats during
0809: * scan processing for retrieval by
0810: * BackingStoreHashtable.getRuntimeStats().
0811: * @param skipNullKeyColumns Whether or not to skip rows with 1 or more null key columns
0812: *
0813: * @see BackingStoreHashtable
0814: * @see TransactionController#openScan
0815: *
0816: * @exception StandardException Standard exception policy.
0817: **/
0818: BackingStoreHashtable createBackingStoreHashtableFromScan(
0819: long conglomId, int open_mode, int lock_level,
0820: int isolation_level, FormatableBitSet scanColumnList,
0821: DataValueDescriptor[] startKeyValue,
0822: int startSearchOperator, Qualifier qualifier[][],
0823: DataValueDescriptor[] stopKeyValue, int stopSearchOperator,
0824: long max_rowcnt, int[] key_column_numbers,
0825: boolean remove_duplicates, long estimated_rowcnt,
0826: long max_inmemory_rowcnt, int initialCapacity,
0827: float loadFactor, boolean collect_runtimestats,
0828: boolean skipNullKeyColumns) throws StandardException;
0829:
0830: /**
0831: Open a scan on a conglomerate. The scan will return all
0832: rows in the conglomerate which are between the
0833: positions defined by {startKeyValue, startSearchOperator} and
0834: {stopKeyValue, stopSearchOperator}, which also match the qualifier.
0835: <P>
0836: The way that starting and stopping keys and operators are used
0837: may best be described by example. Say there's an ordered conglomerate
0838: with two columns, where the 0-th column is named 'x', and the 1st
0839: column is named 'y'. The values of the columns are as follows:
0840: <blockquote><pre>
0841: x: 1 3 4 4 4 5 5 5 6 7 9
0842: y: 1 1 2 4 6 2 4 6 1 1 1
0843: </blockquote></pre>
0844: <P>
0845: A {start key, search op} pair of {{5.2}, GE} would position on
0846: {x=5, y=2}, whereas the pair {{5}, GT} would position on {x=6, y=1}.
0847: <P>
0848: Partial keys are used to implement partial key scans in SQL.
0849: For example, the SQL "select * from t where x = 5" would
0850: open a scan on the conglomerate (or a useful index) of t
0851: using a starting position partial key of {{5}, GE} and
0852: a stopping position partial key of {{5}, GT}.
0853: <P>
0854: Some more examples:
0855: <p>
0856: <blockquote><pre>
0857: +-------------------+------------+-----------+--------------+--------------+
0858: | predicate | start key | stop key | rows | rows locked |
0859: | | value | op | value |op | returned |serialization |
0860: +-------------------+-------+----+-------+---+--------------+--------------+
0861: | x = 5 | {5} | GE | {5} |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
0862: | x > 5 | {5} | GT | null | |{6,1} .. {9,1}|{5,6} .. {9,1}|
0863: | x >= 5 | {5} | GE | null | |{5,2} .. {9,1}|{4,6} .. {9,1}|
0864: | x <= 5 | null | | {5} |GT |{1,1} .. {5,6}|first .. {5,6}|
0865: | x < 5 | null | | {5} |GE |{1,1} .. {4,6}|first .. {4,6}|
0866: | x >= 5 and x <= 7 | {5}, | GE | {7} |GT |{5,2} .. {7,1}|{4,6} .. {7,1}|
0867: | x = 5 and y > 2 | {5,2} | GT | {5} |GT |{5,4} .. {5,6}|{5,2} .. {5,6}|
0868: | x = 5 and y >= 2 | {5,2} | GE | {5} |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
0869: | x = 5 and y < 5 | {5} | GE | {5,5} |GE |{5,2} .. {5,4}|{4,6} .. {5,4}|
0870: | x = 2 | {2} | GE | {2} |GT | none |{1,1} .. {1,1}|
0871: +-------------------+-------+----+-------+---+--------------+--------------+
0872: </blockquote></pre>
0873: <P>
0874: As the above table implies, the underlying scan may lock
0875: more rows than it returns in order to guarantee serialization.
0876: <P>
0877: For each row which meets the start and stop position, as described above
0878: the row is "qualified" to see whether it should be returned. The
0879: qualification is a 2 dimensional array of @see Qualifiers, which represents
0880: the qualification in conjunctive normal form (CNF). Conjunctive normal
0881: form is an "and'd" set of "or'd" Qualifiers.
0882: <P>
0883: For example x = 5 would be represented is pseudo code as:
0884:
0885: qualifier_cnf[][] = new Qualifier[1];
0886: qualifier_cnf[0] = new Qualifier[1];
0887:
0888: qualifier_cnr[0][0] = new Qualifer(x = 5)
0889:
0890: <P>
0891: For example (x = 5) or (y = 6) would be represented is pseudo code as:
0892:
0893: qualifier_cnf[][] = new Qualifier[1];
0894: qualifier_cnf[0] = new Qualifier[2];
0895:
0896: qualifier_cnr[0][0] = new Qualifer(x = 5)
0897: qualifier_cnr[0][1] = new Qualifer(y = 6)
0898:
0899: <P>
0900: For example ((x = 5) or (x = 6)) and ((y = 1) or (y = 2)) would be
0901: represented is pseudo code as:
0902:
0903: qualifier_cnf[][] = new Qualifier[2];
0904: qualifier_cnf[0] = new Qualifier[2];
0905:
0906: qualifier_cnr[0][0] = new Qualifer(x = 5)
0907: qualifier_cnr[0][1] = new Qualifer(x = 6)
0908:
0909: qualifier_cnr[0][0] = new Qualifer(y = 5)
0910: qualifier_cnr[0][1] = new Qualifer(y = 6)
0911:
0912: <P>
0913: For each row the CNF qualfier is processed and it is determined whether
0914: or not the row should be returned to the caller.
0915:
0916: The following pseudo-code describes how this is done:
0917:
0918: <blockquote><pre>
0919: if (qualifier != null)
0920: {
0921: <blockquote><pre>
0922: for (int and_clause; and_clause < qualifier.length; and_clause++)
0923: {
0924: boolean or_qualifies = false;
0925:
0926: for (int or_clause; or_clause < qualifier[and_clause].length; or_clause++)
0927: {
0928: <blockquote><pre>
0929: DataValueDescriptor key =
0930: qualifier[and_clause][or_clause].getOrderable();
0931:
0932: DataValueDescriptor row_col =
0933: get row column[qualifier[and_clause][or_clause].getColumnId()];
0934:
0935: boolean or_qualifies =
0936: row_col.compare(qualifier[i].getOperator,
0937: <blockquote><pre>
0938: key,
0939: qualifier[i].getOrderedNulls,
0940: qualifier[i].getUnknownRV);
0941: </blockquote></pre>
0942:
0943: if (or_qualifies)
0944: {
0945: break;
0946: }
0947: }
0948:
0949: if (!or_qualifies)
0950: {
0951: <blockquote><pre>
0952: don't return this row to the client - proceed to next row;
0953: </blockquote></pre>
0954: }
0955: </blockquote></pre>
0956:
0957: }
0958: </blockquote></pre>
0959: }
0960: </blockquote></pre>
0961:
0962:
0963: @param conglomId The identifier of the conglomerate
0964: to open the scan for.
0965:
0966: @param hold If true, this scan will be maintained open over
0967: commits.
0968:
0969: @param open_mode Specifiy flags to control opening of table.
0970: OPENMODE_FORUPDATE - if set open the table for
0971: update otherwise open table shared.
0972:
0973: @param lock_level One of (MODE_TABLE, MODE_RECORD).
0974:
0975: @param isolation_level The isolation level to lock the conglomerate at.
0976: One of (ISOLATION_READ_COMMITTED,
0977: ISOLATION_REPEATABLE_READ or
0978: ISOLATION_SERIALIZABLE).
0979:
0980: @param scanColumnList A description of which columns to return from
0981: every fetch in the scan. template, and scanColumnList
0982: work together to describe the row to be returned by the scan - see RowUtil
0983: for description of how these three parameters work together to describe
0984: a "row".
0985:
0986: @param startKeyValue An indexable row which holds a
0987: (partial) key value which, in combination with the
0988: startSearchOperator, defines the starting position of
0989: the scan. If null, the starting position of the scan
0990: is the first row of the conglomerate.
0991: The startKeyValue must only reference columns included
0992: in the scanColumnList.
0993:
0994: @param startSearchOperator an operator which defines
0995: how the startKeyValue is to be searched for. If
0996: startSearchOperation is ScanController.GE, the scan starts on
0997: the first row which is greater than or equal to the
0998: startKeyValue. If startSearchOperation is ScanController.GT,
0999: the scan starts on the first row whose key is greater than
1000: startKeyValue. The startSearchOperation parameter is
1001: ignored if the startKeyValue parameter is null.
1002:
1003: @param qualifier A 2 dimensional array encoding a conjunctive normal
1004: form (CNF) datastructure of of qualifiers which, applied
1005: to each key, restrict the rows returned by the scan. Rows
1006: for which the CNF expression returns false are not
1007: returned by the scan. If null, all rows are returned.
1008: Qualifiers can only reference columns which are included in the
1009: scanColumnList. The column id that a qualifier returns is the
1010: column id the table, not the column id in the partial row being
1011: returned.
1012:
1013: For detailed description of 2-dimensional array passing @see Qualifier
1014:
1015: @param stopKeyValue An indexable row which holds a
1016: (partial) key value which, in combination with the
1017: stopSearchOperator, defines the ending position of
1018: the scan. If null, the ending position of the scan
1019: is the last row of the conglomerate.
1020: The stopKeyValue must only reference columns included
1021: in the scanColumnList.
1022:
1023: @param stopSearchOperator an operator which defines
1024: how the stopKeyValue is used to determine the scan stopping
1025: position. If stopSearchOperation is ScanController.GE, the scan
1026: stops just before the first row which is greater than or
1027: equal to the stopKeyValue. If stopSearchOperation is
1028: ScanController.GT, the scan stops just before the first row whose
1029: key is greater than startKeyValue. The stopSearchOperation
1030: parameter is ignored if the stopKeyValue parameter is null.
1031:
1032: @exception StandardException if the scan could not be
1033: opened for some reason. Throws SQLState.STORE_CONGLOMERATE_DOES_NOT_EXIST
1034: if the conglomId being requested does not exist for some reason (ie.
1035: someone has dropped it).
1036:
1037: @see RowUtil
1038: @see ScanController
1039: **/
1040: ScanController openScan(long conglomId, boolean hold,
1041: int open_mode, int lock_level, int isolation_level,
1042: FormatableBitSet scanColumnList,
1043: DataValueDescriptor[] startKeyValue,
1044: int startSearchOperator, Qualifier qualifier[][],
1045: DataValueDescriptor[] stopKeyValue, int stopSearchOperator)
1046: throws StandardException;
1047:
1048: /**
1049: * Open a scan on a conglomerate, optionally providing compiled info.
1050: * <p>
1051: * Same as openScan(), except that one can optionally provide
1052: * "compiled" static_info and/or dynamic_info. This compiled information
1053: * must have be gotten from getDynamicCompiledConglomInfo() and/or
1054: * getStaticCompiledConglomInfo() calls on the same conglomid being opened.
1055: * It is up to caller that "compiled" information is still valid and
1056: * is appropriately multi-threaded protected.
1057: * <p>
1058: *
1059: * @see TransactionController#openScan
1060: * @see TransactionController#getDynamicCompiledConglomInfo
1061: * @see TransactionController#getStaticCompiledConglomInfo
1062: * @see DynamicCompiledOpenConglomInfo
1063: * @see StaticCompiledOpenConglomInfo
1064: *
1065: * @return The identifier to be used to open the conglomerate later.
1066: *
1067: * @param open_mode see openScan()
1068: * @param lock_level see openScan()
1069: * @param isolation_level see openScan()
1070: * @param scanColumnList see openScan()
1071: * @param startKeyValue see openScan()
1072: * @param startSearchOperator see openScan()
1073: * @param qualifier see openScan()
1074: * @param stopKeyValue see openScan()
1075: * @param stopSearchOperator see openScan()
1076: * @param static_info object returned from
1077: * getStaticCompiledConglomInfo() call on this id.
1078: * @param dynamic_info object returned from
1079: * getDynamicCompiledConglomInfo() call on this id.
1080: *
1081: * @exception StandardException Standard exception policy.
1082: **/
1083: ScanController openCompiledScan(boolean hold, int open_mode,
1084: int lock_level, int isolation_level,
1085: FormatableBitSet scanColumnList,
1086: DataValueDescriptor[] startKeyValue,
1087: int startSearchOperator, Qualifier qualifier[][],
1088: DataValueDescriptor[] stopKeyValue, int stopSearchOperator,
1089: StaticCompiledOpenConglomInfo static_info,
1090: DynamicCompiledOpenConglomInfo dynamic_info)
1091: throws StandardException;
1092:
1093: /**
1094: * Open a scan which gets copies of multiple rows at a time.
1095: * <p>
1096: * All inputs work exactly as in openScan(). The return is
1097: * a GroupFetchScanController, which only allows fetches of groups
1098: * of rows from the conglomerate.
1099: * <p>
1100: *
1101: * @return The GroupFetchScanController to be used to fetch the rows.
1102: *
1103: * @param conglomId see openScan()
1104: * @param open_mode see openScan()
1105: * @param lock_level see openScan()
1106: * @param isolation_level see openScan()
1107: * @param scanColumnList see openScan()
1108: * @param startKeyValue see openScan()
1109: * @param startSearchOperator see openScan()
1110: * @param qualifier see openScan()
1111: * @param stopKeyValue see openScan()
1112: * @param stopSearchOperator see openScan()
1113: *
1114: * @exception StandardException Standard exception policy.
1115: *
1116: * @see ScanController
1117: * @see GroupFetchScanController
1118: **/
1119: GroupFetchScanController openGroupFetchScan(long conglomId,
1120: boolean hold, int open_mode, int lock_level,
1121: int isolation_level, FormatableBitSet scanColumnList,
1122: DataValueDescriptor[] startKeyValue,
1123: int startSearchOperator, Qualifier qualifier[][],
1124: DataValueDescriptor[] stopKeyValue, int stopSearchOperator)
1125: throws StandardException;
1126:
1127: /**
1128: * Compress table in place.
1129: * <p>
1130: * Returns a GroupFetchScanController which can be used to move rows
1131: * around in a table, creating a block of free pages at the end of the
1132: * table. The process will move rows from the end of the table toward
1133: * the beginning. The GroupFetchScanController will return the
1134: * old row location, the new row location, and the actual data of any
1135: * row moved. Note that this scan only returns moved rows, not an
1136: * entire set of rows, the scan is designed specifically to be
1137: * used by either explicit user call of the SYSCS_ONLINE_COMPRESS_TABLE()
1138: * procedure, or internal background calls to compress the table.
1139: *
1140: * The old and new row locations are returned so that the caller can
1141: * update any indexes necessary.
1142: *
1143: * This scan always returns all collumns of the row.
1144: *
1145: * All inputs work exactly as in openScan(). The return is
1146: * a GroupFetchScanController, which only allows fetches of groups
1147: * of rows from the conglomerate.
1148: * <p>
1149: *
1150: * @return The GroupFetchScanController to be used to fetch the rows.
1151: *
1152: * @param conglomId see openScan()
1153: * @param hold see openScan()
1154: * @param open_mode see openScan()
1155: * @param lock_level see openScan()
1156: * @param isolation_level see openScan()
1157: *
1158: * @exception StandardException Standard exception policy.
1159: *
1160: * @see ScanController
1161: * @see GroupFetchScanController
1162: **/
1163: GroupFetchScanController defragmentConglomerate(long conglomId,
1164: boolean online, boolean hold, int open_mode,
1165: int lock_level, int isolation_level)
1166: throws StandardException;
1167:
1168: /**
1169: * Purge all committed deleted rows from the conglomerate.
1170: * <p>
1171: * This call will purge committed deleted rows from the conglomerate,
1172: * that space will be available for future inserts into the conglomerate.
1173: * <p>
1174: *
1175: * @param conglomId Id of the conglomerate to purge.
1176: *
1177: * @exception StandardException Standard exception policy.
1178: **/
1179: void purgeConglomerate(long conglomId) throws StandardException;
1180:
1181: /**
1182: * Return free space from the conglomerate back to the OS.
1183: * <p>
1184: * Returns free space from the conglomerate back to the OS. Currently
1185: * only the sequential free pages at the "end" of the conglomerate can
1186: * be returned to the OS.
1187: * <p>
1188: *
1189: * @param conglomId Id of the conglomerate to purge.
1190: *
1191: * @exception StandardException Standard exception policy.
1192: **/
1193: void compressConglomerate(long conglomId) throws StandardException;
1194:
1195: /**
1196: * Retrieve the maximum value row in an ordered conglomerate.
1197: * <p>
1198: * Returns true and fetches the rightmost non-null row of an ordered
1199: * conglomerate into "fetchRow" if there is at least one non-null row in
1200: * the conglomerate. If there are no non-null rows in the conglomerate it
1201: * returns false. Any row with
1202: * a first column with a Null is considered a "null" row.
1203: * <p>
1204: * Non-ordered conglomerates will not implement this interface, calls
1205: * will generate a StandardException.
1206: * <p>
1207: * RESOLVE - this interface is temporary, long term equivalent (and more)
1208: * functionality will be provided by the openBackwardScan() interface.
1209: * <p>
1210: * ISOLATION_SERIALIZABLE and MODE_RECORD locking for btree max:
1211: * The "BTREE" implementation will at the very least get a shared row lock
1212: * on the max key row and the key previous to the max.
1213: * This will be the case where the max row exists in the rightmost page of
1214: * the btree. These locks won't be released. If the row does not exist in
1215: * the last page of the btree then a scan of the entire btree will be
1216: * performed, locks acquired in this scan will not be released.
1217: * <p>
1218: * Note that under ISOLATION_READ_COMMITTED, all locks on the table
1219: * are released before returning from this call.
1220: *
1221: * @param conglomId The identifier of the conglomerate
1222: * to open the scan for.
1223: *
1224: * @param open_mode Specifiy flags to control opening of table.
1225: * OPENMODE_FORUPDATE - if set open the table for
1226: * update otherwise open table shared.
1227: * @param lock_level One of (MODE_TABLE, MODE_RECORD).
1228: *
1229: * @param isolation_level The isolation level to lock the conglomerate at.
1230: * One of (ISOLATION_READ_COMMITTED,
1231: * ISOLATION_REPEATABLE_READ or
1232: * ISOLATION_SERIALIZABLE).
1233: *
1234: * @param scanColumnList A description of which columns to return from
1235: * every fetch in the scan. template, and
1236: * scanColumnList work together
1237: * to describe the row to be returned by the scan -
1238: * see RowUtil for description of how these three
1239: * parameters work together to describe a "row".
1240: *
1241: * @param fetchRow The row to retrieve the maximum value into.
1242: *
1243: * @return boolean indicating if a row was found and retrieved or not.
1244: *
1245: * @exception StandardException Standard exception policy.
1246: **/
1247: boolean fetchMaxOnBtree(long conglomId, int open_mode,
1248: int lock_level, int isolation_level,
1249: FormatableBitSet scanColumnList,
1250: DataValueDescriptor[] fetchRow) throws StandardException;
1251:
1252: /**
1253: * Return an open StoreCostController for the given conglomid.
1254: * <p>
1255: * Return an open StoreCostController which can be used to ask about
1256: * the estimated row counts and costs of ScanController and
1257: * ConglomerateController operations, on the given conglomerate.
1258: * <p>
1259: *
1260: * @return The open StoreCostController.
1261: *
1262: * @param conglomId The identifier of the conglomerate to open.
1263: *
1264: * @exception StandardException Standard exception policy.
1265: *
1266: * @see StoreCostController
1267: **/
1268: StoreCostController openStoreCost(long conglomId)
1269: throws StandardException;
1270:
1271: /**
1272: * Report on the number of open conglomerates in the transaction.
1273: * <p>
1274: * There are 4 types of open "conglomerates" that can be tracked, those
1275: * opened by each of the following: openConglomerate(), openScan(),
1276: * createSort(), and openSort(). Scans opened by openSortScan() are
1277: * tracked the same as those opened by openScan(). This routine can be
1278: * used to either report on the number of all opens, or may be used to
1279: * track one particular type of open.
1280: * <p>
1281: * This routine is expected to be used for debugging only. An
1282: * implementation may only track this info under SanityManager.DEBUG mode.
1283: * If the implementation does not track the info it will return -1 (so
1284: * code using this call to verify that no congloms are open should check
1285: * for return <= 0 rather than == 0).
1286: * <p>
1287: * The return value depends on the "which_to_count" parameter as follows:
1288: * <UL>
1289: * <LI>
1290: * OPEN_CONGLOMERATE - return # of openConglomerate() calls not close()'d.
1291: * <LI>
1292: * OPEN_SCAN - return # of openScan() + openSortScan() calls not
1293: * close()'d.
1294: * <LI>
1295: * OPEN_CREATED_SORTS - return # of sorts created (createSort()) in
1296: * current xact. There is currently no way to get
1297: * rid of these sorts before end of transaction.
1298: * <LI>
1299: * OPEN_SORT - return # of openSort() calls not close()'d.
1300: * <LI>
1301: * OPEN_TOTAL - return total # of all above calls not close()'d.
1302: * </UL>
1303: * - note an implementation may return -1 if it does not track the
1304: * above information.
1305: * <p>
1306: * @return The nunber of open's of a type indicated by "which_to_count"
1307: * parameter.
1308: *
1309: * @param which_to_count Which kind of open to report on.
1310: *
1311: * @exception StandardException Standard exception policy.
1312: **/
1313: public int countOpens(int which_to_count) throws StandardException;
1314:
1315: /**
1316: * Return a string with debug information about opened congloms/scans/sorts.
1317: * <p>
1318: * Return a string with debugging information about current opened
1319: * congloms/scans/sorts which have not been close()'d.
1320: * Calls to this routine are only valid under code which is conditional
1321: * on SanityManager.DEBUG.
1322: * <p>
1323: *
1324: * @return String with debugging information.
1325: *
1326: * @exception StandardException Standard exception policy.
1327: **/
1328: public String debugOpened() throws StandardException;
1329:
1330: /**
1331: Get an object to handle non-transactional files.
1332: */
1333: public FileResource getFileHandler();
1334:
1335: /**
1336: Return an object that when used as the compatability space *and*
1337: group for a lock request, guarantees that the lock will be removed
1338: on a commit or an abort.
1339: */
1340: public Object getLockObject();
1341:
1342: /**
1343: * Return static information about the conglomerate to be included in a
1344: * a compiled plan.
1345: * <p>
1346: * The static info would be valid until any ddl was executed on the
1347: * conglomid, and would be up to the caller to throw away when that
1348: * happened. This ties in with what language already does for other
1349: * invalidation of static info. The type of info in this would be
1350: * containerid and array of format id's from which templates can be created.
1351: * The info in this object is read only and can be shared among as many
1352: * threads as necessary.
1353: * <p>
1354: *
1355: * @return The static compiled information.
1356: *
1357: * @param conglomId The identifier of the conglomerate to open.
1358: *
1359: * @exception StandardException Standard exception policy.
1360: **/
1361: public StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo(
1362: long conglomId) throws StandardException;
1363:
1364: /**
1365: * Return dynamic information about the conglomerate to be dynamically
1366: * reused in repeated execution of a statement.
1367: * <p>
1368: * The dynamic info is a set of variables to be used in a given
1369: * ScanController or ConglomerateController. It can only be used in one
1370: * controller at a time. It is up to the caller to insure the correct
1371: * thread access to this info. The type of info in this is a scratch
1372: * template for btree traversal, other scratch variables for qualifier
1373: * evaluation, ...
1374: * <p>
1375: *
1376: * @return The dynamic information.
1377: *
1378: * @param conglomId The identifier of the conglomerate to open.
1379: *
1380: * @exception StandardException Standard exception policy.
1381: **/
1382: public DynamicCompiledOpenConglomInfo getDynamicCompiledConglomInfo(
1383: long conglomId) throws StandardException;
1384:
1385: /**************************************************************************
1386: * Interfaces previously defined in TcCacheStatIface:
1387: **************************************************************************
1388: */
1389:
1390: /**
1391: Get cache statistics for the specified cache
1392: */
1393: public long[] getCacheStats(String cacheName);
1394:
1395: /**
1396: Reset the cache statistics for the specified cache
1397: */
1398: public void resetCacheStats(String cacheName);
1399:
1400: /**************************************************************************
1401: * Interfaces previously defined in TcLogIface:
1402: **************************************************************************
1403: */
1404: /**
1405: Log an operation and then action it in the context of this
1406: transaction.
1407:
1408: <P>This simply passes the operation to the RawStore which logs and
1409: does it.
1410:
1411:
1412: @param operation the operation that is to be applied
1413:
1414: @see org.apache.derby.iapi.store.raw.Loggable
1415: @see org.apache.derby.iapi.store.raw.Transaction#logAndDo
1416: @exception StandardException Standard cloudscape exception policy
1417: **/
1418: public void logAndDo(Loggable operation) throws StandardException;
1419:
1420: /**************************************************************************
1421: * Interfaces previously defined in TcSortIface:
1422: **************************************************************************
1423: */
1424:
1425: /**
1426: Create a sort. Rows are inserted into the sort with a
1427: sort controller, and subsequently retrieved with a
1428: sort scan controller. The rows come out in the order
1429: specified by the parameters.
1430: <p>
1431: Sorts also do aggregation. The input (unaggregated) rows
1432: have the same format as the aggregated rows, and the
1433: aggregate results are part of the both rows. The sorter,
1434: when it notices that a row is a duplicate of another,
1435: calls a user-supplied aggregation method (see interface
1436: Aggregator), passing it both rows. One row is known as
1437: the 'addend' and the other the 'accumulator'. The
1438: aggregation method is assumed to merge the addend
1439: into the accumulator. The sort then discards the addend
1440: row.
1441: <p>
1442: So, for the query:
1443: <pre><blockquote>
1444: select a, sum(b)
1445: from t
1446: group by a
1447: </blockquote></pre>
1448: The input row to the sorter would have one column for
1449: a and another column for sum(b). It is up to the caller
1450: to get the format of the row correct, and to initialize
1451: the aggregate values correctly (null for most aggregates,
1452: 0 for count).
1453: <p>
1454: Nulls are always considered to be ordered in a sort, that is,
1455: null compares equal to null, and less than anything else.
1456:
1457: @param implParameters Properties which help in choosing
1458: implementation-specific sort options. If null, a
1459: "generally useful" sort will be used.
1460:
1461: @param template A row which is prototypical for the sort.
1462: All rows inserted into the sort controller must have
1463: exactly the same number of columns as the template row.
1464: Every column in an inserted row must have the same type
1465: as the corresponding column in the template.
1466:
1467: @param columnOrdering An array which specifies which columns
1468: participate in ordering - see interface ColumnOrdering for
1469: details. The column referenced in the 0th columnOrdering
1470: object is compared first, then the 1st, etc. To sort on a single
1471: column specify an array with a single entry.
1472:
1473: @param sortObserver An object that is used to observe
1474: the sort. It is used to provide a callback into the sorter.
1475: If the sortObserver is null, then the sort proceeds as normal.
1476: If the sortObserver is non null, then it is called as
1477: rows are loaded into the sorter. It can be used to implement
1478: a distinct sort, aggregates, etc.
1479:
1480: @param alreadyInOrder Indicates that the rows inserted into
1481: the sort controller will already be in order. This is used
1482: to perform aggregation only.
1483:
1484: @param estimatedRows The number of rows that the caller
1485: estimates will be inserted into the sort. -1 indicates that
1486: the caller has no idea. Used by the sort to make good choices
1487: about in-memory vs. external sorting, and to size merge runs.
1488:
1489: @param estimatedRowSize The estimated average row size of the
1490: rows being sorted. This is the client portion of the rowsize, it should
1491: not attempt to calculate Store's overhead. -1 indicates that the caller
1492: has no idea (and the sorter will use 100 bytes in that case. Used by the
1493: sort to make good choices about in-memory vs. external sorting, and to size
1494: merge runs. The client is not expected to estimate the per column/
1495: per row overhead of raw store, just to make a guess about the storage
1496: associated with each row (ie. reasonable estimates for some implementations
1497: would be 4 for int, 8 for long, 102 for char(100),
1498: 202 for varchar(200), a number out of hat for user types, ...).
1499:
1500: @return The sort identifier which can be used subsequently to
1501: open sort controllers and scans.
1502:
1503: @see SortObserver
1504: @see ColumnOrdering
1505: @see ScanController
1506: @see SortController
1507:
1508: @exception StandardException From a lower-level exception.
1509: **/
1510: long createSort(Properties implParameters,
1511: DataValueDescriptor[] template,
1512: ColumnOrdering columnOrdering[], SortObserver sortObserver,
1513: boolean alreadyInOrder, long estimatedRows,
1514: int estimatedRowSize) throws StandardException;
1515:
1516: /**
1517: Drop a sort.
1518: <p>
1519: Drop a sort created by a call to createSort() within the current
1520: transaction (sorts are automatically "dropped" at the end of a
1521: transaction. This call should only be made after all openSortScan()'s
1522: and openSort()'s have been closed.
1523:
1524: @param sortid The identifier of the sort to drop, as returned from
1525: createSort.
1526: <p>
1527: @exception StandardException From a lower-level exception.
1528: **/
1529: void dropSort(long sortid) throws StandardException;
1530:
1531: /**
1532: Open a sort controller for a sort previously created in this
1533: transaction. Sort controllers are used to insert rows into
1534: the sort.
1535: <p>
1536: There may (in the future) be multiple sort inserters
1537: for a given sort, the idea being that the various threads of
1538: a parallel query plan can all insert into the sort. For now,
1539: however, only a single sort controller per sort is supported.
1540:
1541: @param id The identifier of the sort to open, as returned from
1542: createSort.
1543:
1544: @return A sort controller to use for inserting.
1545:
1546: @exception StandardException From a lower-level exception.
1547: **/
1548:
1549: SortController openSort(long id) throws StandardException;
1550:
1551: /**
1552: * Return an open SortCostController.
1553: * <p>
1554: * Return an open SortCostController which can be used to ask about
1555: * the estimated costs of SortController() operations.
1556: * <p>
1557: * @param implParameters Properties which help in choosing
1558: * implementation-specific sort options. If null, a
1559: * "generally useful" sort will be used.
1560: *
1561: * @return The open StoreCostController.
1562: *
1563: * @exception StandardException Standard exception policy.
1564: *
1565: * @see StoreCostController
1566: **/
1567: SortCostController openSortCostController(Properties implParameters)
1568: throws StandardException;
1569:
1570: /**
1571: Open a scan for retrieving rows from a sort. Returns a RowSource for
1572: retrieving rows from the sort.
1573:
1574: @param id The identifier of the sort to scan, as returned
1575: from createSort.
1576:
1577: @return The RowSource
1578:
1579: @exception StandardException From a lower-level exception.
1580: **/
1581: RowLocationRetRowSource openSortRowSource(long id)
1582: throws StandardException;
1583:
1584: /**
1585: Open a scan for retrieving rows from a sort. Returns a
1586: scan controller for retrieving rows from the sort (NOTE:
1587: the only legal methods to use on the returned sort controller
1588: are next() and fetch() - probably there should be scan
1589: controllers and updatable scan controllers).
1590: <p>
1591: In the future, multiple sort scans on the same sort will
1592: be supported (for parallel execution across a uniqueness
1593: sort in which the order of the resulting rows is not
1594: important). Currently, only a single sort scan is allowed
1595: per sort.
1596: <p>
1597: In the future, it will be possible to open a sort scan
1598: and start retrieving rows before the last row is inserted.
1599: The sort controller would block till rows were available
1600: to return. Currently, an attempt to retrieve a row before
1601: the sort controller is closed will cause an exception.
1602:
1603: @param id The identifier of the sort to scan, as returned from createSort.
1604: @param hold If true, this scan will be maintained open over commits.
1605:
1606: @return The sort controller.
1607:
1608: @exception StandardException From a lower-level exception.
1609: **/
1610:
1611: ScanController openSortScan(long id, boolean hold)
1612: throws StandardException;
1613:
1614: /**************************************************************************
1615: * Interfaces previously defined in TcTransactionIface:
1616: **************************************************************************
1617: */
1618:
1619: /**
1620: Return true if any transaction is blocked (even if not by this one).
1621:
1622: */
1623: public boolean anyoneBlocked();
1624:
1625: /**
1626: Abort all changes made by this transaction since the last commit, abort
1627: or the point the transaction was started, whichever is the most recent.
1628: All savepoints within this transaction are released, and all resources
1629: are released (held or non-held).
1630:
1631: @exception StandardException Only exceptions with severities greater than
1632: ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
1633: **/
1634: public void abort() throws StandardException;
1635:
1636: /**
1637: Commit this transaction. All savepoints within this transaction are
1638: released. All non-held conglomerates and scans are closed.
1639:
1640: @exception StandardException Only exceptions with severities greater than
1641: ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
1642: If an exception is thrown, the transaction will not (necessarily) have
1643: been aborted. The standard error handling mechanism is expected to do the
1644: appropriate cleanup. In other words, if commit() encounters an error, the
1645: exception is propagated up to the the standard exception handler, which
1646: initiates cleanupOnError() processing, which will eventually abort the
1647: transaction.
1648: **/
1649: public void commit() throws StandardException;
1650:
1651: /**
1652: "Commit" this transaction without sync'ing the log. Everything else is
1653: identical to commit(), use this at your own risk.
1654:
1655: <BR>bits in the commitflag can turn on to fine tuned the "commit":
1656: KEEP_LOCKS - no locks will be released by the
1657: commit and no post commit processing
1658: will be initiated. If, for some
1659: reasons, the locks cannot be kept
1660: even if this flag is set, then the
1661: commit will sync the log, i.e., it
1662: will revert to the normal commit.
1663:
1664: READONLY_TRANSACTION_INITIALIZATION - Special case used for processing
1665: while creating the transaction.
1666: Should only be used by the system
1667: while creating the transaction to
1668: commit readonly work that may have
1669: been done using the transaction
1670: while getting it setup to be used
1671: by the user. In the future we should
1672: instead use a separate tranaction to
1673: do this initialization. Will fail
1674: if called on a transaction which
1675: has done any updates.
1676: @see TransactionController#commit
1677:
1678: @exception StandardException Only exceptions with severities greater than
1679: ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
1680: If an exception is thrown, the transaction will not (necessarily) have
1681: been aborted. The standard error handling mechanism is expected to do the
1682: appropriate cleanup. In other words, if commit() encounters an error, the
1683: exception is propagated up to the the standard exception handler, which
1684: initiates cleanupOnError() processing, which will eventually abort the
1685: transaction.
1686: **/
1687: public DatabaseInstant commitNoSync(int commitflag)
1688: throws StandardException;
1689:
1690: public final int RELEASE_LOCKS = 0x1;
1691: public final int KEEP_LOCKS = 0x2;
1692: public final int READONLY_TRANSACTION_INITIALIZATION = 0x4;
1693:
1694: /**
1695: Abort the current transaction and pop the context.
1696: **/
1697: public void destroy();
1698:
1699: /**
1700: * Get the context manager that the transaction was created with.
1701: * <p>
1702: *
1703: * @return The context manager that the transaction was created with.
1704: *
1705: **/
1706: public ContextManager getContextManager();
1707:
1708: /**
1709: * Get string id of the transaction.
1710: * <p>
1711: * This transaction "name" will be the same id which is returned in
1712: * the TransactionInfo information, used by the lock and transaction
1713: * vti's to identify transactions.
1714: * <p>
1715: * Although implementation specific, the transaction id is usually a number
1716: * which is bumped every time a commit or abort is issued.
1717: * <p>
1718: *
1719: * @return The a string which identifies the transaction.
1720: **/
1721: public String getTransactionIdString();
1722:
1723: /**
1724: * Get string id of the transaction that would be when the Transaction
1725: * is IN active state. This method increments the Tx id of current Tx
1726: * object if it is in idle state.
1727: * Note: Use this method only getTransactionIdString() is not suitable.
1728: * @return The string which identifies the transaction.
1729: **/
1730: public String getActiveStateTxIdString();
1731:
1732: /**
1733: * Reveals whether the transaction has ever read or written data.
1734: *
1735: * @return true If the transaction has never read or written data.
1736: **/
1737: boolean isIdle();
1738:
1739: /**
1740: * Reveals whether the transaction is a global or local transaction.
1741: *
1742: * @return true If the transaction was either started by
1743: * AccessFactory.startXATransaction() or was morphed to a global
1744: * transaction by calling createXATransactionFromLocalTransaction().
1745: *
1746: * @see AccessFactory#startXATransaction
1747: * @see TransactionController#createXATransactionFromLocalTransaction
1748: *
1749: **/
1750: boolean isGlobal();
1751:
1752: /**
1753: * Reveals whether the transaction is read only.
1754: *
1755: * @return true If the transaction is read only to this point.
1756: *
1757: **/
1758: boolean isPristine();
1759:
1760: /**
1761: Release the save point of the given name. Releasing a savepoint removes all
1762: knowledge from this transaction of the named savepoint and any savepoints
1763: set since the named savepoint was set.
1764:
1765: @param name The user provided name of the savepoint, set by the user
1766: in the setSavePoint() call.
1767: @param kindOfSavepoint A NULL value means it is an internal savepoint (ie not a user defined savepoint)
1768: Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
1769: A String value for kindOfSavepoint would mean it is SQL savepoint
1770: A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
1771: @return returns savepoint position in the stack.
1772:
1773: @exception StandardException Standard cloudscape exception policy. A
1774: statement level exception is thrown if
1775: no savepoint exists with the given name.
1776: **/
1777: public int releaseSavePoint(String name, Object kindOfSavepoint)
1778: throws StandardException;
1779:
1780: /**
1781: Rollback all changes made since the named savepoint was set. The named
1782: savepoint is not released, it remains valid within this transaction, and
1783: thus can be named it future rollbackToSavePoint() calls. Any savepoints
1784: set since this named savepoint are released (and their changes rolled back).
1785: <p>
1786: if "close_controllers" is true then all conglomerates and scans are closed
1787: (held or non-held).
1788: <p>
1789: If "close_controllers" is false then no cleanup is done by the
1790: TransactionController. It is then the responsibility of the caller to
1791: close all resources that may have been affected by the statements
1792: backed out by the call. This option is meant to be used by the Language
1793: implementation of statement level backout, where the system "knows" what
1794: could be affected by the scope of the statements executed within the
1795: statement.
1796: <p>
1797:
1798: @param name The identifier of the SavePoint to roll back to.
1799: @param close_controllers boolean indicating whether or not the controller
1800: should close open controllers.
1801: @param kindOfSavepoint A NULL value means it is an internal savepoint (ie not a user defined savepoint)
1802: Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
1803: A String value for kindOfSavepoint would mean it is SQL savepoint
1804: A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
1805: @return returns savepoint position in the stack.
1806:
1807: @exception StandardException Standard cloudscape exception policy. A
1808: statement level exception is thrown if
1809: no savepoint exists with the given name.
1810: **/
1811: public int rollbackToSavePoint(String name,
1812: boolean close_controllers, Object kindOfSavepoint)
1813: throws StandardException;
1814:
1815: /**
1816: Set a save point in the current transaction. A save point defines a point in
1817: time in the transaction that changes can be rolled back to. Savepoints
1818: can be nested and they behave like a stack. Setting save points "one" and
1819: "two" and the rolling back "one" will rollback all the changes made since
1820: "one" (including those made since "two") and release savepoint "two".
1821:
1822: @param name The user provided name of the savepoint.
1823: @param kindOfSavepoint A NULL value means it is an internal savepoint (ie not a user defined savepoint)
1824: Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
1825: A String value for kindOfSavepoint would mean it is SQL savepoint
1826: A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
1827: @return returns savepoint position in the stack.
1828:
1829: @exception StandardException Standard cloudscape exception policy. A
1830: statement level exception is thrown if
1831: no savepoint exists with the given name.
1832: **/
1833: public int setSavePoint(String name, Object kindOfSavepoint)
1834: throws StandardException;
1835:
1836: /**
1837: * Convert a local transaction to a global transaction.
1838: * <p>
1839: * Get a transaction controller with which to manipulate data within
1840: * the access manager. Tbis controller allows one to manipulate a
1841: * global XA conforming transaction.
1842: * <p>
1843: * Must only be called a previous local transaction was created and exists
1844: * in the context. Can only be called if the current transaction is in
1845: * the idle state. Upon return from this call the old tc will be unusable,
1846: * and all references to it should be dropped (it will have been implicitly
1847: * destroy()'d by this call.
1848: * <p>
1849: * The (format_id, global_id, branch_id) triplet is meant to come exactly
1850: * from a javax.transaction.xa.Xid. We don't use Xid so that the system
1851: * can be delivered on a non-1.2 vm system and not require the javax classes
1852: * in the path.
1853: *
1854: * @param global_id the global transaction identifier part of XID - ie.
1855: * Xid.getGlobalTransactionId().
1856: * @param branch_id The branch qualifier of the Xid - ie.
1857: * Xid.getBranchQaulifier()
1858: *
1859: * @exception StandardException Standard exception policy.
1860: * @see TransactionController
1861: **/
1862: /* XATransactionController */Object createXATransactionFromLocalTransaction(
1863: int format_id, byte[] global_id, byte[] branch_id)
1864: throws StandardException;
1865:
1866: }
|