Class RAMTransaction

    • Field Detail

      • rawtran

        protected Transaction rawtran
        The corresponding raw store transaction.
      • accessmanager

        protected RAMAccessManager accessmanager
        The access manager this transaction is under.
      • parent_tran

        protected RAMTransaction parent_tran
        The parent transaction if this is a nested user transaction.
      • scanControllers

        private java.util.ArrayList<ScanManager> scanControllers
      • sorts

        private java.util.ArrayList<Sort> sorts
      • sortControllers

        private java.util.ArrayList<SortController> sortControllers
      • freeSortIds

        private java.util.ArrayList<java.lang.Integer> freeSortIds
        List of sort identifiers (represented as Integer objects) which can be reused. Since sort identifiers are used as array indexes, we need to reuse them to avoid leaking memory (DERBY-912).
      • tempCongloms

        protected java.util.HashMap<java.lang.Long,​Conglomerate> tempCongloms
        Where to look for temporary conglomerates.
      • nextTempConglomId

        private long nextTempConglomId
        Next id to use for a temporary conglomerate.
      • alterTableCallMade

        private boolean alterTableCallMade
        Set by alter table to indicate that the conglomerate cache needs to be invalidated if a transaction aborting error is encountered, cleared after cleanup.
      • transaction_lock_level

        private int transaction_lock_level
        The lock level of the transaction.

        Cannot lock a level lower than the getSystemLockLevel(). So if getSystemLockLevel() is table level locking, setting the transaction locking level to record has no effect.

    • Method Detail

      • closeControllers

        protected void closeControllers​(boolean closeHeldControllers)
                                 throws StandardException
        Private/Protected methods of This class:
        Throws:
        StandardException
      • determine_locking_policy

        private LockingPolicy determine_locking_policy​(int requested_lock_level,
                                                       int isolation_level)
        Determine correct locking policy for a conglomerate open.

        Determine from the following table whether to table or record lock the conglomerate we are opening.

        System level override ------------------------------- user requests table locking record locking ------------- ------------- -------------- TransactionController.MODE_TABLE TABLE TABLE TransactionController.MODE_RECORD TABLE RECORD

      • determine_lock_level

        private int determine_lock_level​(int requested_lock_level)
      • invalidateConglomerateCache

        protected void invalidateConglomerateCache()
                                            throws StandardException
        Invalidate the conglomerate cache, if necessary. If an alter table call has been made then invalidate the cache.
        Throws:
        StandardException - Standard exception policy.
      • addColumnToConglomerate

        public void addColumnToConglomerate​(long conglomId,
                                            int column_id,
                                            Storable template_column,
                                            int collation_id)
                                     throws StandardException
        Add a column to a conglomerate. The conglomerate must not be open in the current transaction. This also means that there must not be any active scans on it. The column can only be added at the spot just after the current set of columns. The template_column must be nullable. After this call has been made, all fetches of this column from rows that existed in the table prior to this call will return "null".
        Specified by:
        addColumnToConglomerate in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to drop.
        column_id - The column number to add this column at.
        template_column - An instance of the column to be added to table.
        collation_id - collation id of the added column.
        Throws:
        StandardException - Only some types of conglomerates can support adding a column, for instance "heap" conglomerates support adding a column while "btree" conglomerates do not. If the column can not be added an exception will be thrown.
      • getStaticCompiledConglomInfo

        public StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo​(long conglomId)
                                                                   throws StandardException
        Return static information about the conglomerate to be included in a a compiled plan.

        The static info would be valid until any ddl was executed on the conglomid, and would be up to the caller to throw away when that happened. This ties in with what language already does for other invalidation of static info. The type of info in this would be containerid and array of format id's from which templates can be created. The info in this object is read only and can be shared among as many threads as necessary.

        Specified by:
        getStaticCompiledConglomInfo in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to open.
        Returns:
        The static compiled information.
        Throws:
        StandardException - Standard exception policy.
      • getDynamicCompiledConglomInfo

        public DynamicCompiledOpenConglomInfo getDynamicCompiledConglomInfo​(long conglomId)
                                                                     throws StandardException
        Return dynamic information about the conglomerate to be dynamically reused in repeated execution of a statement.

        The dynamic info is a set of variables to be used in a given ScanController or ConglomerateController. It can only be used in one controller at a time. It is up to the caller to insure the correct thread access to this info. The type of info in this is a scratch template for btree traversal, other scratch variables for qualifier evaluation, ...

        Specified by:
        getDynamicCompiledConglomInfo in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to open.
        Returns:
        The dynamic information.
        Throws:
        StandardException - Standard exception policy.
      • countCreatedSorts

        private final int countCreatedSorts()
      • countOpens

        public int countOpens​(int which_to_count)
                       throws StandardException
        Report on the number of open conglomerates in the transaction.

        There are 4 types of open "conglomerates" that can be tracked, those opened by each of the following: openConglomerate(), openScan(), openSort(), and openSortScan(). This routine can be used to either report on the number of all opens, or may be used to track one particular type of open. This routine is expected to be used for debugging only. An implementation may only track this info under SanityManager.DEBUG mode. If the implementation does not track the info it will return -1 (so code using this call to verify that no congloms are open should check for return <= 0 rather than == 0). The return value depends on the "which_to_count" parameter as follows: OPEN_CONGLOMERATE - return # of openConglomerate() calls not close()'d. OPEN_SCAN - return # of openScan() calls not close()'d. OPEN_CREATED_SORTS - return # of sorts created (createSort()) in current xact. There is currently no way to get rid of these sorts before end of transaction. OPEN_SORT - return # of openSort() calls not close()'d. OPEN_TOTAL - return total # of all above calls not close()'d. - note an implementation may return -1 if it does not track the above information.

        Specified by:
        countOpens in interface TransactionController
        Parameters:
        which_to_count - Which kind of open to report on.
        Returns:
        The nunber of open's of a type indicated by "which_to_count" parameter.
        Throws:
        StandardException - Standard exception policy.
      • createConglomerate

        public long createConglomerate​(java.lang.String implementation,
                                       DataValueDescriptor[] template,
                                       ColumnOrdering[] columnOrder,
                                       int[] collationIds,
                                       java.util.Properties properties,
                                       int temporaryFlag)
                                throws StandardException
        Create a new conglomerate.

        Specified by:
        createConglomerate in interface TransactionController
        Parameters:
        implementation - Specifies what kind of conglomerate to create. THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK. For now, use "BTREE" or "heap" for a local access manager.
        template - A row which describes the prototypical row that the conglomerate will be holding. Typically this row gives the conglomerate information about the number and type of columns it will be holding. The implementation may require a specific subclass of row type. Note that the createConglomerate call reads the template and makes a copy of any necessary information from the template, no reference to the template is kept (and thus this template can be re-used in subsequent calls - such as openScan()). This field is required when creating either a heap or btree conglomerate.
        columnOrder - Specifies the colummns sort order. Useful only when the conglomerate is of type BTREE, default value is 'null', which means all columns needs to be sorted in Ascending order.
        collationIds - Specifies the collation id of each of the columns in the new conglomerate. Collation id along with format id may be used to create DataValueDescriptor's which may subsequently be used for comparisons. For instance the correct collation specific order and searching is maintained by correctly specifying the collation id of the columns in the index when the index is created.
        properties - Implementation-specific properties of the conglomerate.
        temporaryFlag - Where temporaryFlag can have the following values: IS_DEFAULT - no bit is set. IS_TEMPORARY - if set, the conglomerate is temporary IS_KEPT - only looked at if IS_TEMPORARY, if set, the temporary container is not removed automatically by store when transaction terminates. If IS_TEMPORARY is set, the conglomerate is temporary. Temporary conglomerates are only visible through the transaction controller that created them. Otherwise, they are opened, scanned, and dropped in the same way as permanent conglomerates. Changes to temporary conglomerates persist across commits, but temporary conglomerates are truncated on abort (or rollback to savepoint). Updates to temporary conglomerates are not locked or logged. A temporary conglomerate is only visible to the transaction controller that created it, even if the conglomerate IS_KEPT when the transaction termination. All temporary conglomerate is removed by store when the conglomerate controller is destroyed, or if it is dropped by an explicit dropConglomerate. If Derby reboots, all temporary conglomerates are removed.
        Returns:
        The identifier to be used to open the conglomerate later.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        TransactionController.createConglomerate(java.lang.String, org.apache.derby.iapi.types.DataValueDescriptor[], org.apache.derby.iapi.store.access.ColumnOrdering[], int[], java.util.Properties, int)
      • createAndLoadConglomerate

        public long createAndLoadConglomerate​(java.lang.String implementation,
                                              DataValueDescriptor[] template,
                                              ColumnOrdering[] columnOrder,
                                              int[] collationIds,
                                              java.util.Properties properties,
                                              int temporaryFlag,
                                              RowLocationRetRowSource rowSource,
                                              long[] rowCount)
                                       throws StandardException
        Create a conglomerate and populate it with rows from rowSource.
        Specified by:
        createAndLoadConglomerate in interface TransactionController
        Parameters:
        implementation - Specifies what kind of conglomerate to create. THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK. For now, use "BTREE" or "heap" for a local access manager.
        template - A row which describes the prototypical row that the conglomerate will be holding. Typically this row gives the conglomerate information about the number and type of columns it will be holding. The implementation may require a specific subclass of row type. Note that the createConglomerate call reads the template and makes a copy of any necessary information from the template, no reference to the template is kept (and thus this template can be re-used in subsequent calls - such as openScan()). This field is required when creating either a heap or btree conglomerate.
        columnOrder - Specifies the colummns sort order. Useful only when the conglomerate is of type BTREE, default value is 'null', which means all columns needs to be sorted in Ascending order.
        collationIds - Specifies the collation id of each of the columns in the new conglomerate. Collation id along with format id may be used to create DataValueDescriptor's which may subsequently be used for comparisons. For instance the correct collation specific order and searching is maintained by correctly specifying the collation id of the columns in the index when the index is created.
        properties - Implementation-specific properties of the conglomerate.
        rowSource - the interface to recieve rows to load into the conglomerate.
        rowCount - - if not null the number of rows loaded into the table will be returned as the first element of the array.
        Throws:
        StandardException - Standard Derby Error Policy
        See Also:
        TransactionController.createAndLoadConglomerate(java.lang.String, org.apache.derby.iapi.types.DataValueDescriptor[], org.apache.derby.iapi.store.access.ColumnOrdering[], int[], java.util.Properties, int, org.apache.derby.iapi.store.access.RowLocationRetRowSource, long[])
      • recreateAndLoadConglomerate

        public long recreateAndLoadConglomerate​(java.lang.String implementation,
                                                boolean recreate_ifempty,
                                                DataValueDescriptor[] template,
                                                ColumnOrdering[] columnOrder,
                                                int[] collationIds,
                                                java.util.Properties properties,
                                                int temporaryFlag,
                                                long orig_conglomId,
                                                RowLocationRetRowSource rowSource,
                                                long[] rowCount)
                                         throws StandardException
        recreate a conglomerate and populate it with rows from rowSource.
        Specified by:
        recreateAndLoadConglomerate in interface TransactionController
        Parameters:
        implementation - Specifies what kind of conglomerate to create. THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK. For now, use "BTREE" or "heap" for a local access manager.
        recreate_ifempty - If false, and the rowsource used to load the new conglomerate returns no rows, then the original conglomid will be returned. To the client it will be as if no call was made. Underlying implementations may actually create and drop a container. If true, then a new empty container will be created and it's conglomid will be returned.
        template - A row which describes the prototypical row that the conglomerate will be holding. Typically this row gives the conglomerate information about the number and type of columns it will be holding. The implementation may require a specific subclass of row type. Note that the createConglomerate call reads the template and makes a copy of any necessary information from the template, no reference to the template is kept (and thus this template can be re-used in subsequent calls - such as openScan()). This field is required when creating either a heap or btree conglomerate.
        columnOrder - Specifies the colummns sort order. Useful only when the conglomerate is of type BTREE, default value is 'null', which means all columns needs to be sorted in Ascending order.
        collationIds - Specifies the collation id of each of the columns in the new conglomerate. Collation id along with format id may be used to create DataValueDescriptor's which may subsequently be used for comparisons. For instance the correct collation specific order and searching is maintained by correctly specifying the collation id of the columns in the index when the index is created.
        properties - Implementation-specific properties of the conglomerate.
        temporaryFlag - If true, the conglomerate is temporary. Temporary conglomerates are only visible through the transaction controller that created them. Otherwise, they are opened, scanned, and dropped in the same way as permanent conglomerates. Changes to temporary conglomerates persist across commits, but temporary conglomerates are truncated on abort (or rollback to savepoint). Updates to temporary conglomerates are not locked or logged.
        orig_conglomId - The conglomid of the original conglomerate.
        rowSource - interface to receive rows to load into the conglomerate.
        rowCount - - if not null the number of rows loaded into the table will be returned as the first element of the array.
        Throws:
        StandardException - Standard Derby Error Policy
        See Also:
        TransactionController.createAndLoadConglomerate(java.lang.String, org.apache.derby.iapi.types.DataValueDescriptor[], org.apache.derby.iapi.store.access.ColumnOrdering[], int[], java.util.Properties, int, org.apache.derby.iapi.store.access.RowLocationRetRowSource, long[])
      • debugOpened

        public java.lang.String debugOpened()
                                     throws StandardException
        Return a string with debug information about opened congloms/scans/sorts.

        Return a string with debugging information about current opened congloms/scans/sorts which have not been close()'d. Calls to this routine are only valid under code which is conditional on SanityManager.DEBUG.

        Specified by:
        debugOpened in interface TransactionController
        Returns:
        String with debugging information.
        Throws:
        StandardException - Standard exception policy.
      • conglomerateExists

        public boolean conglomerateExists​(long conglomId)
                                   throws StandardException
        Description copied from interface: TransactionController
        Check whether a conglomerate exists.
        Specified by:
        conglomerateExists in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to check for.
        Returns:
        true if the conglomerate exists, false otherwise.
        Throws:
        StandardException - only thrown if something goes wrong in the lower levels.
      • dropConglomerate

        public void dropConglomerate​(long conglomId)
                              throws StandardException
        Description copied from interface: TransactionController
        Drop a conglomerate. The conglomerate must not be open in the current transaction. This also means that there must not be any active scans on it.
        Specified by:
        dropConglomerate in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to drop.
        Throws:
        StandardException - if the conglomerate could not be dropped for some reason.
      • fetchMaxOnBtree

        public boolean fetchMaxOnBtree​(long conglomId,
                                       int open_mode,
                                       int lock_level,
                                       int isolation_level,
                                       FormatableBitSet scanColumnList,
                                       DataValueDescriptor[] fetchRow)
                                throws StandardException
        Retrieve the maximum value row in an ordered conglomerate.

        Returns true and fetches the rightmost row of an ordered conglomerate into "fetchRow" if there is at least one row in the conglomerate. If there are no rows in the conglomerate it returns false.

        Non-ordered conglomerates will not implement this interface, calls will generate a StandardException.

        RESOLVE - this interface is temporary, long term equivalent (and more) functionality will be provided by the openBackwardScan() interface.

        Specified by:
        fetchMaxOnBtree in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to open the scan for.
        open_mode - Specifiy flags to control opening of table. OPENMODE_FORUPDATE - if set open the table for update otherwise open table shared.
        lock_level - One of (MODE_TABLE, MODE_RECORD, or MODE_NONE).
        isolation_level - The isolation level to lock the conglomerate at. One of (ISOLATION_READ_COMMITTED or ISOLATION_SERIALIZABLE).
        scanColumnList - A description of which columns to return from every fetch in the scan. template, and scanColumnList work together to describe the row to be returned by the scan - see RowUtil for description of how these three parameters work together to describe a "row".
        fetchRow - The row to retrieve the maximum value into.
        Returns:
        boolean indicating if a row was found and retrieved or not.
        Throws:
        StandardException - Standard exception policy.
      • getUserCreateConglomPropList

        public java.util.Properties getUserCreateConglomPropList()
        A superset of properties that "users" can specify.

        A superset of properties that "users" (ie. from sql) can specify. Store may implement other properties which should not be specified by users. Layers above access may implement properties which are not known at all to Access.

        This list is a superset, as some properties may not be implemented by certain types of conglomerates. For instant an in-memory store may not implement a pageSize property. Or some conglomerates may not support pre-allocation.

        This interface is meant to be used by the SQL parser to do validation of properties passsed to the create table statement, and also by the various user interfaces which present table information back to the user.

        Currently this routine returns the following list: derby.storage.initialPages derby.storage.minimumRecordSize derby.storage.pageReservedSpace derby.storage.pageSize

        Specified by:
        getUserCreateConglomPropList in interface TransactionController
        Returns:
        The superset of properties that "users" can specify.
      • isIdle

        public boolean isIdle()
        Reveals whether the transaction has ever read or written data.
        Specified by:
        isIdle in interface TransactionController
        Returns:
        true If the transaction has never read or written data.
      • createXATransactionFromLocalTransaction

        public java.lang.Object createXATransactionFromLocalTransaction​(int format_id,
                                                                        byte[] global_id,
                                                                        byte[] branch_id)
                                                                 throws StandardException
        Convert a local transaction to a global transaction.

        Get a transaction controller with which to manipulate data within the access manager. Tbis controller allows one to manipulate a global XA conforming transaction.

        Must only be called a previous local transaction was created and exists in the context. Can only be called if the current transaction is in the idle state. Upon return from this call the old tc will be unusable, and all references to it should be dropped (it will have been implicitly destroy()'d by this call.

        The (format_id, global_id, branch_id) triplet is meant to come exactly from a javax.transaction.xa.Xid. We don't use Xid so that the system can be delivered on a non-1.2 vm system and not require the javax classes in the path.

        Specified by:
        createXATransactionFromLocalTransaction in interface TransactionController
        Parameters:
        format_id - the format id part of the Xid - ie. Xid.getFormatId().
        global_id - the global transaction identifier part of XID - ie. Xid.getGlobalTransactionId().
        branch_id - The branch qualifier of the Xid - ie. Xid.getBranchQaulifier()
        Throws:
        StandardException - Standard exception policy.
        See Also:
        TransactionController
      • loadConglomerate

        public long loadConglomerate​(long conglomId,
                                     boolean createConglom,
                                     RowLocationRetRowSource rowSource)
                              throws StandardException
        Bulk load into the conglomerate. Rows being loaded into the conglomerate are not logged.
        Parameters:
        conglomId - The conglomerate Id.
        createConglom - If true, the conglomerate is being created in the same operation as the loadConglomerate. The enables further optimization as recovery does not require page allocation to be logged.
        rowSource - Where the rows come from.
        Returns:
        true The number of rows loaded.
        Throws:
        StandardException - Standard Derby Error Policy
      • loadConglomerate

        public void loadConglomerate​(long conglomId,
                                     RowLocationRetRowSource rowSource)
                              throws StandardException
        Use this for incremental load in the future.
        Parameters:
        conglomId - the conglomerate Id
        rowSource - where the rows to be loaded comes from
        Throws:
        StandardException - Standard Derby Error Policy
      • openConglomerate

        public ConglomerateController openConglomerate​(long conglomId,
                                                       boolean hold,
                                                       int open_mode,
                                                       int lock_level,
                                                       int isolation_level)
                                                throws StandardException
        Description copied from interface: TransactionController
        Open a conglomerate for use.

        The lock level indicates the minimum lock level to get locks at, the underlying conglomerate implementation may actually lock at a higher level (ie. caller may request MODE_RECORD, but the table may be locked at MODE_TABLE instead).

        The close method is on the ConglomerateController interface.

        Specified by:
        openConglomerate in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to open.
        hold - If true, will be maintained open over commits.
        open_mode - Specifiy flags to control opening of table. OPENMODE_FORUPDATE - if set open the table for update otherwise open table shared.
        lock_level - One of (MODE_TABLE, MODE_RECORD).
        isolation_level - The isolation level to lock the conglomerate at. One of (ISOLATION_READ_COMMITTED, ISOLATION_REPEATABLE_READ or ISOLATION_SERIALIZABLE).
        Returns:
        a ConglomerateController to manipulate the conglomerate.
        Throws:
        StandardException - if the conglomerate could not be opened for some reason. Throws SQLState.STORE_CONGLOMERATE_DOES_NOT_EXIST if the conglomId being requested does not exist for some reason (ie. someone has dropped it).
      • findContainerid

        public long findContainerid​(long conglom_id)
                             throws StandardException
        Description copied from interface: TransactionController
        For debugging, find the containerid given the conglomid.

        Will have to change if we ever have more than one container in a conglomerate.

        Specified by:
        findContainerid in interface TransactionController
        Returns:
        the containerid of container implementing conglomerate with "conglomid."
        Throws:
        StandardException - Standard exception policy.
      • createBackingStoreHashtableFromScan

        public BackingStoreHashtable createBackingStoreHashtableFromScan​(long conglomId,
                                                                         int open_mode,
                                                                         int lock_level,
                                                                         int isolation_level,
                                                                         FormatableBitSet scanColumnList,
                                                                         DataValueDescriptor[] startKeyValue,
                                                                         int startSearchOperator,
                                                                         Qualifier[][] qualifier,
                                                                         DataValueDescriptor[] stopKeyValue,
                                                                         int stopSearchOperator,
                                                                         long max_rowcnt,
                                                                         int[] key_column_numbers,
                                                                         boolean remove_duplicates,
                                                                         long estimated_rowcnt,
                                                                         long max_inmemory_rowcnt,
                                                                         int initialCapacity,
                                                                         float loadFactor,
                                                                         boolean collect_runtimestats,
                                                                         boolean skipNullKeyColumns,
                                                                         boolean keepAfterCommit,
                                                                         boolean includeRowLocations)
                                                                  throws StandardException
        Create a BackingStoreHashtable which contains all rows that qualify for the described scan.
        Specified by:
        createBackingStoreHashtableFromScan in interface TransactionController
        Parameters:
        conglomId - see openScan()
        open_mode - see openScan()
        lock_level - see openScan()
        isolation_level - see openScan()
        scanColumnList - see openScan()
        startKeyValue - see openScan()
        startSearchOperator - see openScan()
        qualifier - see openScan()
        stopKeyValue - see openScan()
        stopSearchOperator - see openScan()
        max_rowcnt - The maximum number of rows to insert into the HashSet. Pass in -1 if there is no maximum.
        key_column_numbers - The column numbers of the columns in the scan result row to be the key to the Hashtable. "0" is the first column in the scan result row (which may be different than the first row in the table of the scan).
        remove_duplicates - Should the HashSet automatically remove duplicates, or should it create the Vector of duplicates?
        estimated_rowcnt - The number of rows that the caller estimates will be inserted into the sort. -1 indicates that the caller has no idea. Used by the sort to make good choices about in-memory vs. external sorting, and to size merge runs.
        max_inmemory_rowcnt - The number of rows at which the underlying Hashtable implementation should cut over from an in-memory hash to a disk based access method.
        initialCapacity - If not "-1" used to initialize the java Hashtable.
        loadFactor - If not "-1" used to initialize the java Hashtable.
        collect_runtimestats - If true will collect up runtime stats during scan processing for retrieval by BackingStoreHashtable.getRuntimeStats().
        skipNullKeyColumns - Whether or not to skip rows with 1 or more null key columns
        keepAfterCommit - If true then keep hash table after commit
        includeRowLocations - If true then rows should include RowLocations.
        Returns:
        the BackingStoreHashtable which was created.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        BackingStoreHashtable, TransactionController.openScan(long, boolean, int, int, int, org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.Qualifier[][], org.apache.derby.iapi.types.DataValueDescriptor[], int)
      • openGroupFetchScan

        public GroupFetchScanController openGroupFetchScan​(long conglomId,
                                                           boolean hold,
                                                           int open_mode,
                                                           int lock_level,
                                                           int isolation_level,
                                                           FormatableBitSet scanColumnList,
                                                           DataValueDescriptor[] startKeyValue,
                                                           int startSearchOperator,
                                                           Qualifier[][] qualifier,
                                                           DataValueDescriptor[] stopKeyValue,
                                                           int stopSearchOperator)
                                                    throws StandardException
        Description copied from interface: TransactionController
        Open a scan which gets copies of multiple rows at a time.

        All inputs work exactly as in openScan(). The return is a GroupFetchScanController, which only allows fetches of groups of rows from the conglomerate.

        Specified by:
        openGroupFetchScan in interface TransactionController
        Parameters:
        conglomId - see openScan()
        open_mode - see openScan()
        lock_level - see openScan()
        isolation_level - see openScan()
        scanColumnList - see openScan()
        startKeyValue - see openScan()
        startSearchOperator - see openScan()
        qualifier - see openScan()
        stopKeyValue - see openScan()
        stopSearchOperator - see openScan()
        Returns:
        The GroupFetchScanController to be used to fetch the rows.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        ScanController, GroupFetchScanController
      • purgeConglomerate

        public void purgeConglomerate​(long conglomId)
                               throws StandardException
        Purge all committed deleted rows from the conglomerate.

        This call will purge committed deleted rows from the conglomerate, that space will be available for future inserts into the conglomerate.

        Specified by:
        purgeConglomerate in interface TransactionController
        Parameters:
        conglomId - Id of the conglomerate to purge.
        Throws:
        StandardException - Standard exception policy.
      • compressConglomerate

        public void compressConglomerate​(long conglomId)
                                  throws StandardException
        Return free space from the conglomerate back to the OS.

        Returns free space from the conglomerate back to the OS. Currently only the sequential free pages at the "end" of the conglomerate can be returned to the OS.

        Specified by:
        compressConglomerate in interface TransactionController
        Parameters:
        conglomId - Id of the conglomerate to purge.
        Throws:
        StandardException - Standard exception policy.
      • defragmentConglomerate

        public GroupFetchScanController defragmentConglomerate​(long conglomId,
                                                               boolean online,
                                                               boolean hold,
                                                               int open_mode,
                                                               int lock_level,
                                                               int isolation_level)
                                                        throws StandardException
        Compress table in place.

        Returns a GroupFetchScanController which can be used to move rows around in a table, creating a block of free pages at the end of the table. The process will move rows from the end of the table toward the beginning. The GroupFetchScanController will return the old row location, the new row location, and the actual data of any row moved. Note that this scan only returns moved rows, not an entire set of rows, the scan is designed specifically to be used by either explicit user call of the SYSCS_ONLINE_COMPRESS_TABLE() procedure, or internal background calls to compress the table. The old and new row locations are returned so that the caller can update any indexes necessary. This scan always returns all collumns of the row. All inputs work exactly as in openScan(). The return is a GroupFetchScanController, which only allows fetches of groups of rows from the conglomerate.

        Specified by:
        defragmentConglomerate in interface TransactionController
        Parameters:
        conglomId - see openScan()
        hold - see openScan()
        open_mode - see openScan()
        lock_level - see openScan()
        isolation_level - see openScan()
        Returns:
        The GroupFetchScanController to be used to fetch the rows.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        ScanController, GroupFetchScanController
      • openScan

        public ScanController openScan​(long conglomId,
                                       boolean hold,
                                       int open_mode,
                                       int lock_level,
                                       int isolation_level,
                                       FormatableBitSet scanColumnList,
                                       DataValueDescriptor[] startKeyValue,
                                       int startSearchOperator,
                                       Qualifier[][] qualifier,
                                       DataValueDescriptor[] stopKeyValue,
                                       int stopSearchOperator)
                                throws StandardException
        Description copied from interface: TransactionController
        Open a scan on a conglomerate. The scan will return all rows in the conglomerate which are between the positions defined by {startKeyValue, startSearchOperator} and {stopKeyValue, stopSearchOperator}, which also match the qualifier.

        The way that starting and stopping keys and operators are used may best be described by example. Say there's an ordered conglomerate with two columns, where the 0-th column is named 'x', and the 1st column is named 'y'. The values of the columns are as follows:

                  x: 1 3 4 4 4 5 5 5 6 7 9
                  y: 1 1 2 4 6 2 4 6 1 1 1
                

        A {start key, search op} pair of {{5.2}, GE} would position on {x=5, y=2}, whereas the pair {{5}, GT} would position on {x=6, y=1}.

        Partial keys are used to implement partial key scans in SQL. For example, the SQL "select * from t where x = 5" would open a scan on the conglomerate (or a useful index) of t using a starting position partial key of {{5}, GE} and a stopping position partial key of {{5}, GT}.

        Some more examples:

                +-------------------+------------+-----------+--------------+--------------+
                | predicate         | start key  | stop key  | rows         | rows locked  |
                |                   | value | op | value |op | returned     |serialization |
                +-------------------+-------+----+-------+---+--------------+--------------+
                | x = 5             | {5}   | GE | {5}   |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
                | x > 5             | {5}   | GT | null  |   |{6,1} .. {9,1}|{5,6} .. {9,1}|
                | x >= 5            | {5}   | GE | null  |   |{5,2} .. {9,1}|{4,6} .. {9,1}|
                | x <= 5            | null  |    | {5}   |GT |{1,1} .. {5,6}|first .. {5,6}|
                | x < 5             | null  |    | {5}   |GE |{1,1} .. {4,6}|first .. {4,6}|
                | x >= 5 and x <= 7 | {5},  | GE | {7}   |GT |{5,2} .. {7,1}|{4,6} .. {7,1}|
                | x = 5  and y > 2  | {5,2} | GT | {5}   |GT |{5,4} .. {5,6}|{5,2} .. {5,6}|
                | x = 5  and y >= 2 | {5,2} | GE | {5}   |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
                | x = 5  and y < 5  | {5}   | GE | {5,5} |GE |{5,2} .. {5,4}|{4,6} .. {5,4}|
                | x = 2             | {2}   | GE | {2}   |GT | none         |{1,1} .. {1,1}|
                +-------------------+-------+----+-------+---+--------------+--------------+
                

        As the above table implies, the underlying scan may lock more rows than it returns in order to guarantee serialization.

        For each row which meets the start and stop position, as described above the row is "qualified" to see whether it should be returned. The qualification is a 2 dimensional array of @see Qualifiers, which represents the qualification in conjunctive normal form (CNF). Conjunctive normal form is an "and'd" set of "or'd" Qualifiers.

        For example x = 5 would be represented is pseudo code as: qualifier_cnf[][] = new Qualifier[1]; qualifier_cnf[0] = new Qualifier[1]; qualifier_cnr[0][0] = new Qualifer(x = 5)

        For example (x = 5) or (y = 6) would be represented is pseudo code as: qualifier_cnf[][] = new Qualifier[1]; qualifier_cnf[0] = new Qualifier[2]; qualifier_cnr[0][0] = new Qualifer(x = 5) qualifier_cnr[0][1] = new Qualifer(y = 6)

        For example ((x = 5) or (x = 6)) and ((y = 1) or (y = 2)) would be represented is pseudo code as: qualifier_cnf[][] = new Qualifier[2]; qualifier_cnf[0] = new Qualifier[2]; qualifier_cnr[0][0] = new Qualifer(x = 5) qualifier_cnr[0][1] = new Qualifer(x = 6) qualifier_cnr[0][0] = new Qualifer(y = 5) qualifier_cnr[0][1] = new Qualifer(y = 6)

        For each row the CNF qualfier is processed and it is determined whether or not the row should be returned to the caller. The following pseudo-code describes how this is done:

            if (qualifier != null)
            {
                
                        for (int and_clause; and_clause < qualifier.length; and_clause++)
                        {
                    boolean or_qualifies = false;
        
                    for (int or_clause; or_clause < qualifier[and_clause].length; or_clause++)
                    {
                        
                        DataValueDescriptor key     = 
                            qualifier[and_clause][or_clause].getOrderable();
        
                        DataValueDescriptor row_col = 
                            get row column[qualifier[and_clause][or_clause].getColumnId()];
        
                        boolean or_qualifies = 
                        row_col.compare(qualifier[i].getOperator,
                        
                        key,
                        qualifier[i].getOrderedNulls,
                        qualifier[i].getUnknownRV);
                        
        if (or_qualifies) { break; } } if (!or_qualifies) {
                        don't return this row to the client - proceed to next row;
                        
        }
        }
        }
        Specified by:
        openScan in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to open the scan for.
        hold - If true, this scan will be maintained open over commits.
        open_mode - Specifiy flags to control opening of table. OPENMODE_FORUPDATE - if set open the table for update otherwise open table shared.
        lock_level - One of (MODE_TABLE, MODE_RECORD).
        isolation_level - The isolation level to lock the conglomerate at. One of (ISOLATION_READ_COMMITTED, ISOLATION_REPEATABLE_READ or ISOLATION_SERIALIZABLE).
        scanColumnList - A description of which columns to return from every fetch in the scan. template, and scanColumnList work together to describe the row to be returned by the scan - see RowUtil for description of how these three parameters work together to describe a "row".
        startKeyValue - An indexable row which holds a (partial) key value which, in combination with the startSearchOperator, defines the starting position of the scan. If null, the starting position of the scan is the first row of the conglomerate. The startKeyValue must only reference columns included in the scanColumnList.
        startSearchOperator - an operator which defines how the startKeyValue is to be searched for. If startSearchOperation is ScanController.GE, the scan starts on the first row which is greater than or equal to the startKeyValue. If startSearchOperation is ScanController.GT, the scan starts on the first row whose key is greater than startKeyValue. The startSearchOperation parameter is ignored if the startKeyValue parameter is null.
        qualifier - A 2 dimensional array encoding a conjunctive normal form (CNF) datastructure of of qualifiers which, applied to each key, restrict the rows returned by the scan. Rows for which the CNF expression returns false are not returned by the scan. If null, all rows are returned. Qualifiers can only reference columns which are included in the scanColumnList. The column id that a qualifier returns is the column id the table, not the column id in the partial row being returned. For detailed description of 2-dimensional array passing @see Qualifier
        stopKeyValue - An indexable row which holds a (partial) key value which, in combination with the stopSearchOperator, defines the ending position of the scan. If null, the ending position of the scan is the last row of the conglomerate. The stopKeyValue must only reference columns included in the scanColumnList.
        stopSearchOperator - an operator which defines how the stopKeyValue is used to determine the scan stopping position. If stopSearchOperation is ScanController.GE, the scan stops just before the first row which is greater than or equal to the stopKeyValue. If stopSearchOperation is ScanController.GT, the scan stops just before the first row whose key is greater than startKeyValue. The stopSearchOperation parameter is ignored if the stopKeyValue parameter is null.
        Throws:
        StandardException - if the scan could not be opened for some reason. Throws SQLState.STORE_CONGLOMERATE_DOES_NOT_EXIST if the conglomId being requested does not exist for some reason (ie. someone has dropped it).
        See Also:
        RowUtil, ScanController
      • openStoreCost

        public StoreCostController openStoreCost​(long conglomId)
                                          throws StandardException
        Return an open StoreCostController for the given conglomid.

        Return an open StoreCostController which can be used to ask about the estimated row counts and costs of ScanController and ConglomerateController operations, on the given conglomerate.

        Specified by:
        openStoreCost in interface TransactionController
        Parameters:
        conglomId - The identifier of the conglomerate to open.
        Returns:
        The open StoreCostController.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        StoreCostController
      • createSort

        public long createSort​(java.util.Properties implParameters,
                               DataValueDescriptor[] template,
                               ColumnOrdering[] columnOrdering,
                               SortObserver sortObserver,
                               boolean alreadyInOrder,
                               long estimatedRows,
                               int estimatedRowSize)
                        throws StandardException
        Description copied from interface: TransactionController
        Create a sort. Rows are inserted into the sort with a sort controller, and subsequently retrieved with a sort scan controller. The rows come out in the order specified by the parameters.

        Sorts also do aggregation. The input (unaggregated) rows have the same format as the aggregated rows, and the aggregate results are part of the both rows. The sorter, when it notices that a row is a duplicate of another, calls a user-supplied aggregation method (see interface Aggregator), passing it both rows. One row is known as the 'addend' and the other the 'accumulator'. The aggregation method is assumed to merge the addend into the accumulator. The sort then discards the addend row.

        So, for the query:

        select a, sum(b) from t group by a
        The input row to the sorter would have one column for a and another column for sum(b). It is up to the caller to get the format of the row correct, and to initialize the aggregate values correctly (null for most aggregates, 0 for count).

        Nulls are always considered to be ordered in a sort, that is, null compares equal to null, and less than anything else.

        Specified by:
        createSort in interface TransactionController
        Parameters:
        implParameters - Properties which help in choosing implementation-specific sort options. If null, a "generally useful" sort will be used.
        template - A row which is prototypical for the sort. All rows inserted into the sort controller must have exactly the same number of columns as the template row. Every column in an inserted row must have the same type as the corresponding column in the template.
        columnOrdering - An array which specifies which columns participate in ordering - see interface ColumnOrdering for details. The column referenced in the 0th columnOrdering object is compared first, then the 1st, etc. To sort on a single column specify an array with a single entry.
        sortObserver - An object that is used to observe the sort. It is used to provide a callback into the sorter. If the sortObserver is null, then the sort proceeds as normal. If the sortObserver is non null, then it is called as rows are loaded into the sorter. It can be used to implement a distinct sort, aggregates, etc.
        alreadyInOrder - Indicates that the rows inserted into the sort controller will already be in order. This is used to perform aggregation only.
        estimatedRows - The number of rows that the caller estimates will be inserted into the sort. -1 indicates that the caller has no idea. Used by the sort to make good choices about in-memory vs. external sorting, and to size merge runs.
        estimatedRowSize - The estimated average row size of the rows being sorted. This is the client portion of the rowsize, it should not attempt to calculate Store's overhead. -1 indicates that the caller has no idea (and the sorter will use 100 bytes in that case. Used by the sort to make good choices about in-memory vs. external sorting, and to size merge runs. The client is not expected to estimate the per column/ per row overhead of raw store, just to make a guess about the storage associated with each row (ie. reasonable estimates for some implementations would be 4 for int, 8 for long, 102 for char(100), 202 for varchar(200), a number out of hat for user types, ...).
        Returns:
        The sort identifier which can be used subsequently to open sort controllers and scans.
        Throws:
        StandardException - Standard error policy.
        See Also:
        TransactionController.createSort(java.util.Properties, org.apache.derby.iapi.types.DataValueDescriptor[], org.apache.derby.iapi.store.access.ColumnOrdering[], org.apache.derby.iapi.store.access.SortObserver, boolean, long, int)
      • dropSort

        public void dropSort​(long sortid)
                      throws StandardException
        Drop a sort.

        Drop a sort created by a call to createSort() within the current transaction (sorts are automatically "dropped" at the end of a transaction. This call should only be made after all openSortScan()'s and openSort()'s have been closed.

        Specified by:
        dropSort in interface TransactionController
        Parameters:
        sortid - The identifier of the sort to drop, as returned from createSort.
        Throws:
        StandardException - From a lower-level exception.
      • getProperty

        public java.io.Serializable getProperty​(java.lang.String key)
                                         throws StandardException
        Description copied from interface: PersistentSet
        Gets a value for a stored property. The returned value will be:
        1. the de-serialized object associated with the key using setProperty if such a value is defined or
        2. the default de-serialized object associated with the key using setPropertyDefault if such a value is defined or
        3. null

        The Store provides a transaction protected list of database properties. Higher levels of the system can store and retrieve these properties once Recovery has finished. Each property is a serializable object and is stored/retrieved using a String key.

        Specified by:
        getProperty in interface PersistentSet
        Parameters:
        key - The "key" of the property that is being requested.
        Returns:
        object The requested object or null.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        PersistentSet.getProperty(java.lang.String)
      • getPropertyDefault

        public java.io.Serializable getPropertyDefault​(java.lang.String key)
                                                throws StandardException
        Description copied from interface: PersistentSet
        Gets a default value for a stored property. The returned value will be:
        1. the default de-serialized object associated with the key using setPropertyDefault if such a value is defined or
        2. null

        The Store provides a transaction protected list of database properties. Higher levels of the system can store and retrieve these properties once Recovery has finished. Each property is a serializable object and is stored/retrieved using a String key.

        Specified by:
        getPropertyDefault in interface PersistentSet
        Parameters:
        key - The "key" of the property that is being requested.
        Returns:
        object The requested object or null.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        PersistentSet.getPropertyDefault(java.lang.String)
      • setProperty

        public void setProperty​(java.lang.String key,
                                java.io.Serializable value,
                                boolean dbOnlyProperty)
                         throws StandardException
        Description copied from interface: PersistentSet
        Sets the Serializable object associated with a property key.

        See the discussion of getProperty().

        The value stored may be a Formatable object or a Serializable object whose class name starts with java.*. This stops arbitary objects being stored in the database by class name, which will cause problems in obfuscated/non-obfuscated systems.

        Specified by:
        setProperty in interface PersistentSet
        Parameters:
        key - The key used to lookup this property.
        value - The value to be associated with this key. If null, delete the property from the properties list.
        dbOnlyProperty - True if property is only ever searched for int the database properties.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        PersistentSet.setProperty(java.lang.String, java.io.Serializable, boolean)
      • setPropertyDefault

        public void setPropertyDefault​(java.lang.String key,
                                       java.io.Serializable value)
                                throws StandardException
        Description copied from interface: PersistentSet
        Sets the Serializable object default value associated with a property key.

        See the discussion of getProperty().

        The value stored may be a Formatable object or a Serializable object whose class name starts with java.*. This stops arbitary objects being stored in the database by class name, which will cause problems in obfuscated/non-obfuscated systems.

        Specified by:
        setPropertyDefault in interface PersistentSet
        Parameters:
        key - The key used to lookup this propertyDefault.
        value - The default value to be associated with this key. If null, delete the property default from the properties list.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        PersistentSet.setProperty(java.lang.String, java.io.Serializable, boolean)
      • getProperties

        public java.util.Properties getProperties()
                                           throws StandardException
        Description copied from interface: PersistentSet
        Get properties that can be stored in a java.util.Properties object.

        Get the sub-set of stored properties that can be stored in a java.util.Properties object. That is all the properties that have a value of type java.lang.String. Changes to this properties object are not reflected in any persisent storage.

        Code must use the setProperty() method call.

        Specified by:
        getProperties in interface PersistentSet
        Returns:
        The sub-set of stored properties that can be stored in a java.util.Propertes object.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        PersistentSet.getProperties()
      • openSort

        public SortController openSort​(long id)
                                throws StandardException
        Description copied from interface: TransactionController
        Open a sort controller for a sort previously created in this transaction. Sort controllers are used to insert rows into the sort.

        There may (in the future) be multiple sort inserters for a given sort, the idea being that the various threads of a parallel query plan can all insert into the sort. For now, however, only a single sort controller per sort is supported.

        Specified by:
        openSort in interface TransactionController
        Parameters:
        id - The identifier of the sort to open, as returned from createSort.
        Returns:
        A sort controller to use for inserting.
        Throws:
        StandardException - Standard error policy.
        See Also:
        TransactionController.openSort(long)
      • openSortScan

        public ScanController openSortScan​(long id,
                                           boolean hold)
                                    throws StandardException
        Description copied from interface: TransactionController
        Open a scan for retrieving rows from a sort. Returns a scan controller for retrieving rows from the sort (NOTE: the only legal methods to use on the returned sort controller are next() and fetch() - probably there should be scan controllers and updatable scan controllers).

        In the future, multiple sort scans on the same sort will be supported (for parallel execution across a uniqueness sort in which the order of the resulting rows is not important). Currently, only a single sort scan is allowed per sort.

        In the future, it will be possible to open a sort scan and start retrieving rows before the last row is inserted. The sort controller would block till rows were available to return. Currently, an attempt to retrieve a row before the sort controller is closed will cause an exception.

        Specified by:
        openSortScan in interface TransactionController
        Parameters:
        id - The identifier of the sort to scan, as returned from createSort.
        hold - If true, this scan will be maintained open over commits.
        Returns:
        The sort controller.
        Throws:
        StandardException - Standard error policy.
        See Also:
        TransactionController.openSortScan(long, boolean)
      • commit

        public void commit()
                    throws StandardException
        Description copied from interface: TransactionController
        Commit this transaction. All savepoints within this transaction are released. All non-held conglomerates and scans are closed.
        Specified by:
        commit in interface TransactionController
        Throws:
        StandardException - Only exceptions with severities greater than ExceptionSeverity.TRANSACTION_SEVERITY will be thrown. If an exception is thrown, the transaction will not (necessarily) have been aborted. The standard error handling mechanism is expected to do the appropriate cleanup. In other words, if commit() encounters an error, the exception is propagated up to the the standard exception handler, which initiates cleanupOnError() processing, which will eventually abort the transaction.
      • commitNoSync

        public DatabaseInstant commitNoSync​(int commitflag)
                                     throws StandardException
        Description copied from interface: TransactionController
        "Commit" this transaction without sync'ing the log. Everything else is identical to commit(), use this at your own risk.
        bits in the commitflag can turn on to fine tuned the "commit": KEEP_LOCKS - no locks will be released by the commit and no post commit processing will be initiated. If, for some reasons, the locks cannot be kept even if this flag is set, then the commit will sync the log, i.e., it will revert to the normal commit. READONLY_TRANSACTION_INITIALIZATION - Special case used for processing while creating the transaction. Should only be used by the system while creating the transaction to commit readonly work that may have been done using the transaction while getting it setup to be used by the user. In the future we should instead use a separate tranaction to do this initialization. Will fail if called on a transaction which has done any updates.
        Specified by:
        commitNoSync in interface TransactionController
        Throws:
        StandardException - Only exceptions with severities greater than ExceptionSeverity.TRANSACTION_SEVERITY will be thrown. If an exception is thrown, the transaction will not (necessarily) have been aborted. The standard error handling mechanism is expected to do the appropriate cleanup. In other words, if commit() encounters an error, the exception is propagated up to the the standard exception handler, which initiates cleanupOnError() processing, which will eventually abort the transaction.
        See Also:
        TransactionController.commit()
      • abort

        public void abort()
                   throws StandardException
        Description copied from interface: TransactionController
        Abort all changes made by this transaction since the last commit, abort or the point the transaction was started, whichever is the most recent. All savepoints within this transaction are released, and all resources are released (held or non-held).
        Specified by:
        abort in interface TransactionController
        Throws:
        StandardException - Only exceptions with severities greater than ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
      • getContextManager

        public ContextManager getContextManager()
        Get the context manager that the transaction was created with.

        Specified by:
        getContextManager in interface TransactionController
        Returns:
        The context manager that the transaction was created with.
      • setSavePoint

        public int setSavePoint​(java.lang.String name,
                                java.lang.Object kindOfSavepoint)
                         throws StandardException
        Description copied from interface: TransactionController
        Set a save point in the current transaction. A save point defines a point in time in the transaction that changes can be rolled back to. Savepoints can be nested and they behave like a stack. Setting save points "one" and "two" and the rolling back "one" will rollback all the changes made since "one" (including those made since "two") and release savepoint "two".
        Specified by:
        setSavePoint in interface TransactionController
        Parameters:
        name - The user provided name of the savepoint.
        kindOfSavepoint - A NULL value means it is an internal savepoint (ie not a user defined savepoint) Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint A String value for kindOfSavepoint would mean it is SQL savepoint A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
        Returns:
        returns savepoint position in the stack.
        Throws:
        StandardException - Standard Derby exception policy. A statement level exception is thrown if no savepoint exists with the given name.
      • releaseSavePoint

        public int releaseSavePoint​(java.lang.String name,
                                    java.lang.Object kindOfSavepoint)
                             throws StandardException
        Description copied from interface: TransactionController
        Release the save point of the given name. Releasing a savepoint removes all knowledge from this transaction of the named savepoint and any savepoints set since the named savepoint was set.
        Specified by:
        releaseSavePoint in interface TransactionController
        Parameters:
        name - The user provided name of the savepoint, set by the user in the setSavePoint() call.
        kindOfSavepoint - A NULL value means it is an internal savepoint (ie not a user defined savepoint) Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint A String value for kindOfSavepoint would mean it is SQL savepoint A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
        Returns:
        returns savepoint position in the stack.
        Throws:
        StandardException - Standard Derby exception policy. A statement level exception is thrown if no savepoint exists with the given name.
      • rollbackToSavePoint

        public int rollbackToSavePoint​(java.lang.String name,
                                       boolean close_controllers,
                                       java.lang.Object kindOfSavepoint)
                                throws StandardException
        Description copied from interface: TransactionController
        Rollback all changes made since the named savepoint was set. The named savepoint is not released, it remains valid within this transaction, and thus can be named it future rollbackToSavePoint() calls. Any savepoints set since this named savepoint are released (and their changes rolled back).

        if "close_controllers" is true then all conglomerates and scans are closed (held or non-held).

        If "close_controllers" is false then no cleanup is done by the TransactionController. It is then the responsibility of the caller to close all resources that may have been affected by the statements backed out by the call. This option is meant to be used by the Language implementation of statement level backout, where the system "knows" what could be affected by the scope of the statements executed within the statement.

        Specified by:
        rollbackToSavePoint in interface TransactionController
        Parameters:
        name - The identifier of the SavePoint to roll back to.
        close_controllers - boolean indicating whether or not the controller should close open controllers.
        kindOfSavepoint - A NULL value means it is an internal savepoint (ie not a user defined savepoint) Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint A String value for kindOfSavepoint would mean it is SQL savepoint A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
        Returns:
        returns savepoint position in the stack.
        Throws:
        StandardException - Standard Derby exception policy. A statement level exception is thrown if no savepoint exists with the given name.
      • xa_commit

        public void xa_commit​(boolean onePhase)
                       throws StandardException
        This method is called to commit the current XA global transaction.

        RESOLVE - how do we map to the "right" XAExceptions.

        Specified by:
        xa_commit in interface XATransactionController
        Parameters:
        onePhase - If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of current xid.
        Throws:
        StandardException - Standard exception policy.
      • xa_prepare

        public int xa_prepare()
                       throws StandardException
        This method is called to ask the resource manager to prepare for a transaction commit of the transaction specified in xid.

        Specified by:
        xa_prepare in interface XATransactionController
        Returns:
        A value indicating the resource manager's vote on the the outcome of the transaction. The possible values are: XA_RDONLY or XA_OK. If the resource manager wants to roll back the transaction, it should do so by throwing an appropriate XAException in the prepare method.
        Throws:
        StandardException - Standard exception policy.
      • xa_rollback

        public void xa_rollback()
                         throws StandardException
        rollback the current global transaction.

        The given transaction is roll'ed back and it's history is not maintained in the transaction table or long term log.

        Specified by:
        xa_rollback in interface XATransactionController
        Throws:
        StandardException - Standard exception policy.
      • addPostCommitWork

        public void addPostCommitWork​(Serviceable work)
        Add to the list of post commit work.

        Add to the list of post commit work that may be processed after this transaction commits. If this transaction aborts, then the post commit work list will be thrown away. No post commit work will be taken out on a rollback to save point.

        This routine simply delegates the work to the Rawstore transaction.

        Specified by:
        addPostCommitWork in interface TransactionManager
        Parameters:
        work - The post commit work to do.
      • checkVersion

        public boolean checkVersion​(int requiredMajorVersion,
                                    int requiredMinorVersion,
                                    java.lang.String feature)
                             throws StandardException
        Check to see if a database has been upgraded to the required level in order to use a store feature.
        Specified by:
        checkVersion in interface TransactionManager
        Parameters:
        requiredMajorVersion - required database Engine major version
        requiredMinorVersion - required database Engine minor version
        feature - Non-null to throw an exception, null to return the state of the version match.
        Returns:
        true if the database has been upgraded to the required level, false otherwise.
        Throws:
        StandardException - if the database is not at the require version when feature feature is not null .
      • closeMe

        public void closeMe​(ConglomerateController conglom_control)
        The ConglomerateController.close() method has been called on "conglom_control".

        Take whatever cleanup action is appropriate to a closed conglomerateController. It is likely this routine will remove references to the ConglomerateController object that it was maintaining for cleanup purposes.

        Specified by:
        closeMe in interface TransactionManager
      • closeMe

        public void closeMe​(SortController sort_control)
        The SortController.close() method has been called on "sort_control".

        Take whatever cleanup action is appropriate to a closed sortController. It is likely this routine will remove references to the SortController object that it was maintaining for cleanup purposes.

        Specified by:
        closeMe in interface TransactionManager
      • closeMe

        public void closeMe​(ScanManager scan)
        The ScanManager.close() method has been called on "scan".

        Take whatever cleanup action is appropriate to a closed scan. It is likely this routine will remove references to the scan object that it was maintaining for cleanup purposes.

        Specified by:
        closeMe in interface TransactionManager
      • getAccessManager

        public AccessFactory getAccessManager()
        Get reference to access factory which started this transaction.

        Specified by:
        getAccessManager in interface TransactionController
        Returns:
        The AccessFactory which started this transaction.
      • getInternalTransaction

        public TransactionManager getInternalTransaction()
                                                  throws StandardException
        Get an Internal transaction.

        Start an internal transaction. An internal transaction is a completely separate transaction from the current user transaction. All work done in the internal transaction must be physical (ie. it can be undone physically by the rawstore at the page level, rather than logically undone like btree insert/delete operations). The rawstore guarantee's that in the case of a system failure all open Internal transactions are first undone in reverse order, and then other transactions are undone in reverse order.

        Internal transactions are meant to implement operations which, if interupted before completion will cause logical operations like tree searches to fail. This special undo order insures that the state of the tree is restored to a consistent state before any logical undo operation which may need to search the tree is performed.

        Specified by:
        getInternalTransaction in interface TransactionManager
        Returns:
        The new internal transaction.
        Throws:
        StandardException - Standard exception policy.
      • startNestedUserTransaction

        public TransactionController startNestedUserTransaction​(boolean readOnly,
                                                                boolean flush_log_on_xact_end)
                                                         throws StandardException
        Get an nested user transaction.

        A nested user can be used exactly as any other TransactionController, except as follows. For this discussion let the parent transaction be the transaction used to make the getNestedUserTransaction(), and let the child transaction be the transaction returned by the getNestedUserTransaction() call.

        The nesting is limited to one level deep. An exception will be thrown if a subsequent getNestedUserTransaction() is called on the child transaction.

        The locks in the child transaction will be compatible with the locks of the parent transaction.

        A commit in the child transaction will release locks associated with the child transaction only, work can continue in the parent transaction at this point.

        Any abort of the child transaction will result in an abort of both the child transaction and parent transaction.

        A TransactionController.destroy() call should be made on the child transaction once all child work is done, and the caller wishes to continue work in the parent transaction.

        Nested internal transactions are meant to be used to implement system work necessary to commit as part of implementing a user's request, but where holding the lock for the duration of the user transaction is not acceptable. 2 examples of this are system catalog read locks accumulated while compiling a plan, and auto-increment.

        Specified by:
        startNestedUserTransaction in interface TransactionController
        Parameters:
        readOnly - Is transaction readonly? Only 1 non-read only nested transaction is allowed per transaction.
        flush_log_on_xact_end - By default should the transaction commit and abort be synced to the log. Normal usage should pick true, unless there is specific performance need and usage works correctly if a commit can be lost on system crash.
        Returns:
        The new nested user transaction.
        Throws:
        StandardException - Standard exception policy.
      • getRawStoreXact

        public Transaction getRawStoreXact()
        Get the Transaction from the Transaction manager.

        Access methods often need direct access to the "Transaction" - ie. the raw store transaction, so give access to it.

        Specified by:
        getRawStoreXact in interface TransactionManager
        Returns:
        The raw store transaction.
      • getLockSpace

        public CompatibilitySpace getLockSpace()
        Return an object that when used as the compatibility space, and the object returned when calling getOwner() on that object is used as group for a lock request, guarantees that the lock will be removed on a commit or an abort.
        Specified by:
        getLockSpace in interface TransactionController
      • setNoLockWait

        public void setNoLockWait​(boolean noWait)
        Tell this transaction whether it should time out immediately if a lock cannot be granted without waiting. This mechanism can for instance be used if an operation is first attempted in a nested transaction to reduce the lifetime of locks held in the system tables (like when a stored prepared statement is compiled and stored). In such a case, the caller must catch timeout exceptions and retry the operation in the main transaction if a lock timeout occurs.

        For now, this only works if the transaction has its own compatibility space. If it has inherited the compatibility space from its parent, the request will be ignored (or cause a failure in debug builds).

        Specified by:
        setNoLockWait in interface TransactionController
        Parameters:
        noWait - if true never wait for a lock in this transaction, but time out immediately
        See Also:
        LockOwner.noWait(), Transaction.setNoLockWait(boolean)
      • getTransactionIdString

        public java.lang.String getTransactionIdString()
        Get string id of the transaction.

        This transaction "name" will be the same id which is returned in the TransactionInfo information, used by the lock and transaction vti's to identify transactions.

        Although implementation specific, the transaction id is usually a number which is bumped every time a commit or abort is issued.

        For now return the toString() method, which does what we want. Later if that is not good enough we can add public raw tran interfaces to get exactly what we want.

        Specified by:
        getTransactionIdString in interface TransactionController
        Returns:
        The a string which identifies the transaction.
      • getActiveStateTxIdString

        public java.lang.String getActiveStateTxIdString()
        Get string id of the transaction that would be when the Transaction is IN active state.
        Specified by:
        getActiveStateTxIdString in interface TransactionController
        Returns:
        The string which identifies the transaction.
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object