Source code: org/apache/derby/iapi/store/raw/xact/RawTransaction.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.raw.xact.RawTransaction
4
5 Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18
19 */
20
21 package org.apache.derby.iapi.store.raw.xact;
22
23 import org.apache.derby.iapi.store.raw.ContainerKey;
24
25 import org.apache.derby.iapi.services.locks.LockFactory;
26
27 import org.apache.derby.iapi.store.raw.data.DataFactory;
28 import org.apache.derby.iapi.store.raw.Compensation;
29 import org.apache.derby.iapi.store.raw.LockingPolicy;
30 import org.apache.derby.iapi.store.raw.Loggable;
31 import org.apache.derby.iapi.store.raw.Transaction;
32 import org.apache.derby.iapi.store.raw.GlobalTransactionId;
33 import org.apache.derby.iapi.store.raw.log.LogInstant;
34 import org.apache.derby.iapi.store.raw.data.RawContainerHandle;
35 import org.apache.derby.iapi.error.StandardException;
36
37 import org.apache.derby.iapi.util.ByteArray;
38 import org.apache.derby.iapi.services.io.DynamicByteArrayOutputStream;
39 import org.apache.derby.catalog.UUID;
40
41
42 import java.util.Observable;
43
44 import org.apache.derby.iapi.services.io.LimitObjectInput;
45
46 /**
47 RawTransaction is the form of Transaction used within the raw store. This
48 allows the break down of RawStore functionality into (at least) three modules
49 (Transactions, Data, Log) without exposing internal information on the
50 external interface.
51
52 <P>
53 The transaction will notify any Observer's just before the transaction
54 is committed, aborted or a rollback to savepoint occurs. The argument passed
55 to the update() method of the Observer's will be one of
56 <UL>
57 <LI> RawTransaction.COMMIT - transaction is committing
58 <LI> RawTransaction.ABORT - transaction is aborting
59 <LI> RawTransaction.SAVEPOINTROLLBACK - transaction is being rolled back to a savepoint
60 </UL>
61 The observer's must perform a value equality check (equals()) on the
62 update arg to see why it is being notified.
63
64 @see java.util.Observer
65 */
66
67 public abstract class RawTransaction extends Observable implements Transaction {
68
69 public static final Integer COMMIT = new Integer(0);
70 public static final Integer ABORT = new Integer(1);
71 public static final Integer SAVEPOINT_ROLLBACK = new Integer(2);
72 public static final Integer LOCK_ESCALATE = new Integer(3);
73
74 protected StandardException observerException;
75
76 /**
77 Get the lock factory to be used during this transaction.
78 */
79 public abstract LockFactory getLockFactory();
80
81 /**
82 Get the data factory to be used during this transaction.
83 */
84 public abstract DataFactory getDataFactory();
85
86 /**
87 Get cache statistics for the specified cache
88 */
89 public abstract long[] getCacheStats(String cacheName);
90
91 /**
92 Reset the cache statistics for the specified cache
93 */
94 public abstract void resetCacheStats(String cacheName);
95
96 /**
97 Get the log buffer to be used during this transaction.
98 */
99 public abstract DynamicByteArrayOutputStream getLogBuffer();
100
101 /**
102 Log a compensation operation and then action it in the context of this
103 transaction.
104 The CompensationOperation is logged in the transaction log file and
105 then its doMe method is called to perform the required change. This
106 compensation operation will rollback the change that was done by the
107 Loggable Operation at undoInstant.
108
109 @param compensation the Compensation Operation
110 @param undoInstant the LogInstant of the Loggable Operation this
111 compensation operation is going to roll back
112 @param in optional data for the rollback operation
113 @param dataLengt optional data length
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 load tran - use only by media recovery.
272
273 @exception StandardException Standard cloudscape exception policy
274 */
275 public abstract void reCreateContainerForLoadTran
276 (long segmentId, long containerId, ByteArray containerInfo)
277 throws StandardException;
278
279
280 /**
281 Status that needs to go into the begin transaction log record, if there
282 is one, to help with recovery
283 */
284 protected abstract int statusForBeginXactLog();
285
286 /**
287 Status that needs to go into the end transaction log record, if there
288 is one, to help with recovery
289 */
290 protected abstract int statusForEndXactLog();
291
292 /**
293 Is the transaction in the middle of an abort.
294 */
295 public abstract boolean inAbort();
296
297 /**
298 Can this transaction handles post termination work
299 */
300 public abstract boolean handlesPostTerminationWork();
301
302 /**
303 Make this transaction aware that it is being used by recovery
304 */
305 public abstract void recoveryTransaction();
306
307 /**
308 Allow my users to notigy my observers.
309 */
310 public void notifyObservers(Object arg) {
311 if (countObservers() != 0) {
312 setChanged();
313 super.notifyObservers(arg);
314 }
315 }
316
317
318 /**
319 *Retunrs true if the transaction is part of rollforward recovery
320 */
321 public abstract boolean inRollForwardRecovery();
322
323
324 /**
325 * redo a checkpoint during rollforward recovery
326 */
327 public abstract void checkpointInRollForwardRecovery(LogInstant cinstant,
328 long redoLWM)
329 throws StandardException;
330
331 }
332
333