001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.xact.RawTransaction
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.raw.xact;
023:
024: import org.apache.derby.iapi.store.raw.ContainerKey;
025:
026: import org.apache.derby.iapi.services.locks.LockFactory;
027:
028: import org.apache.derby.iapi.store.raw.data.DataFactory;
029: import org.apache.derby.iapi.store.raw.Compensation;
030: import org.apache.derby.iapi.store.raw.LockingPolicy;
031: import org.apache.derby.iapi.store.raw.Loggable;
032: import org.apache.derby.iapi.store.raw.Transaction;
033: import org.apache.derby.iapi.store.raw.GlobalTransactionId;
034: import org.apache.derby.iapi.store.raw.log.LogInstant;
035: import org.apache.derby.iapi.store.raw.data.RawContainerHandle;
036: import org.apache.derby.iapi.error.StandardException;
037:
038: import org.apache.derby.iapi.util.ByteArray;
039: import org.apache.derby.iapi.services.io.DynamicByteArrayOutputStream;
040: import org.apache.derby.catalog.UUID;
041:
042: import java.util.Observable;
043:
044: import org.apache.derby.iapi.services.io.LimitObjectInput;
045:
046: /**
047: RawTransaction is the form of Transaction used within the raw store. This
048: allows the break down of RawStore functionality into (at least) three modules
049: (Transactions, Data, Log) without exposing internal information on the
050: external interface.
051:
052: <P>
053: The transaction will notify any Observer's just before the transaction
054: is committed, aborted or a rollback to savepoint occurs. The argument passed
055: to the update() method of the Observer's will be one of
056: <UL>
057: <LI> RawTransaction.COMMIT - transaction is committing
058: <LI> RawTransaction.ABORT - transaction is aborting
059: <LI> RawTransaction.SAVEPOINTROLLBACK - transaction is being rolled back to a savepoint
060: </UL>
061: The observer's must perform a value equality check (equals()) on the
062: update arg to see why it is being notified.
063:
064: @see java.util.Observer
065: */
066:
067: public abstract class RawTransaction extends Observable implements
068: Transaction {
069:
070: public static final Integer COMMIT = new Integer(0);
071: public static final Integer ABORT = new Integer(1);
072: public static final Integer SAVEPOINT_ROLLBACK = new Integer(2);
073: public static final Integer LOCK_ESCALATE = new Integer(3);
074:
075: protected StandardException observerException;
076:
077: /**
078: Get the lock factory to be used during this transaction.
079: */
080: public abstract LockFactory getLockFactory();
081:
082: /**
083: Get the data factory to be used during this transaction.
084: */
085: public abstract DataFactory getDataFactory();
086:
087: /**
088: Get cache statistics for the specified cache
089: */
090: public abstract long[] getCacheStats(String cacheName);
091:
092: /**
093: Reset the cache statistics for the specified cache
094: */
095: public abstract void resetCacheStats(String cacheName);
096:
097: /**
098: Get the log buffer to be used during this transaction.
099: */
100: public abstract DynamicByteArrayOutputStream getLogBuffer();
101:
102: /**
103: Log a compensation operation and then action it in the context of this
104: transaction.
105: The CompensationOperation is logged in the transaction log file and
106: then its doMe method is called to perform the required change. This
107: compensation operation will rollback the change that was done by the
108: Loggable Operation at undoInstant.
109:
110: @param compensation the Compensation Operation
111: @param undoInstant the LogInstant of the Loggable Operation this
112: compensation operation is going to roll back
113: @param in optional data for the rollback operation
114:
115: @see Compensation
116:
117: @exception StandardException Standard cloudscape exception policy
118: */
119: public abstract void logAndUndo(Compensation compensation,
120: LogInstant undoInstant, LimitObjectInput in)
121: throws StandardException;
122:
123: /** Methods to help logging and recovery */
124:
125: /**
126: Set the transaction Ids (Global and internal) of this transaction
127: */
128: public abstract void setTransactionId(GlobalTransactionId id,
129: TransactionId shortId);
130:
131: /**
132: Set the transactionId (Global and internal) of this transaction using a
133: log record that contains the Global id
134: */
135: abstract public void setTransactionId(Loggable beginXact,
136: TransactionId shortId);
137:
138: /**
139: Get the shortId of this transaction. May return null if transactio
140: has no ID.
141: */
142: abstract public TransactionId getId();
143:
144: /**
145: Get the shortId of this transaction. May return null if transactio
146: has no ID.
147: */
148: abstract public GlobalTransactionId getGlobalId();
149:
150: /**
151: Add this raw transaction on to the list of update transaction
152: */
153: public abstract void addUpdateTransaction(int transactionStatus);
154:
155: /**
156: Remove this raw transaction from the list of update transaction
157: */
158: public abstract void removeUpdateTransaction();
159:
160: /**
161: Change the state of transaction in table to prepare.
162: */
163: public abstract void prepareTransaction();
164:
165: /**
166: Set the log instant for the first log record written by this
167: transaction.
168: */
169: abstract public void setFirstLogInstant(LogInstant instant);
170:
171: /**
172: Get the log instant for the first log record written by this
173: transaction.
174: */
175: abstract public LogInstant getFirstLogInstant();
176:
177: /**
178: Set the log instant for the last log record written by this transaction.
179: */
180: abstract public void setLastLogInstant(LogInstant instant);
181:
182: /**
183: Get the log instant for the last log record written by this transaction.
184: If the transaction is unclear what its last log instant is,
185: than it may return null.
186: */
187: abstract public LogInstant getLastLogInstant();
188:
189: /**
190: Check to see if a logical operation is allowed by this transaction,
191: throws a TransactionExceotion if it isn't. This implementation allows
192: logical operations. Transactions that need to disallow logical
193: operations should hide this method.
194:
195: @exception StandardException Standard Cloudscape error policy,
196: */
197: public void checkLogicalOperationOk() throws StandardException {
198: }
199:
200: /**
201: Return true if this transaction should be rolled back first
202: in recovery. This implementation returns false. Transactions that
203: need to rollback first during recovery should hide this method.
204: */
205: public boolean recoveryRollbackFirst() {
206: return false;
207: }
208:
209: /**
210: * During recovery re-prepare a transaction.
211: * <p>
212: * After redo() and undo(), this routine is called on all outstanding
213: * in-doubt (prepared) transactions. This routine re-acquires all
214: * logical write locks for operations in the xact, and then modifies
215: * the transaction table entry to make the transaction look as if it
216: * had just been prepared following startup after recovery.
217: * <p>
218: *
219: * @exception StandardException Standard exception policy.
220: **/
221: abstract public void reprepare() throws StandardException;
222:
223: /**
224: Allow an Observer to indicate an exception to the transaction that
225: is raised in its update() method.
226: */
227: public void setObserverException(StandardException se) {
228: if (observerException == null)
229: observerException = se;
230: }
231:
232: /**
233: Start a nested top transaction. A nested top transaction behaves exactly
234: like a user transaction. Nested top transaction allow system type work
235: to proceed in a separate transaction to the current user transaction
236: and be committed independently of the user transaction (usually before
237: the user transaction).
238: Only one nested top transaction can be active in a context at any one
239: time.
240: After a commit the transaction may be re-used.
241:
242: A nested top transaction conflicts on the logical locks of its "parent"
243: transaction.
244:
245: @exception StandardException Standard Cloudscape error policy
246: */
247:
248: public abstract RawTransaction startNestedTopTransaction()
249: throws StandardException;
250:
251: /**
252: Open a container that may be dropped - use only by logging and recovery.
253: During recovery redo, a log record may refer to a container that has
254: long been dropped. This interface is provided so a dropped container
255: may be opened.
256:
257: If the container has been dropped and is known to be committed, then
258: even if we open the dropped container with forUpdate true, the
259: container will be silently opened as read only. Logging and recovery
260: code always check for committed drop status. Anybody else wanting to
261: use this interface must keep this in mind.
262:
263: @exception StandardException Standard cloudscape exception policy
264: */
265: public abstract RawContainerHandle openDroppedContainer(
266: ContainerKey containerId, LockingPolicy locking)
267: throws StandardException;
268:
269: /**
270: Recreate a container during redo recovery.
271:
272: Used during redo recovery when processing log records trying to
273: create a container, but no container is found in the db.
274:
275: @exception StandardException Standard cloudscape exception policy
276: */
277: public abstract void reCreateContainerForRedoRecovery(
278: long segmentId, long containerId, ByteArray containerInfo)
279: throws StandardException;
280:
281: /**
282: Status that needs to go into the begin transaction log record, if there
283: is one, to help with recovery
284: */
285: protected abstract int statusForBeginXactLog();
286:
287: /**
288: Status that needs to go into the end transaction log record, if there
289: is one, to help with recovery
290: */
291: protected abstract int statusForEndXactLog();
292:
293: /**
294: Is the transaction in the middle of an abort.
295: */
296: public abstract boolean inAbort();
297:
298: /**
299: Can this transaction handles post termination work
300: */
301: public abstract boolean handlesPostTerminationWork();
302:
303: /**
304: Make this transaction aware that it is being used by recovery
305: */
306: public abstract void recoveryTransaction();
307:
308: /**
309: Allow my users to notigy my observers.
310: */
311: public void notifyObservers(Object arg) {
312: if (countObservers() != 0) {
313: setChanged();
314: super .notifyObservers(arg);
315: }
316: }
317:
318: /**
319: *Retunrs true if the transaction is part of rollforward recovery
320: */
321: public abstract boolean inRollForwardRecovery();
322:
323: /**
324: * redo a checkpoint during rollforward recovery
325: */
326: public abstract void checkpointInRollForwardRecovery(
327: LogInstant cinstant, long redoLWM) throws StandardException;
328:
329: /*
330: * Make the transaction block the online backup.
331: *
332: * @param wait if <tt>true</tt>, waits until the transaction
333: * can block the backup.
334: * @return <tt>true</tt> if the transaction blocked the
335: * backup. <tt>false</tt> otherwise.
336: * @exception StandardException if interrupted while waiting
337: * for the backup in progress to complete.
338: */
339: public abstract boolean blockBackup(boolean wait)
340: throws StandardException;
341:
342: /**
343: * Check if the transaction is blocking the backup ?
344: * @return <tt> true </tt> if this transaction is
345: * blocking the backup, otherwise <tt> false </tt>
346: */
347: public abstract boolean isBlockingBackup();
348:
349: }
|