org.apache.derby.iapi.store.raw
Interface Loggable

All Superinterfaces:
java.io.Externalizable, Formatable, java.io.Serializable, TypedFormat
All Known Subinterfaces:
Compensation, LogicalUndoable, Undoable
All Known Implementing Classes:
BeginXact, CheckpointOperation, ChecksumOperation, ContainerBasicOperation, ContainerOperation, ContainerUndoOperation, EndXact, LogicalPageOperation, LogicalUndoOperation, PageBasicOperation, PhysicalPageOperation, PhysicalUndoOperation, RemoveFileOperation

public interface Loggable
extends Formatable

A Loggable is a record of a change of state or an event that happened in the RawStore in the context of a transaction. All changes in the RawStore must be logged. This is the root class for all log operations.

See Also:
Transaction.logAndDo(org.apache.derby.iapi.store.raw.Loggable)

Field Summary
static int ABORT
           
static int BI_LOG
           
static int CHECKSUM
           
static int COMMIT
           
static int COMPENSATION
           
static int FILE_RESOURCE
           
static int FIRST
          Each loggable belongs to one or more groups of similar functionality.
static int LAST
           
static int PREPARE
           
static int RAWSTORE
           
static int XA_NEEDLOCK
           
 
Method Summary
 void doMe(Transaction xact, LogInstant instant, LimitObjectInput in)
          Apply the change indicated by this operation and optional data.
 ByteArray getPreparedLog()
          The log operations are responsible to create the ByteArray, and the log operations should write out any optional data for the change to the ByteArray.
 int group()
          Get the loggable's group value
 boolean needsRedo(Transaction xact)
          Determine if the operation should be reapplied in recovery redo.
 void releaseResource(Transaction xact)
          Release any resource that was acquired for doMe for rollback or recovery redo.
 
Methods inherited from interface java.io.Externalizable
readExternal, writeExternal
 
Methods inherited from interface org.apache.derby.iapi.services.io.TypedFormat
getTypeFormatId
 

Field Detail

FIRST

public static final int FIRST
Each loggable belongs to one or more groups of similar functionality. Grouping is a way to quickly sort out log records that are interesting to different modules or different implementations. When a module makes loggable and sent it to the log file, it must mark this loggable with one or more of the following group. If none fit, or if the loggable encompasses functionality that is not described in existing groups, then a new group should be introduced. Grouping has no effect on how the record is logged or how it is treated in rollback or recovery. The following groups are defined. This list serves as the registry of all loggable groups.

See Also:
Constant Field Values

LAST

public static final int LAST
See Also:
Constant Field Values

COMPENSATION

public static final int COMPENSATION
See Also:
Constant Field Values

BI_LOG

public static final int BI_LOG
See Also:
Constant Field Values

COMMIT

public static final int COMMIT
See Also:
Constant Field Values

ABORT

public static final int ABORT
See Also:
Constant Field Values

PREPARE

public static final int PREPARE
See Also:
Constant Field Values

XA_NEEDLOCK

public static final int XA_NEEDLOCK
See Also:
Constant Field Values

RAWSTORE

public static final int RAWSTORE
See Also:
Constant Field Values

FILE_RESOURCE

public static final int FILE_RESOURCE
See Also:
Constant Field Values

CHECKSUM

public static final int CHECKSUM
See Also:
Constant Field Values
Method Detail

doMe

public void doMe(Transaction xact,
                 LogInstant instant,
                 LimitObjectInput in)
          throws StandardException,
                 java.io.IOException
Apply the change indicated by this operation and optional data. If this method fail, the system will be shut down because the log record has already been written to disk. Moreover, the log record will be replayed during recovery and this doMe method will be called on the same page again, so if it fails again, recovery will fail and the database cannot be started. So it is very important to make sure that every resource you need, such as disk space, has been acquired before the logAndDo method is called!
This method cannot acquire any resource (like latching of a page) since it is called underneath the logging system, ie., the log record has already been written to the log stream.

The available() method of in indicates how much data can be read, i.e. how much was originally written.

Parameters:
xact - the Transaction
instant - the log instant of this operation
in - optional data
Throws:
java.io.IOException - Can be thrown by any of the methods of in.
StandardException - Standard Cloudscape policy.

getPreparedLog

public ByteArray getPreparedLog()
                         throws StandardException
The log operations are responsible to create the ByteArray, and the log operations should write out any optional data for the change to the ByteArray. The ByteArray can be prepared when the log operation is constructed, or it can be prepared when getPreparedLog() is called. Called by the log manager to allow the log operation to pass the buffer which contains optional data that will be available in to doMe() methods.

Throws:
StandardException - Standard Cloudscape policy.

needsRedo

public boolean needsRedo(Transaction xact)
                  throws StandardException
Determine if the operation should be reapplied in recovery redo. If redo is needed, acquire any resource that is necessary for the loggable's doMe method. These need to be released in the releaseResource method.

The sequence of events in recovery redo of a Loggable operation is:

  • Get the loggable operation. If loggable.needsRedo is false, then no need to redo this operation.
  • If loggable.needsRedo is true, all the resources necessary for applying the doMe is acquired in needsRedo.
  • If the loggable is actually a compensation operation, then the logging system will find the undoable operation that needs to be undone, call compensation.setUndoOp with the undoable operation.
  • The recovery system then calls loggable.doMe, which re-applies the loggable operation, or re-applies the compensation operation
  • The recovery system then calls loggable.releaseResource.

    Parameters:
    xact - The transaction trying to redo this operation
    Returns:
    true if operation needs redoing, false if not.
    Throws:
    StandardException - Standard Cloudscape policy.
    See Also:
    releaseResource(org.apache.derby.iapi.store.raw.Transaction)

  • releaseResource

    public void releaseResource(Transaction xact)
    Release any resource that was acquired for doMe for rollback or recovery redo. This resource is acquired in either generateUndo (if this is a compensation operation during run time rollback or recovery rollback) or in needsRedo (if this is during recovery redo). The run time transaction context should have all the resource already acquird for run time roll forward, so there is no need to releaseResource during run time roll forward. This method must be safe to be called multiple times.


    group

    public int group()
    Get the loggable's group value


    Built on Tue 2006-10-10 19:23:47+0200, from revision exported

    Apache Derby V10.1 Engine Documentation - Copyright © 1997,2005 The Apache Software Foundation or its licensors, as applicable.