Source code: org/apache/derby/iapi/store/access/conglomerate/LogicalUndo.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.access.conglomerate.LogicalUndo
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.access.conglomerate;
22
23 import org.apache.derby.iapi.error.StandardException;
24 import org.apache.derby.iapi.store.raw.LogicalUndoable;
25 import org.apache.derby.iapi.store.raw.Page;
26 import org.apache.derby.iapi.store.raw.Transaction;
27
28 import org.apache.derby.iapi.services.io.LimitObjectInput;
29 import java.io.IOException;
30
31 /**
32 A Logical undo is an undo operation that operates on a different page
33 from the page that has the original change. The reason one would
34 need logical undo is when an uncommitted row move from one page to
35 another in a nested internal transaction which is committed. For
36 example, an uncommitted insert on a btree may be moved by a later split
37 operation to another page, the split operation will have committed. If
38 the insert needs to be rolled back, it can only be found at the new
39 page where the split puts it and not at the original page where it is
40 inserted.
41 <P>
42 The logging and recovery system does not know how to do logical undo.
43 Client of the logging system must provide it with a call back function
44 so that during undo time (both runtime undo and recovery undo), the
45 appropriate page and row can be found so that the logging system can
46 apply the log's undo operation.
47 <P>
48 Any log operation that needs logical undo must implement this
49 LogicalUndo interface, which serves the purpose of a callback function
50 pointer. This callback function findUndoInfo is called by log operation
51 generateUndo and will be given all the information in the log operation.
52 <P>
53 FindUndo uses the information in the pageOp to find the correct page
54 and record that needs to be rolled back, i.e., a latched page
55 (undoPage) and the recordId (undoRID). It returns the latched
56 undoPage, and modifies the pageOp to contain the correct segmentId,
57 containerId, pageNumber and recordId etc. It also need to supply a
58 releaseResource() method that the logging system can call to unlatch
59 the page and release the container, etc, after the undo has been
60 applied.
61 <P>
62 The logging system will use the information in the undoPackage to put
63 together a Compensation operation which has the undoPage number
64 and undoRID. Logical Undo is only called during the generation of a
65 CLR, never during recovery redo.
66 <P>
67 <B>Note: LogicalUndo is a call back function pointer that will be
68 written out as part of the log operation, it should not contain any
69 non-transient member fields </B>
70 <P>
71 Details.
72 <P>
73 LogicalUndo, and LogicalUndoable is the interface used by logical undo
74 between the logging system in RawStore and Access. A log operation
75 that needs logical undo should implment LogicalUndoable intead of
76 Undoable. A LogicalUndoable log operation contains a LogicalUndo
77 member field, which is a function pointer to an Access function that
78 provides the logical undo logic of, say, traversing a btree.
79 <P>
80 When called to generateUndo, that LogicalUndoable log operation will
81 call LogicalUndo.findUndo instead of relying on the page number and
82 recordId that is stored in it during the runtime roll forward
83 operation. <B>The logging system opens the container before it calls
84 findUndo, therefore the container where the log operation is applied
85 cannot between rollforward and rollback.</B>
86 <P>
87 In LogicalUndo.findUndo, it can use information stored in
88 the LogicalUndoable, such as pageNumber, containerId, to come up with a
89 template row. It can then ask the LogicalUndoable log record
90 to restore a row from the log record that fits the template. Using
91 this restored row, LogicalUndo can, e.g., restore the key to the btree
92 and traverses the btree. Once it finds the correct RecordHandle where
93 the rollback should go, findUndo should call pageOp.resetRecord and
94 return a latched page where the undo should go.
95 <P>
96 Upon the return of findUndo, the LogicalUndoable log operation should
97 have information about the new RecordHandle and the page should be
98 return latched. A compensation operation is then generated with the
99 new record location and undoMe is applied on the correct location.
100 <P>
101 The logging system will unlatch the undoPage when it is done with
102 rollback and will close the container.
103
104 @see org.apache.derby.iapi.store.raw.LogicalUndoable
105 @see org.apache.derby.iapi.store.raw.Undoable#generateUndo
106 */
107
108 public interface LogicalUndo {
109
110 /**
111 Find the page and record to undo. If no logical undo is necessary,
112 i.e., row has not moved, then just return the latched page where undo
113 should go. If the record has moved, it has a new recordId on the new
114 page, this routine needs to call pageOp.resetRecord with the new
115 RecordHandle so that the logging system can update the compensation
116 Operation with the new location.
117
118 @param transaction the transaction doing the rollback
119 @param pageOp the page operation that supports logical undo. This
120 LogicalUndo function pointer is a field of that pageOperation
121 @param in data stored in the log stream that contains the record data
122 necessary to restore the row.
123
124 @exception StandardException Standard Cloudscape error policy
125 @exception IOException Method may read from InputStream
126 */
127 public Page findUndo(
128 Transaction transaction,
129 LogicalUndoable pageOp,
130 LimitObjectInput in)
131 throws StandardException, IOException;
132 }
133