Save This Page
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.access.conglomerate.LogicalUndo
4
5 Licensed to the Apache Software Foundation (ASF) under one or more
6 contributor license agreements. See the NOTICE file distributed with
7 this work for additional information regarding copyright ownership.
8 The ASF licenses this file to you under the Apache License, Version 2.0
9 (the "License"); you may not use this file except in compliance with
10 the License. You may obtain a copy of the License at
11
12 http://www.apache.org/licenses/LICENSE-2.0
13
14 Unless required by applicable law or agreed to in writing, software
15 distributed under the License is distributed on an "AS IS" BASIS,
16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 See the License for the specific language governing permissions and
18 limitations under the License.
19
20 */
21
22 package org.apache.derby.iapi.store.access.conglomerate;
23
24 import org.apache.derby.iapi.error.StandardException;
25 import org.apache.derby.iapi.store.raw.LogicalUndoable;
26 import org.apache.derby.iapi.store.raw.Page;
27 import org.apache.derby.iapi.store.raw.Transaction;
28
29 import org.apache.derby.iapi.services.io.LimitObjectInput;
30 import java.io.IOException;
31
32 /**
33 A Logical undo is an undo operation that operates on a different page
34 from the page that has the original change. The reason one would
35 need logical undo is when an uncommitted row move from one page to
36 another in a nested internal transaction which is committed. For
37 example, an uncommitted insert on a btree may be moved by a later split
38 operation to another page, the split operation will have committed. If
39 the insert needs to be rolled back, it can only be found at the new
40 page where the split puts it and not at the original page where it is
41 inserted.
42 <P>
43 The logging and recovery system does not know how to do logical undo.
44 Client of the logging system must provide it with a call back function
45 so that during undo time (both runtime undo and recovery undo), the
46 appropriate page and row can be found so that the logging system can
47 apply the log's undo operation.
48 <P>
49 Any log operation that needs logical undo must implement this
50 LogicalUndo interface, which serves the purpose of a callback function
51 pointer. This callback function findUndoInfo is called by log operation
52 generateUndo and will be given all the information in the log operation.
53 <P>
54 FindUndo uses the information in the pageOp to find the correct page
55 and record that needs to be rolled back, i.e., a latched page
56 (undoPage) and the recordId (undoRID). It returns the latched
57 undoPage, and modifies the pageOp to contain the correct segmentId,
58 containerId, pageNumber and recordId etc. It also need to supply a
59 releaseResource() method that the logging system can call to unlatch
60 the page and release the container, etc, after the undo has been
61 applied.
62 <P>
63 The logging system will use the information in the undoPackage to put
64 together a Compensation operation which has the undoPage number
65 and undoRID. Logical Undo is only called during the generation of a
66 CLR, never during recovery redo.
67 <P>
68 <B>Note: LogicalUndo is a call back function pointer that will be
69 written out as part of the log operation, it should not contain any
70 non-transient member fields </B>
71 <P>
72 Details.
73 <P>
74 LogicalUndo, and LogicalUndoable is the interface used by logical undo
75 between the logging system in RawStore and Access. A log operation
76 that needs logical undo should implment LogicalUndoable intead of
77 Undoable. A LogicalUndoable log operation contains a LogicalUndo
78 member field, which is a function pointer to an Access function that
79 provides the logical undo logic of, say, traversing a btree.
80 <P>
81 When called to generateUndo, that LogicalUndoable log operation will
82 call LogicalUndo.findUndo instead of relying on the page number and
83 recordId that is stored in it during the runtime roll forward
84 operation. <B>The logging system opens the container before it calls
85 findUndo, therefore the container where the log operation is applied
86 cannot between rollforward and rollback.</B>
87 <P>
88 In LogicalUndo.findUndo, it can use information stored in
89 the LogicalUndoable, such as pageNumber, containerId, to come up with a
90 template row. It can then ask the LogicalUndoable log record
91 to restore a row from the log record that fits the template. Using
92 this restored row, LogicalUndo can, e.g., restore the key to the btree
93 and traverses the btree. Once it finds the correct RecordHandle where
94 the rollback should go, findUndo should call pageOp.resetRecord and
95 return a latched page where the undo should go.
96 <P>
97 Upon the return of findUndo, the LogicalUndoable log operation should
98 have information about the new RecordHandle and the page should be
99 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 Derby error policy
126 @exception IOException Method may read from InputStream
127 */
128 public Page findUndo(
129 Transaction transaction,
130 LogicalUndoable pageOp,
131 LimitObjectInput in)
132 throws StandardException, IOException;
133 }
134