transactioncontroller.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.iapi.store.access.TransactionController

   Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 */

package org.apache.derby.iapi.store.access;

import java.util.Properties;

import java.io.Serializable;

import org.apache.derby.iapi.services.context.ContextManager;
import org.apache.derby.iapi.services.property.PersistentSet;
import org.apache.derby.iapi.services.io.Storable;

import org.apache.derby.iapi.error.StandardException;

import org.apache.derby.iapi.store.raw.Loggable;
import org.apache.derby.iapi.store.raw.Transaction;

import org.apache.derby.iapi.types.DataValueDescriptor;

import org.apache.derby.iapi.store.access.BackingStoreHashtable;
import org.apache.derby.iapi.services.io.FormatableBitSet;

import org.apache.derby.iapi.store.access.DatabaseInstant;
import org.apache.derby.iapi.error.ExceptionSeverity;
/**

The TransactionController interface provides methods that an access client
can use to control a transaction, which include the methods for
gaining access to resources (conglomerates, scans, etc.) in the transaction
controller's storage manager.  TransactionControllers are obtained
from an AccessFactory via the getTransaction method.
<P>
Each transaction controller is associated with a transaction context which
provides error cleanup when standard exceptions are thrown anywhere in the
system.  The transaction context performs the following actions in response
to cleanupOnError:
<UL>
<LI>
If the error is an instance of StandardException that has a severity less
than ExceptionSeverity.TRANSACTION_SEVERITY all resources remain unaffected.
<LI>
If the error is an instance of StandardException that has a severity equal
to ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released.  An attempt
to use any resource obtained from this transaction controller after
such an error will result in an error.  The transaction controller itself remains
valid, however.
<LI>
If the error is an instance of StandardException that has a severity greater
than ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released and the
context is popped from the stack.  Attempting to use this controller or any
resources obtained from it will result in an error.
</UL>
Transactions are obtained from an AccessFactory.
@see AccessFactory#getTransaction
@see org.apache.derby.iapi.error.StandardException
@see PersistentSet


**/

public interface TransactionController
    extends PersistentSet
{

    /**
     * Constant used for the lock_level argument to openConglomerate() and 
     * openScan() calls.  Pass in MODE_RECORD if you want the conglomerate
     * to be opened with record level locking (but the system may override
     * this choice and provide table level locking instead).  
     **/
	static final int MODE_RECORD    = 6;
    /**
     * Constant used for the lock_level argument to openConglomerate() and 
     * openScan() calls.  Pass in MODE_TABLE if you want the conglomerate
     * to be opened with table level locking - if this mode is passed in the
     * system will never use record level locking for the open scan or 
     * controller.
     **/
	static final int MODE_TABLE     = 7;

    /**
     * Constants used for the isolation_level argument to openConglomerate() and
     * openScan() calls.
     **/

    /**
     * 
     * No locks are requested for data that is read only.  Uncommitted data
     * may be returned.  Writes only visible previous to commit.
     * Exclusive transaction length locks are set on data that is written, no
     * lock is set on data that is read.  No table level intent lock is held
     * so it is up to caller to insure that table is not dropped while being
     * accessed (RESOLVE - this issue may need to be resolved differently if
     * we can't figure out a non-locked based way to prevent ddl during
     * read uncommitted access).
     *
     * ONLY USED INTERNALLY BY ACCESS, NOT VALID FOR EXTERNAL USERS.
     **/
	static final int ISOLATION_NOLOCK = 0;

    /**
     * No locks are requested for data that is read only.  Uncommitted data
     * may be returned.  Writes only visible previous to commit.
     * Exclusive transaction length locks are set on data that is written, no
     * lock is set on data that is read.  No table level intent lock is held
     * so it is up to caller to insure that table is not dropped while being
     * accessed (RESOLVE - this issue may need to be resolved differently if
     * we can't figure out a non-locked based way to prevent ddl during
     * read uncommitted access).
     *
     * Note that this is currently only supported in heap scans.
     *
     * TODO - work in progress to support this locking mode in the 5.1 
     * storage system.  
     **/
	static final int ISOLATION_READ_UNCOMMITTED = 1;

    /**
     * No lost updates, no dirty reads, only committed data is returned.  
     * Writes only visible when committed.  Exclusive transaction
     * length locks are set on data that is written, short term locks (
     * possibly instantaneous duration locks) are set
     * on data that is read.  
     **/
	static final int ISOLATION_READ_COMMITTED = 2;

    /**
     * No lost updates, no dirty reads, only committed data is returned.  
     * Writes only visible when committed.  Exclusive transaction
     * length locks are set on data that is written, short term locks (
     * possibly instantaneous duration locks) are set
     * on data that is read.  Read locks are requested for "zero" duration,
     * thus upon return from access no read row lock is held.
     **/
	static final int ISOLATION_READ_COMMITTED_NOHOLDLOCK = 3;

    /**
     * Read and write locks are held until end of transaction, but no
     * phantom protection is performed (ie no previous key locking).
     * Writes only visible when committed. 
     *
     * Note this constant is currently mapped to ISOLATION_SERIALIZABLE.  
     * The constant is provided so that code which only requires repeatable 
     * read can be coded with the right isolation level, and will just work when
     * store provided real repeatable read isolation.
     **/
	static final int ISOLATION_REPEATABLE_READ = 4;

    /**
     * Gray's isolation degree 3, "Serializable, Repeatable Read".	Note that
     * some conglomerate implementations may only be able to provide 
     * phantom protection under MODE_TABLE, while others can support this
     * under MODE_RECORD.
     **/
	static final int ISOLATION_SERIALIZABLE = 5;

    /**
     * Constants used for the flag argument to openConglomerate() and 
     * openScan() calls.
     *
     * NOTE - The values of these constants must correspond to their associated
     * constants in 
     * protocol.Database.Storage.RawStore.Interface.ContainerHandle, do not
     * add constants to this file without first adding there.
     **/

    /**
     * Use this mode to the openScan() call to indicate the scan should get
     * update locks during scan, and either promote the update locks to 
     * exclusive locks if the row is changed or demote the lock if the row
     * is not updated.  The lock demotion depends on the isolation level of
     * the scan.  If isolation level is ISOLATION_SERIALIZABLE or 
     * ISOLATION_REPEATABLE_READ
     * then the lock will be converted to a read lock.  If the isolation level 
     * ISOLATION_READ_COMMITTED then the lock is released when the scan moves
     * off the row.
     * <p>
     * Note that one must still set OPENMODE_FORUPDATE to be able to change
     * rows in the scan.  So to enable update locks for an updating scan one
     * provides (OPENMODE_FORUPDATE | OPENMODE_USE_UPDATE_LOCKS)
     **/
    static final int OPENMODE_USE_UPDATE_LOCKS      = 0x00001000;

    /**
     * Use this mode to the openConglomerate() call which opens the base
     * table to be used in a index to base row probe.  This will cause
     * the openConglomerate() call to not get any row locks as part of
     * it's fetches.
     * It is important when using this mode that the secondary index table be
     * successfully opened before opening the base table so that
     * proper locking protocol is followed.
     **/
    static final int OPENMODE_SECONDARY_LOCKED      = 0x00002000;

    /**
     * Use this mode to the openConglomerate() call used to open the
     * secondary indices of a table for inserting new rows in the table.
     * This will let the secondaryindex know that the base row being inserted
     * has already been locked and only previous key locks need be obtained.
     * 
     * It is important when using this mode that the base table be
     * successfully opened before opening the secondaryindex so that
     * proper locking protocol is followed.
     **/
    static final int OPENMODE_BASEROW_INSERT_LOCKED = 0x00004000;

    /**
     * open table for update, if not specified table will be opened for read.
     **/
    static final int OPENMODE_FORUPDATE             = 0x00000004;

    /**
     * Use this mode to the openConglomerate() call used to just get the
     * table lock on the conglomerate without actually doing anything else.
     * Any operations other than close() performed on the "opened" container
     * will fail.
     **/
    static final int OPENMODE_FOR_LOCK_ONLY         = 0x00000040;

    /**
     * The table lock request will not wait.
     * <p>
     * The request to get the table lock (any table lock including intent or
     * "real" table level lock), will not wait if it can't be granted.   A
     * lock timeout will be returned.  Note that subsequent row locks will
     * wait if the application has not set a 0 timeout and if the call does
     * not have a wait parameter (like OpenConglomerate.fetch().
     **/
    static final int OPENMODE_LOCK_NOWAIT           = 0x00000080;

    /**
     * Constants used for the countOpen() call.
     **/
    public static final int OPEN_CONGLOMERATE   = 0x01;
    public static final int OPEN_SCAN           = 0x02;
    public static final int OPEN_CREATED_SORTS  = 0x03;
    public static final int OPEN_SORT           = 0x04;
    public static final int OPEN_TOTAL          = 0x05;


	static final byte IS_DEFAULT	=	(byte) 0x00; // initialize the flag
	static final byte IS_TEMPORARY	=	(byte) 0x01; // conglom is temporary
	static final byte IS_KEPT		=	(byte) 0x02; // no auto remove


    /**************************************************************************
     * Interfaces previously defined in TcAccessIface:
     **************************************************************************
     */

	/**
	Check whether a conglomerate exists.

	@param  conglomId  The identifier of the conglomerate to check for.

	@return  true if the conglomerate exists, false otherwise.

	@exception StandardException   only thrown if something goes
	wrong in the lower levels.
	**/
    boolean conglomerateExists(long conglomId)
		throws StandardException;

    /**
    Create a conglomerate.
	<p>
	Currently, only "heap"'s and ""btree secondary index"'s are supported, 
    and all the features are not completely implemented.  
    For now, create conglomerates like this:
	<p>
	<blockquote><pre>
		TransactionController tc;
		long conglomId = tc.createConglomerate(
			"heap", // we're requesting a heap conglomerate
			template, // a populated template is required for heap and btree.
			null, // default properties
			0); // not temporary
	</blockquote></pre>

    Each implementation of a conglomerate takes a possibly different set
    of properties.  The "heap" implementation currently takes no properties.

    The "btree secondary index" requires the following set of properties:
    <UL>
    <LI> "baseConglomerateId" (integer).  The conglomerate id of the base
    conglomerate is never actually accessed by the b-tree secondary
    index implementation, it only serves as a namespace for row locks.
    This property is required.
    <LI> "rowLocationColumn" (integer).  The zero-based index into the row which