Class ContainerOperation

java.lang.Object
org.apache.derby.impl.store.raw.data.ContainerBasicOperation
org.apache.derby.impl.store.raw.data.ContainerOperation
All Implemented Interfaces:
Externalizable, Serializable, Formatable, TypedFormat, Loggable, Undoable

public class ContainerOperation extends ContainerBasicOperation implements Undoable
Log operation to create, drop or remove a container. Both the doMe or the undoMe of a create actually caused the container header to be modified and flushed before the log record is flushed. This is necessary for 2 reasons, one is that of ensuring enough disk space, and the other is because unlike any other operation, the log record create container is in the log stream before the container is in the container cache. What this mean is that if a checkpoint started after the container operation but before the container is kept or is dirtied in the container cache, then checkpoint will not know to wait for the container to be kept or cleaned. The checkpoint will erroneous assume that the operation does not need to be redone since its log instant is before the checkpoint but in fact the change has not been flushed to disk. A drop or remove container does not have this problem. The container exist and is in kept state when the operation is logged so the checkpoint will not overlook it and it doesn't need to flush the container header. In the case of remove, the stub is flushed for a different reason - that of ensuring disk space.
See Also:
  • Field Details

    • operation

      protected byte operation
    • hasCreateByteArray

      protected transient boolean hasCreateByteArray
    • createByteArray

      protected ByteArray createByteArray
    • CREATE

      protected static final byte CREATE
      See Also:
    • DROP

      protected static final byte DROP
      See Also:
    • REMOVE

      protected static final byte REMOVE
      See Also:
  • Constructor Details

  • Method Details

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Specified by:
      writeExternal in interface Externalizable
      Overrides:
      writeExternal in class ContainerBasicOperation
      Throws:
      IOException
    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Specified by:
      readExternal in interface Externalizable
      Overrides:
      readExternal in class ContainerBasicOperation
      Throws:
      IOException - cannot read log record from log stream
      ClassNotFoundException - cannot read ByteArray object
    • getTypeFormatId

      public int getTypeFormatId()
      Return my format identifier.
      Specified by:
      getTypeFormatId in interface TypedFormat
      Returns:
      The identifier. (A UUID stuffed in an array of 16 bytes).
    • findContainerForRedoRecovery

      protected RawContainerHandle findContainerForRedoRecovery(RawTransaction xact) throws StandardException
      Find container for load tran.

      If we are in load tran, and the operation is a create, the container may not (should not?) exist yet. We need to recreate it.

      Overrides:
      findContainerForRedoRecovery in class ContainerBasicOperation
      Throws:
      StandardException - Standard Derby error policy.
    • doMe

      public final void doMe(Transaction tran, LogInstant instant, LimitObjectInput in) throws StandardException
      Description copied from interface: Loggable
      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.

      Specified by:
      doMe in interface Loggable
      Parameters:
      tran - the Transaction
      instant - the log instant of this operation
      in - optional data
      Throws:
      StandardException - Standard Derby error policy
    • undoMe

      public void undoMe(Transaction tran, RawContainerHandle hdl, LogInstant CLRInstant, LimitObjectInput in) throws StandardException
      Undo of create, drop or remove
      Parameters:
      tran - the transaction that is undoing this operation
      hdl - the container handle. This is found here during runtime undo - in which case we made the CLR and passed in the containerHdl found in generateUndo and it is passed back to this; or it is found in the CLR's needsRedo and is passed in and this operation never found the container. Either case, release resource at the end is safe
      CLRInstant - the log instant of the CLR
      in - optional data
      Throws:
      StandardException - Standard Derby error policy
    • generateUndo

      public Compensation generateUndo(Transaction tran, LimitObjectInput in) throws StandardException
      Description copied from interface: Undoable
      Generate a loggable which will undo this change, using the optional input if necessary.

      NOTE
      Any logical undo logic must be hidden behind generateUndo. During recovery redo, it should not depend on any logical undo logic.

      There are 3 ways to implement a redo-only log record:

    • Make the log record a Loggable instead of an Undoable, this is the cleanest method.
    • If you want to extend a log operation class that is an Undoable, you can then either have generateUndo return null - this is preferred - (the log operation's undoMe should never be called, so you can put a null body there if the super class you are extending does not implement a undoMe).
    • Or, have undoMe do nothing - this is least preferred.

      Any resource (e.g., latched page) that is needed for the undoable.undoMe() must be acquired in undoable.generateUndo(). Moreover, that resource must be identified in the compensation operation, and reacquired in the compensation.needsRedo() method during recovery redo.
      If you do write your own generateUndo or needsRedo, any resource you latch or acquire, you must release them in Compensation.doMe() or in Compensation.releaseResource().

      To write a generateUndo operation, find the object that needs to be rolled back. Assuming that it is a page, latch it, put together a Compensation operation with the undoOp set to this operation, and save the page number in the compensation operation, then return the Compensation operation to the logging system.

      The sequence of events in a rollback of a undoable operation is

    • The logging system calls undoable.generateUndo. If this returns null, then there is nothing to undo.
    • If generateUndo returns a Compensation operation, then the logging system will log the Compensation log record and call Compenstation.doMe(). (Hopefully, this just calls the undoable's undoMe)
    • After the Compensation operation has been applied, the logging system will call compensation.releaseResource(). If you do overwrite a super class's releaseResource(), it would be prudent to call super.releaseResource() first.

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

    • Specified by:
      generateUndo in interface Undoable
      Parameters:
      tran - the transaction doing the rollback
      Returns:
      the compensation operation that will rollback this change, or null if nothing to undo.
      Throws:
      StandardException - Standard Derby error policy
      See Also:
    • toString

      public String toString()
      debug
      Overrides:
      toString in class ContainerBasicOperation