| 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 | |
| 114 | @see Compensation |
| 115 | |
| 116 | @exception StandardException Standard cloudscape exception policy |
| 117 | */ |
| 118 | public abstract void logAndUndo(Compensation compensation, LogInstant undoInstant, |
| 119 | LimitObjectInput in) |
| 120 | throws StandardException; |
| 121 | |
| 122 | /** Methods to help logging and recovery */ |
| 123 | |
| 124 | /** |
| 125 | Set the transaction Ids (Global and internal) of this transaction |
| 126 | */ |
| 127 | public abstract void setTransactionId(GlobalTransactionId id, TransactionId shortId); |
| 128 | |
| 129 | /** |
| 130 | Set the transactionId (Global and internal) of this transaction using a |
| 131 | log record that contains the Global id |
| 132 | */ |
| 133 | abstract public void setTransactionId(Loggable beginXact, TransactionId shortId); |
| 134 | |
| 135 | |
| 136 | /** |
| 137 | Get the shortId of this transaction. May return null if transactio |
| 138 | has no ID. |
| 139 | */ |
| 140 | abstract public TransactionId getId(); |
| 141 | |
| 142 | /** |
| 143 | Get the shortId of this transaction. May return null if transactio |
| 144 | has no ID. |
| 145 | */ |
| 146 | abstract public GlobalTransactionId getGlobalId(); |
| 147 | |
| 148 | /** |
| 149 | Add this raw transaction on to the list of update transaction |
| 150 | */ |
| 151 | public abstract void addUpdateTransaction(int transactionStatus); |
| 152 | |
| 153 | /** |
| 154 | Remove this raw transaction from the list of update transaction |
| 155 | */ |
| 156 | public abstract void removeUpdateTransaction(); |
| 157 | |
| 158 | /** |
| 159 | Change the state of transaction in table to prepare. |
| 160 | */ |
| 161 | public abstract void prepareTransaction(); |
| 162 | |
| 163 | /** |
| 164 | Set the log instant for the first log record written by this |
| 165 | transaction. |
| 166 | */ |
| 167 | abstract public void setFirstLogInstant(LogInstant instant); |
| 168 | |
| 169 | /** |
| 170 | Get the log instant for the first log record written by this |
| 171 | transaction. |
| 172 | */ |
| 173 | abstract public LogInstant getFirstLogInstant(); |
| 174 | |
| 175 | /** |
| 176 | Set the log instant for the last log record written by this transaction. |
| 177 | */ |
| 178 | abstract public void setLastLogInstant(LogInstant instant); |
| 179 | |
| 180 | /** |
| 181 | Get the log instant for the last log record written by this transaction. |
| 182 | If the transaction is unclear what its last log instant is, |
| 183 | than it may return null. |
| 184 | */ |
| 185 | abstract public LogInstant getLastLogInstant(); |
| 186 | |
| 187 | |
| 188 | /** |
| 189 | Check to see if a logical operation is allowed by this transaction, |
| 190 | throws a TransactionExceotion if it isn't. This implementation allows |
| 191 | logical operations. Transactions that need to disallow logical |
| 192 | operations should hide this method. |
| 193 | |
| 194 | @exception StandardException Standard Cloudscape error policy, |
| 195 | */ |
| 196 | public void checkLogicalOperationOk() throws StandardException { |
| 197 | } |
| 198 | |
| 199 | /** |
| 200 | Return true if this transaction should be rolled back first |
| 201 | in recovery. This implementation returns false. Transactions that |
| 202 | need to rollback first during recovery should hide this method. |
| 203 | */ |
| 204 | public boolean recoveryRollbackFirst() { |
| 205 | return false; |
| 206 | } |
| 207 | |
| 208 | /** |
| 209 | * During recovery re-prepare a transaction. |
| 210 | * <p> |
| 211 | * After redo() and undo(), this routine is called on all outstanding |
| 212 | * in-doubt (prepared) transactions. This routine re-acquires all |
| 213 | * logical write locks for operations in the xact, and then modifies |
| 214 | * the transaction table entry to make the transaction look as if it |
| 215 | * had just been prepared following startup after recovery. |
| 216 | * <p> |
| 217 | * |
| 218 | * @exception StandardException Standard exception policy. |
| 219 | **/ |
| 220 | abstract public void reprepare() |
| 221 | 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() throws StandardException; |
| 249 | |
| 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 | /** |
| 283 | Status that needs to go into the begin transaction log record, if there |
| 284 | is one, to help with recovery |
| 285 | */ |
| 286 | protected abstract int statusForBeginXactLog(); |
| 287 | |
| 288 | /** |
| 289 | Status that needs to go into the end transaction log record, if there |
| 290 | is one, to help with recovery |
| 291 | */ |
| 292 | protected abstract int statusForEndXactLog(); |
| 293 | |
| 294 | /** |
| 295 | Is the transaction in the middle of an abort. |
| 296 | */ |
| 297 | public abstract boolean inAbort(); |
| 298 | |
| 299 | /** |
| 300 | Can this transaction handles post termination work |
| 301 | */ |
| 302 | public abstract boolean handlesPostTerminationWork(); |
| 303 | |
| 304 | /** |
| 305 | Make this transaction aware that it is being used by recovery |
| 306 | */ |
| 307 | public abstract void recoveryTransaction(); |
| 308 | |
| 309 | /** |
| 310 | Allow my users to notigy my observers. |
| 311 | */ |
| 312 | public void notifyObservers(Object arg) { |
| 313 | if (countObservers() != 0) { |
| 314 | setChanged(); |
| 315 | super.notifyObservers(arg); |
| 316 | } |
| 317 | } |
| 318 | |
| 319 | |
| 320 | /** |
| 321 | *Retunrs true if the transaction is part of rollforward recovery |
| 322 | */ |
| 323 | public abstract boolean inRollForwardRecovery(); |
| 324 | |
| 325 | |
| 326 | /** |
| 327 | * redo a checkpoint during rollforward recovery |
| 328 | */ |
| 329 | public abstract void checkpointInRollForwardRecovery(LogInstant cinstant, |
| 330 | long redoLWM) |
| 331 | throws StandardException; |
| 332 | |
| 333 | |
| 334 | /* |
| 335 | * Make the transaction block the online backup. |
| 336 | * |
| 337 | * @param wait if <tt>true</tt>, waits until the transaction |
| 338 | * can block the backup. |
| 339 | * @return <tt>true</tt> if the transaction blocked the |
| 340 | * backup. <tt>false</tt> otherwise. |
| 341 | * @exception StandardException if interrupted while waiting |
| 342 | * for the backup in progress to complete. |
| 343 | */ |
| 344 | public abstract boolean blockBackup(boolean wait) |
| 345 | throws StandardException; |
| 346 | |
| 347 | /** |
| 348 | * Check if the transaction is blocking the backup ? |
| 349 | * @return <tt> true </tt> if this transaction is |
| 350 | * blocking the backup, otherwise <tt> false </tt> |
| 351 | */ |
| 352 | public abstract boolean isBlockingBackup(); |
| 353 | |
| 354 | } |
| 355 | |
| 356 | |