Interface LogicalUndo

  • All Known Implementing Classes:
    B2IUndo

    public interface LogicalUndo
    A Logical undo is an undo operation that operates on a different page from the page that has the original change. The reason one would need logical undo is when an uncommitted row move from one page to another in a nested internal transaction which is committed. For example, an uncommitted insert on a btree may be moved by a later split operation to another page, the split operation will have committed. If the insert needs to be rolled back, it can only be found at the new page where the split puts it and not at the original page where it is inserted.

    The logging and recovery system does not know how to do logical undo. Client of the logging system must provide it with a call back function so that during undo time (both runtime undo and recovery undo), the appropriate page and row can be found so that the logging system can apply the log's undo operation.

    Any log operation that needs logical undo must implement this LogicalUndo interface, which serves the purpose of a callback function pointer. This callback function findUndoInfo is called by log operation generateUndo and will be given all the information in the log operation.

    FindUndo uses the information in the pageOp to find the correct page and record that needs to be rolled back, i.e., a latched page (undoPage) and the recordId (undoRID). It returns the latched undoPage, and modifies the pageOp to contain the correct segmentId, containerId, pageNumber and recordId etc. It also need to supply a releaseResource() method that the logging system can call to unlatch the page and release the container, etc, after the undo has been applied.

    The logging system will use the information in the undoPackage to put together a Compensation operation which has the undoPage number and undoRID. Logical Undo is only called during the generation of a CLR, never during recovery redo.

    Note: LogicalUndo is a call back function pointer that will be written out as part of the log operation, it should not contain any non-transient member fields

    Details.

    LogicalUndo, and LogicalUndoable is the interface used by logical undo between the logging system in RawStore and Access. A log operation that needs logical undo should implment LogicalUndoable intead of Undoable. A LogicalUndoable log operation contains a LogicalUndo member field, which is a function pointer to an Access function that provides the logical undo logic of, say, traversing a btree.

    When called to generateUndo, that LogicalUndoable log operation will call LogicalUndo.findUndo instead of relying on the page number and recordId that is stored in it during the runtime roll forward operation. The logging system opens the container before it calls findUndo, therefore the container where the log operation is applied cannot between rollforward and rollback.

    In LogicalUndo.findUndo, it can use information stored in the LogicalUndoable, such as pageNumber, containerId, to come up with a template row. It can then ask the LogicalUndoable log record to restore a row from the log record that fits the template. Using this restored row, LogicalUndo can, e.g., restore the key to the btree and traverses the btree. Once it finds the correct RecordHandle where the rollback should go, findUndo should call pageOp.resetRecord and return a latched page where the undo should go.

    Upon the return of findUndo, the LogicalUndoable log operation should have information about the new RecordHandle and the page should be return latched. A compensation operation is then generated with the new record location and undoMe is applied on the correct location.

    The logging system will unlatch the undoPage when it is done with rollback and will close the container.

    See Also:
    LogicalUndoable, Undoable.generateUndo(org.apache.derby.iapi.store.raw.Transaction, org.apache.derby.iapi.services.io.LimitObjectInput)
    • Method Detail

      • findUndo

        Page findUndo​(Transaction transaction,
                      LogicalUndoable pageOp,
                      LimitObjectInput in)
               throws StandardException,
                      java.io.IOException
        Find the page and record to undo. If no logical undo is necessary, i.e., row has not moved, then just return the latched page where undo should go. If the record has moved, it has a new recordId on the new page, this routine needs to call pageOp.resetRecord with the new RecordHandle so that the logging system can update the compensation Operation with the new location.
        Parameters:
        transaction - the transaction doing the rollback
        pageOp - the page operation that supports logical undo. This LogicalUndo function pointer is a field of that pageOperation
        in - data stored in the log stream that contains the record data necessary to restore the row.
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - Method may read from InputStream