001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.conglomerate.LogicalUndo
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.access.conglomerate;
023:
024: import org.apache.derby.iapi.error.StandardException;
025: import org.apache.derby.iapi.store.raw.LogicalUndoable;
026: import org.apache.derby.iapi.store.raw.Page;
027: import org.apache.derby.iapi.store.raw.Transaction;
028:
029: import org.apache.derby.iapi.services.io.LimitObjectInput;
030: import java.io.IOException;
031:
032: /**
033: A Logical undo is an undo operation that operates on a different page
034: from the page that has the original change. The reason one would
035: need logical undo is when an uncommitted row move from one page to
036: another in a nested internal transaction which is committed. For
037: example, an uncommitted insert on a btree may be moved by a later split
038: operation to another page, the split operation will have committed. If
039: the insert needs to be rolled back, it can only be found at the new
040: page where the split puts it and not at the original page where it is
041: inserted.
042: <P>
043: The logging and recovery system does not know how to do logical undo.
044: Client of the logging system must provide it with a call back function
045: so that during undo time (both runtime undo and recovery undo), the
046: appropriate page and row can be found so that the logging system can
047: apply the log's undo operation.
048: <P>
049: Any log operation that needs logical undo must implement this
050: LogicalUndo interface, which serves the purpose of a callback function
051: pointer. This callback function findUndoInfo is called by log operation
052: generateUndo and will be given all the information in the log operation.
053: <P>
054: FindUndo uses the information in the pageOp to find the correct page
055: and record that needs to be rolled back, i.e., a latched page
056: (undoPage) and the recordId (undoRID). It returns the latched
057: undoPage, and modifies the pageOp to contain the correct segmentId,
058: containerId, pageNumber and recordId etc. It also need to supply a
059: releaseResource() method that the logging system can call to unlatch
060: the page and release the container, etc, after the undo has been
061: applied.
062: <P>
063: The logging system will use the information in the undoPackage to put
064: together a Compensation operation which has the undoPage number
065: and undoRID. Logical Undo is only called during the generation of a
066: CLR, never during recovery redo.
067: <P>
068: <B>Note: LogicalUndo is a call back function pointer that will be
069: written out as part of the log operation, it should not contain any
070: non-transient member fields </B>
071: <P>
072: Details.
073: <P>
074: LogicalUndo, and LogicalUndoable is the interface used by logical undo
075: between the logging system in RawStore and Access. A log operation
076: that needs logical undo should implment LogicalUndoable intead of
077: Undoable. A LogicalUndoable log operation contains a LogicalUndo
078: member field, which is a function pointer to an Access function that
079: provides the logical undo logic of, say, traversing a btree.
080: <P>
081: When called to generateUndo, that LogicalUndoable log operation will
082: call LogicalUndo.findUndo instead of relying on the page number and
083: recordId that is stored in it during the runtime roll forward
084: operation. <B>The logging system opens the container before it calls
085: findUndo, therefore the container where the log operation is applied
086: cannot between rollforward and rollback.</B>
087: <P>
088: In LogicalUndo.findUndo, it can use information stored in
089: the LogicalUndoable, such as pageNumber, containerId, to come up with a
090: template row. It can then ask the LogicalUndoable log record
091: to restore a row from the log record that fits the template. Using
092: this restored row, LogicalUndo can, e.g., restore the key to the btree
093: and traverses the btree. Once it finds the correct RecordHandle where
094: the rollback should go, findUndo should call pageOp.resetRecord and
095: return a latched page where the undo should go.
096: <P>
097: Upon the return of findUndo, the LogicalUndoable log operation should
098: have information about the new RecordHandle and the page should be
099: return latched. A compensation operation is then generated with the
100: new record location and undoMe is applied on the correct location.
101: <P>
102: The logging system will unlatch the undoPage when it is done with
103: rollback and will close the container.
104:
105: @see org.apache.derby.iapi.store.raw.LogicalUndoable
106: @see org.apache.derby.iapi.store.raw.Undoable#generateUndo
107: */
108:
109: public interface LogicalUndo {
110:
111: /**
112: Find the page and record to undo. If no logical undo is necessary,
113: i.e., row has not moved, then just return the latched page where undo
114: should go. If the record has moved, it has a new recordId on the new
115: page, this routine needs to call pageOp.resetRecord with the new
116: RecordHandle so that the logging system can update the compensation
117: Operation with the new location.
118:
119: @param transaction the transaction doing the rollback
120: @param pageOp the page operation that supports logical undo. This
121: LogicalUndo function pointer is a field of that pageOperation
122: @param in data stored in the log stream that contains the record data
123: necessary to restore the row.
124:
125: @exception StandardException Standard Cloudscape error policy
126: @exception IOException Method may read from InputStream
127: */
128: public Page findUndo(Transaction transaction,
129: LogicalUndoable pageOp, LimitObjectInput in)
130: throws StandardException, IOException;
131: }
|