--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.access.conglomerate.LogicalUndo\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.access.conglomerate;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+import org.apache.derby.iapi.store.raw.LogicalUndoable;\r
+import org.apache.derby.iapi.store.raw.Page;\r
+import org.apache.derby.iapi.store.raw.Transaction;\r
+\r
+import org.apache.derby.iapi.services.io.LimitObjectInput;\r
+import java.io.IOException;\r
+\r
+/**\r
+ A Logical undo is an undo operation that operates on a different page\r
+ from the page that has the original change. The reason one would\r
+ need logical undo is when an uncommitted row move from one page to\r
+ another in a nested internal transaction which is committed. For\r
+ example, an uncommitted insert on a btree may be moved by a later split\r
+ operation to another page, the split operation will have committed. If\r
+ the insert needs to be rolled back, it can only be found at the new\r
+ page where the split puts it and not at the original page where it is\r
+ inserted. \r
+ <P>\r
+ The logging and recovery system does not know how to do logical undo.\r
+ Client of the logging system must provide it with a call back function\r
+ so that during undo time (both runtime undo and recovery undo), the\r
+ appropriate page and row can be found so that the logging system can\r
+ apply the log's undo operation.\r
+ <P>\r
+ Any log operation that needs logical undo must implement this\r
+ LogicalUndo interface, which serves the purpose of a callback function\r
+ pointer. This callback function findUndoInfo is called by log operation\r
+ generateUndo and will be given all the information in the log operation.\r
+ <P>\r
+ FindUndo uses the information in the pageOp to find the correct page\r
+ and record that needs to be rolled back, i.e., a latched page\r
+ (undoPage) and the recordId (undoRID). It returns the latched\r
+ undoPage, and modifies the pageOp to contain the correct segmentId,\r
+ containerId, pageNumber and recordId etc. It also need to supply a\r
+ releaseResource() method that the logging system can call to unlatch\r
+ the page and release the container, etc, after the undo has been\r
+ applied.\r
+ <P>\r
+ The logging system will use the information in the undoPackage to put\r
+ together a Compensation operation which has the undoPage number\r
+ and undoRID. Logical Undo is only called during the generation of a\r
+ CLR, never during recovery redo.\r
+ <P>\r
+ <B>Note: LogicalUndo is a call back function pointer that will be\r
+ written out as part of the log operation, it should not contain any\r
+ non-transient member fields </B>\r
+ <P>\r
+ Details.\r
+ <P>\r
+ LogicalUndo, and LogicalUndoable is the interface used by logical undo\r
+ between the logging system in RawStore and Access. A log operation\r
+ that needs logical undo should implment LogicalUndoable intead of\r
+ Undoable. A LogicalUndoable log operation contains a LogicalUndo\r
+ member field, which is a function pointer to an Access function that\r
+ provides the logical undo logic of, say, traversing a btree. \r
+ <P>\r
+ When called to generateUndo, that LogicalUndoable log operation will\r
+ call LogicalUndo.findUndo instead of relying on the page number and\r
+ recordId that is stored in it during the runtime roll forward\r
+ operation. <B>The logging system opens the container before it calls\r
+ findUndo, therefore the container where the log operation is applied\r
+ cannot between rollforward and rollback.</B>\r
+ <P>\r
+ In LogicalUndo.findUndo, it can use information stored in\r
+ the LogicalUndoable, such as pageNumber, containerId, to come up with a\r
+ template row. It can then ask the LogicalUndoable log record\r
+ to restore a row from the log record that fits the template. Using\r
+ this restored row, LogicalUndo can, e.g., restore the key to the btree\r
+ and traverses the btree. Once it finds the correct RecordHandle where\r
+ the rollback should go, findUndo should call pageOp.resetRecord and\r
+ return a latched page where the undo should go.\r
+ <P>\r
+ Upon the return of findUndo, the LogicalUndoable log operation should\r
+ have information about the new RecordHandle and the page should be\r
+ return latched. A compensation operation is then generated with the\r
+ new record location and undoMe is applied on the correct location.\r
+ <P>\r
+ The logging system will unlatch the undoPage when it is done with\r
+ rollback and will close the container.\r
+\r
+ @see org.apache.derby.iapi.store.raw.LogicalUndoable\r
+ @see org.apache.derby.iapi.store.raw.Undoable#generateUndo \r
+*/\r
+\r
+public interface LogicalUndo {\r
+\r
+ /**\r
+ Find the page and record to undo. If no logical undo is necessary,\r
+ i.e., row has not moved, then just return the latched page where undo\r
+ should go. If the record has moved, it has a new recordId on the new\r
+ page, this routine needs to call pageOp.resetRecord with the new\r
+ RecordHandle so that the logging system can update the compensation\r
+ Operation with the new location.\r
+\r
+ @param transaction the transaction doing the rollback\r
+ @param pageOp the page operation that supports logical undo. This\r
+ LogicalUndo function pointer is a field of that pageOperation\r
+ @param in data stored in the log stream that contains the record data\r
+ necessary to restore the row.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+ @exception IOException Method may read from InputStream \r
+ */\r
+ public Page findUndo(\r
+ Transaction transaction, \r
+ LogicalUndoable pageOp,\r
+ LimitObjectInput in)\r
+ throws StandardException, IOException;\r
+}\r
+\r
projects / Benchmarks_CSolver.git / blobdiff