Side of Software
Persistence Library 2.0

sos.db
Class AbstractTransactionPolicy

java.lang.Object
  extended by sos.db.AbstractTransactionPolicy
All Implemented Interfaces:
java.io.Serializable, TransactionPolicy
Direct Known Subclasses:
DefaultReadWriteTransactionPolicy, DefaultTransactionPolicy

public abstract class AbstractTransactionPolicy
extends java.lang.Object
implements TransactionPolicy, java.io.Serializable

A partial implementation of TransactionPolicy. This abstract class handles the method invocation on the database object and the notification that the database object has changed as a result of the invocation. Before the method invocation, it logs a message by calling logMethodInvoked.

To determine if a database object changes as a result of the method invocation, this class uses the read-only status of the method. If the method is ReadOnlyManager.READ_ONLY, the object is guaranteed not to change. If the method is ReadOnlyManager.WRITE or ReadOnlyManager.UNKNOWN, the object is assumed to change. If the method is ReadOnlyManager.DEFERRED_WRITE, the object is assumed to change if a WRITE or UNKNOWN method is invoked on the returned object. It gets the method's status by invoking getMethodStatus, which in turn invokes ReadOnlyManager.getMethodStatus. Subclasses may override getMethodStatus to provide an alternate means of determining a method's read-only status.

Note: It is always safe to classify a method as a write method. Incorrectly classifying a write method as read-only may prevent the database from resaving a modified object and lead to unexpected values.

Besides registerObject and startTransaction, subclasses can implement the following methods:

   public void prepareForReadOnlyInvocation( TransactionSupport support ) throws IOException
   public void prepareForWriteInvocation( TransactionSupport support ) throws IOException
These methods give implementations a chance to detect transaction conflicts and deadlocks. The first method is called before read-only methods are invoked on database objects. The second method is called before all other methods are invoked. Inside these methods, subclasses may wish to block the current transaction, interrupt other transactions, or build a waits-for graph. They can use TransactionSupport.getKey() to uniquely identify the receiver object.

Since:
1.0
See Also:
ReadOnlyManager, DefaultTransactionPolicy, DefaultReadWriteTransactionPolicy

Constructor Summary
AbstractTransactionPolicy()
           
 
Method Summary
protected  int getMethodStatus(java.lang.reflect.Method method)
          Returns the specified method's read-only status.
 java.lang.Object invoke(TransactionSupport support, java.lang.reflect.Method method, java.lang.Object[] args)
          Invokes the specified method on the object referred to by support.
protected  void logMethodInvocation(java.lang.String databaseName, java.lang.Object key, java.lang.Class receiverClass, java.lang.reflect.Method method)
          Records that the specified method is about to be executed on the object of type receiverClass that is associated with key.
protected  void prepareForReadOnlyInvocation(TransactionSupport support)
          Prepares for the invocation of a read-only method on the object referenced by support.
protected  void prepareForWriteInvocation(TransactionSupport support)
          Prepares for the invocation of a non-read-only method on the object referenced by support.
 void registerObject(TransactionSupport support, java.lang.Object object)
          Notifies this policy that there is a new database object.
 void startTransaction(TransactionSupport support)
          Notifies this policy that a top-level transaction is starting for the executing thread.
 void unregisterObjects(Database database, java.util.Set<java.lang.Object> oldKeys)
          Notifies this policy that objects have been removed from the database.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractTransactionPolicy

public AbstractTransactionPolicy()
Method Detail

getMethodStatus

protected int getMethodStatus(java.lang.reflect.Method method)
Returns the specified method's read-only status.

This implementation invokes ReadOnlyManager.getMethodStatus to determine the status.

Parameters:
method - method whose read-only status is desired
Returns:
the read-only status of method

invoke

public java.lang.Object invoke(TransactionSupport support,
                               java.lang.reflect.Method method,
                               java.lang.Object[] args)
                        throws java.lang.IllegalAccessException,
                               java.lang.reflect.InvocationTargetException,
                               java.io.IOException
Description copied from interface: TransactionPolicy
Invokes the specified method on the object referred to by support. The database calls this method to invoke a method on a database object.

If the object can potentially be modified by the execution of method, the implementation should fetch the receiver using getObjectForWrite; otherwise, it should use getObjectForRead.

If the object needs to be locked during the execution of method, the implementation can use the object returned by getKey to identify the lock.

If this method throws a DatabaseException, the current transaction will be aborted and rolled back.

Specified by:
invoke in interface TransactionPolicy
Parameters:
support - object to assist in transaction management
method - method to invoke on the object referred to by support
args - arguments to the method
Returns:
the result of the invocation of method
Throws:
java.lang.IllegalAccessException - if method is not accessible
java.lang.reflect.InvocationTargetException - if the invocation of method throws an exception. The exception returned by getCause is the method's exception.
java.io.IOException - if an I/O error occurs
See Also:
TransactionSupport.getKey(), TransactionSupport.getObjectForRead(), TransactionSupport.getObjectForWrite()

logMethodInvocation

protected void logMethodInvocation(java.lang.String databaseName,
                                   java.lang.Object key,
                                   java.lang.Class receiverClass,
                                   java.lang.reflect.Method method)
Records that the specified method is about to be executed on the object of type receiverClass that is associated with key.

It is safe to invoke toString on key.

This implementation uses the localized message for key "logMethodInvoked". The message takes five parameters: the database name, the transaction thread, the key, the receiver class, and the method.

Parameters:
databaseName - name of the database
key - unique key of the receiver object
receiverClass - the class of the receiver object
method - the method that is about to be invoked

prepareForReadOnlyInvocation

protected void prepareForReadOnlyInvocation(TransactionSupport support)
                                     throws java.io.IOException
Prepares for the invocation of a read-only method on the object referenced by support.

This implementation does nothing. Subclasses can override this method to provide a more meaningful implementation. For example, they can use this method to acquire a read lock.

Parameters:
support - object that holds information about the receiver object, including a key that uniquely identifies it
Throws:
java.io.IOException - if an I/O error occurs
See Also:
prepareForWriteInvocation(sos.db.TransactionSupport)

prepareForWriteInvocation

protected void prepareForWriteInvocation(TransactionSupport support)
                                  throws java.io.IOException
Prepares for the invocation of a non-read-only method on the object referenced by support.

This implementation does nothing. Subclasses can override this method to provide a more meaningful implementation. For example, they can use this method to acquire a write lock.

Parameters:
support - object that holds information about the receiver object, including a key that uniquely identifies it
Throws:
java.io.IOException - if an I/O error occurs
See Also:
prepareForReadOnlyInvocation(sos.db.TransactionSupport)

registerObject

public void registerObject(TransactionSupport support,
                           java.lang.Object object)
                    throws java.io.IOException
Description copied from interface: TransactionPolicy
Notifies this policy that there is a new database object. The database calls this method when an object is added to the database.

Specified by:
registerObject in interface TransactionPolicy
Parameters:
support - object to assist in transaction management
object - the object added to the database
Throws:
java.io.IOException - if an I/O error occurs

startTransaction

public void startTransaction(TransactionSupport support)
                      throws java.io.IOException
Description copied from interface: TransactionPolicy
Notifies this policy that a top-level transaction is starting for the executing thread. The database calls this method when a top-level transaction is starting.

Specified by:
startTransaction in interface TransactionPolicy
Parameters:
support - object to assist in transaction management
Throws:
java.io.IOException - if an I/O error occurs

unregisterObjects

public void unregisterObjects(Database database,
                              java.util.Set<java.lang.Object> oldKeys)
Description copied from interface: TransactionPolicy
Notifies this policy that objects have been removed from the database. The database calls this method when objects are being removed from the database.

Specified by:
unregisterObjects in interface TransactionPolicy
Parameters:
database - database for which the objects have been removed
oldKeys - set of objects that identify the objects being removed from the database

Side of Software
Persistence Library 2.0

Copyright 2004-08 Side of Software (SOS). All rights reserved.