KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > raw > xact > RawTransaction


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.raw.xact.RawTransaction
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.store.raw.xact;
23
24 import org.apache.derby.iapi.store.raw.ContainerKey;
25
26 import org.apache.derby.iapi.services.locks.LockFactory;
27
28 import org.apache.derby.iapi.store.raw.data.DataFactory;
29 import org.apache.derby.iapi.store.raw.Compensation;
30 import org.apache.derby.iapi.store.raw.LockingPolicy;
31 import org.apache.derby.iapi.store.raw.Loggable;
32 import org.apache.derby.iapi.store.raw.Transaction;
33 import org.apache.derby.iapi.store.raw.GlobalTransactionId;
34 import org.apache.derby.iapi.store.raw.log.LogInstant;
35 import org.apache.derby.iapi.store.raw.data.RawContainerHandle;
36 import org.apache.derby.iapi.error.StandardException;
37
38 import org.apache.derby.iapi.util.ByteArray;
39 import org.apache.derby.iapi.services.io.DynamicByteArrayOutputStream;
40 import org.apache.derby.catalog.UUID;
41
42
43 import java.util.Observable JavaDoc;
44
45 import org.apache.derby.iapi.services.io.LimitObjectInput;
46
47 /**
48     RawTransaction is the form of Transaction used within the raw store. This
49     allows the break down of RawStore functionality into (at least) three modules
50     (Transactions, Data, Log) without exposing internal information on the
51     external interface.
52
53     <P>
54     The transaction will notify any Observer's just before the transaction
55     is committed, aborted or a rollback to savepoint occurs. The argument passed
56     to the update() method of the Observer's will be one of
57     <UL>
58     <LI> RawTransaction.COMMIT - transaction is committing
59     <LI> RawTransaction.ABORT - transaction is aborting
60     <LI> RawTransaction.SAVEPOINTROLLBACK - transaction is being rolled back to a savepoint
61     </UL>
62     The observer's must perform a value equality check (equals()) on the
63     update arg to see why it is being notified.
64
65     @see java.util.Observer
66 */
67
68 public abstract class RawTransaction extends Observable JavaDoc implements Transaction {
69
70     public static final Integer JavaDoc COMMIT = new Integer JavaDoc(0);
71     public static final Integer JavaDoc ABORT = new Integer JavaDoc(1);
72     public static final Integer JavaDoc SAVEPOINT_ROLLBACK = new Integer JavaDoc(2);
73     public static final Integer JavaDoc LOCK_ESCALATE = new Integer JavaDoc(3);
74
75     protected StandardException observerException;
76
77     /**
78         Get the lock factory to be used during this transaction.
79     */
80     public abstract LockFactory getLockFactory();
81
82     /**
83         Get the data factory to be used during this transaction.
84     */
85     public abstract DataFactory getDataFactory();
86
87     /**
88         Get cache statistics for the specified cache
89     */
90     public abstract long[] getCacheStats(String JavaDoc cacheName);
91
92     /**
93         Reset the cache statistics for the specified cache
94     */
95     public abstract void resetCacheStats(String JavaDoc cacheName);
96
97     /**
98         Get the log buffer to be used during this transaction.
99     */
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, LogInstant undoInstant,
120                                     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, TransactionId shortId);
129
130     /**
131         Set the transactionId (Global and internal) of this transaction using a
132         log record that contains the Global id
133     */
134     abstract public void setTransactionId(Loggable beginXact, TransactionId shortId);
135
136         
137     /**
138         Get the shortId of this transaction. May return null if transactio
139         has no ID.
140     */
141     abstract public TransactionId getId();
142
143     /**
144         Get the shortId of this transaction. May return null if transactio
145         has no ID.
146     */
147     abstract public GlobalTransactionId getGlobalId();
148
149     /**
150         Add this raw transaction on to the list of update transaction
151     */
152     public abstract void addUpdateTransaction(int transactionStatus);
153
154     /**
155         Remove this raw transaction from the list of update transaction
156     */
157     public abstract void removeUpdateTransaction();
158
159     /**
160         Change the state of transaction in table to prepare.
161     */
162     public abstract void prepareTransaction();
163
164     /**
165         Set the log instant for the first log record written by this
166         transaction.
167     */
168     abstract public void setFirstLogInstant(LogInstant instant);
169
170     /**
171         Get the log instant for the first log record written by this
172         transaction.
173     */
174     abstract public LogInstant getFirstLogInstant();
175
176     /**
177         Set the log instant for the last log record written by this transaction.
178     */
179     abstract public void setLastLogInstant(LogInstant instant);
180
181     /**
182         Get the log instant for the last log record written by this transaction.
183         If the transaction is unclear what its last log instant is,
184         than it may return null.
185     */
186     abstract public LogInstant getLastLogInstant();
187
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()
222         throws StandardException;
223
224     /**
225         Allow an Observer to indicate an exception to the transaction that
226         is raised in its update() method.
227     */
228     public void setObserverException(StandardException se) {
229         if (observerException == null)
230             observerException = se;
231     }
232
233     /**
234         Start a nested top transaction. A nested top transaction behaves exactly
235         like a user transaction. Nested top transaction allow system type work
236         to proceed in a separate transaction to the current user transaction
237         and be committed independently of the user transaction (usually before
238         the user transaction).
239         Only one nested top transaction can be active in a context at any one
240         time.
241         After a commit the transaction may be re-used.
242
243         A nested top transaction conflicts on the logical locks of its "parent"
244         transaction.
245
246         @exception StandardException Standard Cloudscape error policy
247     */
248
249     public abstract RawTransaction startNestedTopTransaction() throws StandardException;
250
251
252     /**
253         Open a container that may be dropped - use only by logging and recovery.
254         During recovery redo, a log record may refer to a container that has
255         long been dropped. This interface is provided so a dropped container
256         may be opened.
257
258         If the container has been dropped and is known to be committed, then
259         even if we open the dropped container with forUpdate true, the
260         container will be silently opened as read only. Logging and recovery
261         code always check for committed drop status. Anybody else wanting to
262         use this interface must keep this in mind.
263
264         @exception StandardException Standard cloudscape exception policy
265     */
266     public abstract RawContainerHandle openDroppedContainer
267         (ContainerKey containerId, LockingPolicy locking)
268          throws StandardException;
269
270     /**
271         Recreate a container during redo recovery.
272
273         Used during redo recovery when processing log records trying to
274         create a container, but no container is found in the db.
275
276         @exception StandardException Standard cloudscape exception policy
277      */
278     public abstract void reCreateContainerForRedoRecovery
279         (long segmentId, long containerId, ByteArray containerInfo)
280         throws StandardException;
281
282
283     /**
284         Status that needs to go into the begin transaction log record, if there
285         is one, to help with recovery
286     */
287     protected abstract int statusForBeginXactLog();
288
289     /**
290         Status that needs to go into the end transaction log record, if there
291         is one, to help with recovery
292     */
293     protected abstract int statusForEndXactLog();
294
295     /**
296         Is the transaction in the middle of an abort.
297     */
298     public abstract boolean inAbort();
299
300     /**
301         Can this transaction handles post termination work
302     */
303     public abstract boolean handlesPostTerminationWork();
304
305     /**
306         Make this transaction aware that it is being used by recovery
307      */
308     public abstract void recoveryTransaction();
309
310     /**
311         Allow my users to notigy my observers.
312     */
313     public void notifyObservers(Object JavaDoc arg) {
314         if (countObservers() != 0) {
315             setChanged();
316             super.notifyObservers(arg);
317         }
318     }
319
320     
321     /**
322      *Retunrs true if the transaction is part of rollforward recovery
323      */
324     public abstract boolean inRollForwardRecovery();
325
326
327     /**
328      * redo a checkpoint during rollforward recovery
329      */
330     public abstract void checkpointInRollForwardRecovery(LogInstant cinstant,
331                                                          long redoLWM)
332         throws StandardException;
333
334     
335     /*
336      * Make the transaction block the online backup.
337      *
338      * @param wait if <tt>true</tt>, waits until the transaction
339      * can block the backup.
340      * @return <tt>true</tt> if the transaction blocked the
341      * backup. <tt>false</tt> otherwise.
342      * @exception StandardException if interrupted while waiting
343      * for the backup in progress to complete.
344      */
345     public abstract boolean blockBackup(boolean wait)
346         throws StandardException;
347
348     /**
349      * Check if the transaction is blocking the backup ?
350      * @return <tt> true </tt> if this transaction is
351      * blocking the backup, otherwise <tt> false </tt>
352      */
353     public abstract boolean isBlockingBackup();
354
355 }
356
357
358
Popular Tags