transaction.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.iapi.store.raw.Transaction

   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.raw;

import org.apache.derby.iapi.services.daemon.Serviceable;
import org.apache.derby.iapi.error.StandardException;
import org.apache.derby.iapi.store.raw.log.LogInstant;
import org.apache.derby.iapi.store.access.FileResource;
import org.apache.derby.iapi.store.access.RowSource;
import org.apache.derby.iapi.store.access.TransactionController;
import org.apache.derby.iapi.services.context.ContextManager;

import java.util.Properties;

import org.apache.derby.iapi.services.property.PersistentSet;

import org.apache.derby.iapi.error.ExceptionSeverity;
/**
*/

public interface Transaction {

	/**
		Return the context manager this transaction is associated with.
	*/
	public ContextManager getContextManager();

    /**
     * Get the compatibility space of the transaction.
     * <p>
     * Returns an object that can be used with the lock manager to provide
     * the compatibility space of a transaction.  2 transactions with the
     * same compatibility space will not conflict in locks.  The usual case
     * is that each transaction has it's own unique compatibility space.
     * <p>
     *
	 * @return The compatibility space of the transaction.
     **/
    Object getCompatibilitySpace();


	/**
		Called after the transaction has been attached to an Access Manger
		TransactionController. Thus may not be called for all transactions.
		Purpose is to allow a transaction access to database (service) properties.

		Will not be called for transactions early in the boot process, ie. before
		the property conglomerate is set up.
		@exception StandardException  Standard cloudscape exception policy
	*/
	public void setup(PersistentSet set)
		throws StandardException;

	/**
		Return my transaction identifier. Transaction identifiers may be 
        re-used for transactions that do not modify the raw store.
		May return null if this transaction has no globalId.
	*/
	public GlobalTransactionId getGlobalId();

	/**
		Get the current default locking policy for all operations within this
		transaction. The transaction is initially started with a default
		locking policy equivalent to
		<PRE>
			 newLockingPolicy(
              LockingPolicy.MODE_RECORD, LockingPolicy.ISOLATION_SERIALIZABLE, true);
		</PRE>
        This default can be changed by subsequent calls to 
        setDefaultLockingPolicy(LockingPolicy policy).


		@return The current default locking policy in this transaction.
	*/

	public LockingPolicy getDefaultLockingPolicy();


	/**
		Obtain a locking policy for use in openContainer(). The mode
		and isolation must be constants from LockingPolicy. If higherOK is true
		then the object returned may implement a stricter form of locking than
		the one requested.
		<BR>
		A null LockingPolicy reference is identical to a LockingPolicy obtained 
        by using MODE_NONE which is guaranteed to exist.

		@param mode A constant of the form LockingPolicy.MODE_*
		@param isolation A constant of the form LockingPolicy.ISOLATION_*
		@param stricterOk True if a stricter level of locking is acceptable, 
        false if an exact match is required.

		@return A object that can be used in an openContainer call, 
        null if a matching policy cannot be found.
	*/

	public LockingPolicy newLockingPolicy(int mode, int isolation, boolean stricterOk);


	/**
		Set the default locking policy for all operations within this
		transaction. The transaction is intially started with a default
		locking policy equivalent to
		<PRE>
			 newLockingPolicy(
              LockingPolicy.MODE_RECORD, LockingPolicy.ISOLATION_SERIALIZABLE, true);
		</PRE>

		@param policy The lock policy to use, if null then then a no locking 
        policy will be installed as the default.

		@return true if a new locking policy was installed as the default, false
		of a matching policy could not be found.
	*/

	public void setDefaultLockingPolicy(LockingPolicy policy);


	/**
		Commit this transaction. All savepoints within this transaction are 
        released.

		@return the commit instant of this transaction, or null if it
		didn't make any changes 
		
		@exception StandardException
        A transaction level exception is thrown
        if the transaction was aborted due to some error. Any exceptions that 
        occur of lower severity than Transaction severity are caught, the 
        transaction is then aborted and then an exception of Transaction
		severity is thrown nesting the original exception.

		@exception StandardException Any exception more severe than a
        Transaction exception is not caught and the transaction is not aborted.
        The transaction will be aborted by the standard context mechanism.

	*/

	public LogInstant commit() throws StandardException;

	/**
	    "Commit" this transaction without sync'ing the log.
		Everything else is identical to commit(), use this at your own risk.
		
		<BR>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.

		@exception StandardException
        A transaction level exception is thrown
        if the transaction was aborted due to some error. Any exceptions that 
        occur of lower severity than Transaction severity are caught, the 
        transaction is then aborted and then an exception of Transaction
		severity is thrown nesting the original exception.

		@exception StandardException Any exception more severe than a
        Transaction exception is not caught and the transaction is not aborted.
        The transaction will be aborted by the standard context mechanism.
	*/

	public LogInstant commitNoSync(int commitflag) throws StandardException;
	public final int RELEASE_LOCKS = TransactionController.RELEASE_LOCKS;
	public final int KEEP_LOCKS = TransactionController.KEEP_LOCKS;


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

		@exception StandardException Only exceptions with severities greater 
        than ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
		
	*/
	public void abort() throws StandardException;

	/**
		Close this transaction, the transaction must be idle. This close will
		pop the transaction context off the stack that was pushed when the 
        transaction was started.

		@see RawStoreFactory#startTransaction

		@exception StandardException Standard Cloudscape error policy
		@exception StandardException A transaction level exception is 
        thrown if the transaction is not idle.

		
	*/
	public void close() throws StandardException;

	/**
        If this transaction is not idle, abort it.  After this call close().

		@see RawStoreFactory#startTransaction

		@exception StandardException Standard Cloudscape error policy
		@exception StandardException A transaction level exception is 
        thrown if the transaction is not idle.

		
	*/
	public void destroy() throws StandardException;


	/**
		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".
    @param name     The user provided name of the savepoint
	  @param	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

		@return returns total number of savepoints in the stack.
		@exception StandardException  Standard cloudscape exception policy
		@exception StandardException
        A statement level exception is thrown if a savepoint already 
        exists in the current transaction with the same name.
		
	*/

	public int setSavePoint(String name, Object kindOfSavepoint) throws StandardException;

	/**
		Release the save point of the given name. Relasing a savepoint removes 
        all knowledge from this transaction of the named savepoint and any 
        savepoints set since the named savepoint was set.
    @param name     The user provided name of the savepoint, set by the user
                    in the setSavePoint() call.
	  @param	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

		@return returns total number of savepoints in the stack.
		@exception StandardException  Standard cloudscape exception policy
		@exception StandardException
        A statement level exception is thrown if a savepoint already
        exists in the current transaction with the same name.

	*/

	public int releaseSavePoint(String name, Object kindOfSavepoint) throws StandardException;

	/**
		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).
    @param name     The user provided name of the savepoint, set by the user
                    in the setSavePoint() call.
	  @param	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

		@return returns total number of savepoints in the stack.
		@exception StandardException  Standard cloudscape exception policy
		@exception StandardException
        A statement level exception is thrown if no savepoint exists with 
        the given name.

	*/
	public int rollbackToSavePoint(String name, Object kindOfSavepoint) throws StandardException;

	/**

		Open a container, with the transaction's default locking policy.

        <p>
        Note that if NOWAIT has been specified lock will be 
        requested with no wait time, and if lock is not granted a 
        SQLState.LOCK_TIMEOUT exception will be thrown.
		<P>
		The release() method of ContainerHandle will be called when this 
        transaction is aborted or commited, it may be called explicitly to
		release the ContainerHandle before the end of the transaction.


		@return a valid ContainerHandle or null if the container does not exist.

		@exception StandardException  Standard cloudscape exception policy