transactioncontroller.java

derby database source code.good for you.

    the b-tree secondary index will assume holds a @see RowLocation of
    the base row in the base conglomerate.  This value will be used
    for acquiring locks.  In this implementation RowLocationColumn must be 
    the last key column.
    This property is required.
    <LI>"allowDuplicates" (boolean).  If set to true the table will allow 
    rows which are duplicate in key column's 0 through (nUniqueColumns - 1).
    Currently only supports "false".
    This property is optional, defaults to false.
    <LI>"nKeyFields"  (integer) Columns 0 through (nKeyFields - 1) will be 
    included in key of the conglomerate.
    This implementation requires that "nKeyFields" must be the same as the
    number of fields in the conglomerate, including the rowLocationColumn.
    Other implementations may relax this restriction to allow non-key fields
    in the index.
    This property is required.
    <LI>"nUniqueColumns" (integer) Columns 0 through "nUniqueColumns" will be 
    used to check for uniqueness.  So for a standard SQL non-unique index 
    implementation set "nUniqueColumns" to the same value as "nKeyFields"; and
    for a unique index set "nUniqueColumns" to "nKeyFields - 1 (ie. don't 
    include the rowLocationColumn in the uniqueness check).
    This property is required.
    <LI>"maintainParentLinks" (boolean)
    Whether the b-tree pages maintain the page number of their parent.  Only
    used for consistency checking.  It takes a certain amount more effort to
    maintain these links, but they're really handy for ensuring that the index
    is consistent.
    This property is optional, defaults to true.
    </UL>

    A secondary index i (a, b) on table t (a, b, c) would have rows
    which looked like (a, b, row_location).  baseConglomerateId is set to the
    conglomerate id of t.  rowLocationColumns is set to 2.  allowsDuplicates
    would be set to false.  To create a unique
    secondary index set uniquenessColumns to 2, this means that the btree
    code will compare the key values but not the row id when determing
    uniqueness.  To create a nonunique secondary index set uniquenessColumns
    to 3, this would mean that the uniqueness test would include the row
    location and since all row locations will be unique  all rows inserted
    into the index will be differentiated (at least) by row location.

	@return The identifier to be used to open the conglomerate later.

    @param 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.

    @param 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.

	@param 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.


	@param properties Implementation-specific properties of the
	conglomerate.  

    @param  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 cloudscape reboots, all temporary
	conglomerates are removed.

	@exception  StandardException  if the conglomerate could
	not be created for some reason.
    **/
    long createConglomerate(
    String                  implementation,
    DataValueDescriptor[]   template,
    ColumnOrdering[]        columnOrder,
    Properties              properties,
    int                     temporaryFlag)
		throws StandardException;

	/**
	Create a conglomerate and load (filled) it with rows that comes from the
	row source without loggging.  

 	<p>Individual rows that are loaded into the conglomerate are not
 	logged. After this operation, the underlying database must be backed up
 	with a database backup rather than an transaction log backup (when we have
 	them). This warning is put here for the benefit of future generation.

	<p>
	This function behaves the same as @see createConglomerate except it also
	populates the conglomerate with rows from the row source and the rows that
	are inserted are not logged.

    @param 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.

	@param rowSource the interface to recieve rows to load into the
	conglomerate. 

	@param rowCount - if not null the number of rows loaded into the table
	will be returned as the first element of the array.

	@exception StandardException if the conglomerate could not be created or
	loaded for some reason.  Throws 
    SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION if
	the conglomerate supports uniqueness checks and has been created to
	disallow duplicates, and one of the rows being loaded had key columns which
	were duplicate of a row already in the conglomerate.
	**/
    long createAndLoadConglomerate(
    String                  implementation,
    DataValueDescriptor[]   template,
	ColumnOrdering[]		columnOrder,
    Properties              properties,
    int                     temporaryFlag,
    RowLocationRetRowSource rowSource,
	long[] rowCount)
    throws StandardException;

	/**
    Recreate a conglomerate and possibly load it with new rows that come from
    the new row source.

	<p>
	This function behaves the same as @see createConglomerate except it also
	populates the conglomerate with rows from the row source and the rows that
	are inserted are not logged.

	<p>Individual rows that are loaded into the conglomerate are not
	logged. After this operation, the underlying database must be backed up
	with a database backup rather than an transaction log backup (when we have
	them). This warning is put here for the benefit of future generation.

    @param 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.

    @param 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.

    @param 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.

	@param 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.

	@param properties Implementation-specific properties of the conglomerate.  

    @param  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.

	@param orig_conglomId The conglomid of the original conglomerate.

	@param rowSource interface to receive rows to load into the conglomerate. 

	@param rowCount - if not null the number of rows loaded into the table
	will be returned as the first element of the array.

    @exception StandardException if the conglomerate could not be created or
	loaded for some reason.  Throws 
    SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION if
	the conglomerate supports uniqueness checks and has been created to
	disallow duplicates, and one of the rows being loaded had key columns which
	were duplicate of a row already in the conglomerate.
	**/
    long recreateAndLoadConglomerate(
    String                  implementation,
    boolean                 recreate_ifempty,
    DataValueDescriptor[]   template,
	ColumnOrdering[]		columnOrder,
    Properties              properties,
    int			            temporaryFlag,
    long                    orig_conglomId,
    RowLocationRetRowSource rowSource,
	long[] rowCount
	)
        throws StandardException;

    /**
    Add a column to a conglomerate.  
    
    The Storage system will block this action until it can get an exclusive
    container level lock on the conglomerate.  The conglomerate must not be
    open in the current transaction, this means that within the current 
    transaction there must be no open ConglomerateController's or 
    ScanControllers.  It may not be possible in some implementations of the
    system to catch this error in the store, so it is up to the caller to 
    insure this.

    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".

	@param conglomId        The identifier of the conglomerate to alter.
	@param column_id        The column number to add this column at.
	@param template_column  An instance of the column to be added to table.

	@exception 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.
    **/
    public void addColumnToConglomerate(
    long        conglomId, 
    int         column_id, 
    Storable    template_column)
		throws StandardException;


    /**
    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.

	@param conglomId The identifier of the conglomerate to drop.

	@exception StandardException if the conglomerate could not be
	 dropped for some reason.
    **/
    void dropConglomerate(long conglomId)
		throws StandardException;

    /**
     * For debugging, find the conglomid given the containerid.
     * <p>
     *
	 * @return the conglomid, which contains the container with containerid.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    long findConglomid(long containerid)
		throws StandardException;

    /**
     * For debugging, find the containerid given the conglomid.
     * <p>
     * Will have to change if we ever have more than one container in 
     * a conglomerate.
     *
	 * @return the containerid of container implementing conglomerate with 
     *             "conglomid."
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    long findContainerid(long conglomid)
		throws StandardException;

    /**
     * Get an nested user transaction.
     * <p>
     * A nested user transaction can be used exactly as any other 
     * TransactionController, except as follows.  For this discussion let the