KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > access > conglomerate > LogicalUndo


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 JavaDoc;
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 Cloudscape 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 JavaDoc;
133 }
134
135
Popular Tags