weblogic.transaction
Interface TransactionLoggable

public interface TransactionLoggable

Interface for object capable of being stored in transaction log.

This interface describes the properties of an object suitable for transactional logging and crash recovery via the TranactionLogger class.

TransactionLoggable Object's Life Cycle

1. A TransactionLoggable object is first created and initialized.

2. When it needs to be permanently stored in the transaction log, it is passed to the TransactionLogger.store() method. This enters it in a queue for safe storage on disk.

3. The object's TransactionLoggable.writeExternal() method is invoked to get a permanent representation of the object's state for external storage.

4. After the object is known to be safely stored in the transaction log, its TransactionLoggable.onDisk() callback method is invoked. In the unlikely event of a problem, its onError() callback method is invoked instead.

5. At some later time, when this object is no longer needed for recovery processing, it must be released via the TransactionLogger.release() method.

6. During crash recovery processing, a new instantiation of the object is created, and the TransactionLoggable.readExternal() method is responsible for restoring the object's state to correspond with its previous state at the time TransactionLoggable.writeExternal() was invoked.

7. After state is restored, the object's onRecovery() callback method is invoked.

   It is possible for TransactionLoggable.onRecovery() to be never called, or to be called more than once, depending on the number of system crashes.

8. After recovery processing is complete, the recovered object should be released again via the TransactionLogger.release() method.

A TransacctionLoggable class is also expected to efficiently implement equals(), hashCode(), and to have a constructor with no arguments.

See Also:

TransactionLogger

readExternal

void readExternal(DataInput decoder)
                  throws IOException

Restore object's state based on external representation.

If more than one version of the object's class's implementation exists, this method should be prepared to handle older versions. This permits a transaction log file stored on disk to be processed after a software upgrade.

Parameters:

decoder - decoder for log externalization data types

Throws:

IOException

writeExternal

void writeExternal(DataOutput encoder)
                   throws IOException

Save object's state in external format.

The external format should be as compact as possible, so it may be efficiently written into the transaction log.

A version number should be included, in case an older log file is read by a newer version of the object's class's implementation. This permits a transaction log file stored on disk to be processed after a software upgrade.

Parameters:

encoder - encoder for log externalization data types

Throws:

IOException

onDisk

void onDisk(TransactionLogger tlog)

Callback method for when object safely written to disk.

Parameters:

tlog - TransactionLogger object handling this object

onError

void onError(TransactionLogger tlog)

Callback method for problem writing object to disk. It probably didn't make it, but unfortunately there's some chance it might have also.

Parameters:

tlog - TransactionLogger object handling this object

onRecovery

void onRecovery(TransactionLogger tlog)

Callback method to perform recovery.

When this method is invoked, the object should perform its crash recovery logic. State will already have been restored by the readExternal method.

Parameters:

tlog - TransactionLogger object handling this object