001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.Undoable
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;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: import org.apache.derby.iapi.services.io.LimitObjectInput;
027: import java.io.IOException;
028:
029: /**
030: An Undoable operation is an operation that changed the state of the RawStore
031: in the context of a transaction and this change can be rolled back.
032:
033: @see Transaction#logAndDo
034: @see Compensation
035: */
036:
037: public interface Undoable extends Loggable {
038:
039: /**
040: Generate a loggable which will undo this change, using the optional
041: input if necessary.
042:
043: <P><B>NOTE</B><BR>Any logical undo logic must be hidden behind generateUndo.
044: During recovery redo, it should not depend on any logical undo logic.
045:
046: <P>
047: There are 3 ways to implement a redo-only log record:
048: <NL>
049: <LI>Make the log record a Loggable instead of an Undoable, this is the
050: cleanest method.
051: <LI>If you want to extend a log operation class that is an Undoable,
052: you can then either have generateUndo return null - this is preferred -
053: (the log operation's undoMe should never be called, so you can put a
054: null body there if the super class you are extending does not implement
055: a undoMe).
056: <LI>Or, have undoMe do nothing - this is least preferred.
057: </NL>
058:
059: <P>Any resource (e.g., latched page) that is needed for the
060: undoable.undoMe() must be acquired in undoable.generateUndo().
061: Moreover, that resource must be identified in the compensation
062: operation, and reacquired in the compensation.needsRedo() method during
063: recovery redo.
064: <BR><B>If you do write your own generateUndo or needsRedo, any
065: resource you latch or acquire, you must release them in
066: Compensation.doMe() or in Compensation.releaseResource().</B>
067:
068: <P> To write a generateUndo operation, find the object that needs to be
069: rolled back. Assuming that it is a page, latch it, put together a
070: Compensation operation with the undoOp set to this operation, and save
071: the page number in the compensation operation, then
072: return the Compensation operation to the logging system.
073:
074: <P>
075: The sequence of events in a rollback of a undoable operation is
076: <NL>
077: <LI> The logging system calls undoable.generateUndo. If this returns
078: null, then there is nothing to undo.
079: <LI> If generateUndo returns a Compensation operation, then the logging
080: system will log the Compensation log record and call
081: Compenstation.doMe(). (Hopefully, this just calls the undoable's
082: undoMe)
083: <LI> After the Compensation operation has been applied, the logging
084: system will call compensation.releaseResource(). If you do overwrite a
085: super class's releaseResource(), it would be prudent to call
086: super.releaseResource() first.
087: </NL>
088:
089: <P> The available() method of in indicates how much data can be read, i.e.
090: how much was originally written.
091:
092: @param xact the transaction doing the rollback
093: @return the compensation operation that will rollback this change, or
094: null if nothing to undo.
095:
096: @exception IOException Can be thrown by any of the methods of ObjectInput.
097: @exception StandardException Standard Cloudscape policy.
098:
099: @see Loggable#releaseResource
100: @see Loggable#needsRedo
101:
102: */
103: public Compensation generateUndo(Transaction xact,
104: LimitObjectInput in) throws StandardException, IOException;
105:
106: }
|