--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.raw.xact.RawTransaction\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.raw.xact;\r
+\r
+import org.apache.derby.iapi.store.raw.ContainerKey;\r
+\r
+import org.apache.derby.iapi.services.locks.LockFactory;\r
+\r
+import org.apache.derby.iapi.store.raw.data.DataFactory;\r
+import org.apache.derby.iapi.store.raw.Compensation;\r
+import org.apache.derby.iapi.store.raw.LockingPolicy;\r
+import org.apache.derby.iapi.store.raw.Loggable;\r
+import org.apache.derby.iapi.store.raw.Transaction;\r
+import org.apache.derby.iapi.store.raw.GlobalTransactionId;\r
+import org.apache.derby.iapi.store.raw.log.LogInstant;\r
+import org.apache.derby.iapi.store.raw.log.LogFactory;\r
+import org.apache.derby.iapi.store.raw.data.RawContainerHandle;\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import org.apache.derby.iapi.util.ByteArray;\r
+import org.apache.derby.iapi.services.io.DynamicByteArrayOutputStream;\r
+import org.apache.derby.catalog.UUID;\r
+\r
+\r
+import java.util.Observable;\r
+\r
+import org.apache.derby.iapi.services.io.LimitObjectInput;\r
+\r
+/**\r
+ RawTransaction is the form of Transaction used within the raw store. This\r
+ allows the break down of RawStore functionality into (at least) three modules\r
+ (Transactions, Data, Log) without exposing internal information on the\r
+ external interface.\r
+\r
+ <P>\r
+ The transaction will notify any Observer's just before the transaction\r
+ is committed, aborted or a rollback to savepoint occurs. The argument passed\r
+ to the update() method of the Observer's will be one of\r
+ <UL>\r
+ <LI> RawTransaction.COMMIT - transaction is committing\r
+ <LI> RawTransaction.ABORT - transaction is aborting\r
+ <LI> RawTransaction.SAVEPOINTROLLBACK - transaction is being rolled back to a savepoint\r
+ </UL>\r
+ The observer's must perform a value equality check (equals()) on the \r
+ update arg to see why it is being notified.\r
+\r
+ @see java.util.Observer\r
+*/\r
+\r
+public abstract class RawTransaction extends Observable implements Transaction {\r
+\r
+ public static final Integer COMMIT = new Integer(0);\r
+ public static final Integer ABORT = new Integer(1);\r
+ public static final Integer SAVEPOINT_ROLLBACK = new Integer(2);\r
+ public static final Integer LOCK_ESCALATE = new Integer(3);\r
+\r
+ protected StandardException observerException;\r
+\r
+ /** \r
+ Get the lock factory to be used during this transaction.\r
+ */\r
+ public abstract LockFactory getLockFactory();\r
+\r
+ /** \r
+ Get the data factory to be used during this transaction.\r
+ */\r
+ public abstract DataFactory getDataFactory();\r
+\r
+ /** \r
+ Get the log factory to be used during this transaction.\r
+ */\r
+ public abstract LogFactory getLogFactory();\r
+\r
+ /**\r
+ Get cache statistics for the specified cache\r
+ */\r
+ public abstract long[] getCacheStats(String cacheName);\r
+\r
+ /**\r
+ Reset the cache statistics for the specified cache\r
+ */\r
+ public abstract void resetCacheStats(String cacheName);\r
+\r
+ /**\r
+ Get the log buffer to be used during this transaction.\r
+ */\r
+ public abstract DynamicByteArrayOutputStream getLogBuffer();\r
+\r
+ /**\r
+ Log a compensation operation and then action it in the context of this \r
+ transaction.\r
+ The CompensationOperation is logged in the transaction log file and \r
+ then its doMe method is called to perform the required change. This \r
+ compensation operation will rollback the change that was done by the \r
+ Loggable Operation at undoInstant. \r
+\r
+ @param compensation the Compensation Operation\r
+ @param undoInstant the LogInstant of the Loggable Operation this \r
+ compensation operation is going to roll back\r
+ @param in optional data for the rollback operation\r
+\r
+ @see Compensation\r
+\r
+ @exception StandardException Standard Derby exception policy\r
+ */\r
+ public abstract void logAndUndo(Compensation compensation, LogInstant undoInstant, \r
+ LimitObjectInput in) \r
+ throws StandardException;\r
+\r
+ /** Methods to help logging and recovery */\r
+\r
+ /** \r
+ Set the transaction Ids (Global and internal) of this transaction\r
+ */\r
+ public abstract void setTransactionId(GlobalTransactionId id, TransactionId shortId);\r
+\r
+ /**\r
+ Set the transactionId (Global and internal) of this transaction using a\r
+ log record that contains the Global id\r
+ */\r
+ abstract public void setTransactionId(Loggable beginXact, TransactionId shortId);\r
+\r
+ \r
+ /**\r
+ Get the shortId of this transaction. May return null if transactio\r
+ has no ID.\r
+ */\r
+ abstract public TransactionId getId();\r
+\r
+ /**\r
+ Get the shortId of this transaction. May return null if transactio\r
+ has no ID.\r
+ */\r
+ abstract public GlobalTransactionId getGlobalId();\r
+\r
+ /**\r
+ Add this raw transaction on to the list of update transaction\r
+ */\r
+ public abstract void addUpdateTransaction(int transactionStatus);\r
+\r
+ /**\r
+ Remove this raw transaction from the list of update transaction\r
+ */\r
+ public abstract void removeUpdateTransaction();\r
+\r
+ /**\r
+ Change the state of transaction in table to prepare.\r
+ */\r
+ public abstract void prepareTransaction();\r
+\r
+ /**\r
+ Set the log instant for the first log record written by this \r
+ transaction.\r
+ */\r
+ abstract public void setFirstLogInstant(LogInstant instant);\r
+\r
+ /**\r
+ Get the log instant for the first log record written by this \r
+ transaction.\r
+ */\r
+ abstract public LogInstant getFirstLogInstant();\r
+\r
+ /**\r
+ Set the log instant for the last log record written by this transaction. \r
+ */\r
+ abstract public void setLastLogInstant(LogInstant instant);\r
+\r
+ /**\r
+ Get the log instant for the last log record written by this transaction. \r
+ If the transaction is unclear what its last log instant is, \r
+ than it may return null.\r
+ */\r
+ abstract public LogInstant getLastLogInstant();\r
+\r
+\r
+ /**\r
+ Check to see if a logical operation is allowed by this transaction, \r
+ throws a TransactionExceotion if it isn't. This implementation allows\r
+ logical operations. Transactions that need to disallow logical \r
+ operations should hide this method.\r
+\r
+ @exception StandardException Standard Derby error policy,\r
+ */\r
+ public void checkLogicalOperationOk() throws StandardException {\r
+ }\r
+\r
+ /**\r
+ Return true if this transaction should be rolled back first\r
+ in recovery. This implementation returns false. Transactions that\r
+ need to rollback first during recovery should hide this method.\r
+ */\r
+ public boolean recoveryRollbackFirst() {\r
+ return false;\r
+ }\r
+\r
+ /**\r
+ * During recovery re-prepare a transaction.\r
+ * <p>\r
+ * After redo() and undo(), this routine is called on all outstanding \r
+ * in-doubt (prepared) transactions. This routine re-acquires all \r
+ * logical write locks for operations in the xact, and then modifies\r
+ * the transaction table entry to make the transaction look as if it\r
+ * had just been prepared following startup after recovery.\r
+ * <p>\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ abstract public void reprepare()\r
+ throws StandardException;\r
+\r
+ /**\r
+ Allow an Observer to indicate an exception to the transaction that\r
+ is raised in its update() method.\r
+ */\r
+ public void setObserverException(StandardException se) {\r
+ if (observerException == null)\r
+ observerException = se;\r
+ }\r
+\r
+ /**\r
+ Start a nested top transaction. A nested top transaction behaves exactly\r
+ like a user transaction. Nested top transaction allow system type work\r
+ to proceed in a separate transaction to the current user transaction\r
+ and be committed independently of the user transaction (usually before\r
+ the user transaction).\r
+ Only one nested top transaction can be active in a context at any one\r
+ time.\r
+ After a commit the transaction may be re-used.\r
+\r
+ A nested top transaction conflicts on the logical locks of its "parent"\r
+ transaction.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+ */\r
+\r
+ public abstract RawTransaction startNestedTopTransaction() throws StandardException;\r
+\r
+\r
+ /**\r
+ Open a container that may be dropped - use only by logging and recovery.\r
+ During recovery redo, a log record may refer to a container that has\r
+ long been dropped. This interface is provided so a dropped container\r
+ may be opened.\r
+\r
+ If the container has been dropped and is known to be committed, then\r
+ even if we open the dropped container with forUpdate true, the\r
+ container will be silently opened as read only. Logging and recovery\r
+ code always check for committed drop status. Anybody else wanting to\r
+ use this interface must keep this in mind.\r
+\r
+ @exception StandardException Standard Derby exception policy\r
+ */\r
+ public abstract RawContainerHandle openDroppedContainer\r
+ (ContainerKey containerId, LockingPolicy locking)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Recreate a container during redo recovery.\r
+\r
+ Used during redo recovery when processing log records trying to \r
+ create a container, but no container is found in the db.\r
+\r
+ @exception StandardException Standard Derby exception policy\r
+ */\r
+ public abstract void reCreateContainerForRedoRecovery\r
+ (long segmentId, long containerId, ByteArray containerInfo)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ Status that needs to go into the begin transaction log record, if there\r
+ is one, to help with recovery\r
+ */\r
+ protected abstract int statusForBeginXactLog();\r
+\r
+ /**\r
+ Status that needs to go into the end transaction log record, if there\r
+ is one, to help with recovery\r
+ */\r
+ protected abstract int statusForEndXactLog();\r
+\r
+ /** \r
+ Is the transaction in the middle of an abort.\r
+ */\r
+ public abstract boolean inAbort();\r
+\r
+ /**\r
+ Can this transaction handles post termination work\r
+ */\r
+ public abstract boolean handlesPostTerminationWork();\r
+\r
+ /**\r
+ Make this transaction aware that it is being used by recovery\r
+ */\r
+ public abstract void recoveryTransaction();\r
+\r
+ /**\r
+ Allow my users to notigy my observers.\r
+ */\r
+ public void notifyObservers(Object arg) {\r
+ if (countObservers() != 0) {\r
+ setChanged();\r
+ super.notifyObservers(arg);\r
+ }\r
+ }\r
+\r
+ \r
+ /** \r
+ *Retunrs true if the transaction is part of rollforward recovery\r
+ */\r
+ public abstract boolean inRollForwardRecovery();\r
+\r
+\r
+ /** \r
+ * redo a checkpoint during rollforward recovery\r
+ */\r
+ public abstract void checkpointInRollForwardRecovery(LogInstant cinstant,\r
+ long redoLWM) \r
+ throws StandardException;\r
+\r
+ \r
+ /**\r
+ * Make the transaction block the online backup.\r
+ *\r
+ * @param wait if <tt>true</tt>, waits until the transaction\r
+ * can block the backup.\r
+ * @return <tt>true</tt> if the transaction blocked the \r
+ * backup. <tt>false</tt> otherwise.\r
+ * @exception StandardException if interrupted while waiting \r
+ * for the backup in progress to complete.\r
+ */\r
+ public abstract boolean blockBackup(boolean wait)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Check if the transaction is blocking the backup ?\r
+ * @return <tt> true </tt> if this transaction is \r
+ * blocking the backup, otherwise <tt> false </tt>\r
+ */\r
+ public abstract boolean isBlockingBackup();\r
+\r
+}\r
+\r
+\r