See the WebSphere eXtreme Scale Wiki for links to eXtreme Scale Version 7.0 documentation.
If you log in
with your developerWorks ID, you can leave comments and feedback for the development team.
When an application is making changes to a Map during a transaction, a LogSequence object tracks those changes. If the application changes an entry in the map, a corresponding LogElement object exists to provide the details of the change. Loaders are given a LogSequence object for a particular map whenever an application calls for a flush or commit to the transaction. The Loader iterates over the LogElement objects within the LogSequence object and applies each LogElement object to the backend.
ObjectGridEventListener listeners that are registered with an ObjectGrid also use LogSequence objects. These listeners are given a LogSequence object for each map in a committed transaction. Applications can use these listeners to wait for certain entries to change, like a trigger in a conventional database.
The following log-related interfaces or classes are provided by the ObjectGrid framework:
- com.ibm.websphere.objectgrid.plugins.LogElement
- com.ibm.websphere.objectgrid.plugins.LogSequence
- com.ibm.websphere.objectgrid.plugins.LogSequenceFilter
- com.ibm.websphere.objectgrid.plugins.LogSequenceTransformer
LogElement interface
A LogElement represents an operation on an entry during a transaction. A LogElement object has the following attributes. The most commonly used attributes the type and the current value attributes:
type attribute
A log element type indicates the kind of operation that this log element represents. The type can be one of the following constants that are defined in the LogElement interface: INSERT, UPDATE, DELETE, EVICT, FETCH, or TOUCH.
undo type attribute
Returns what operation must be performed to undo a prior change that the transaction made to the map entry.
current value attribute
The current value represents the new value for the operation INSERT, UPDATE or FETCH. If the operation is TOUCH, DELETE, or EVICT, the current value is null. This value can be cast to ValueProxyInfo when a ValueInterface is in use.
CacheEntry attribute
You can get a reference to the CacheEntry object from the LogElement and use the methods defined on the CacheEntry object to retrieve needed information.
pending state attribute
If the pending state is true, then the change that is represented by this log element has not yet been applied to the loader. If the state is false, then the change has been applied to the loader, most likely by the flush operation.
versioned value attribute
A versioned value is a value that can be used for versioning.
new keywords attribute
The new keyword collection contains any new keywords that have been associated with this entry.
last access time attribute
Represents the last access time for the entry.
before image / after image attributes
Getter methods are available to get the image of the value object before or after the changes were applied to the map.
LogSequence interface
In most transactions, operations to more than one entry in a map occur, so multiple LogElement objects are created. It makes sense to have an object that acts as a composite of multiple LogElement objects. The LogSequence interface serves this purpose by containing a list of LogElement objects. The LogSequence interface has the following methods:
size method
Returns the number of LogElement objects in the specified sequence.
getAllChanges method
Returns an iterator of all the changes in the specified log sequence.
getPendingChanges method
Returns an iterator of all the pending changes. This method is most likely to be used by a loader to apply pending changes to the persistent store only.
getChangesByKeys method
Returns an iterator of the LogElement objects that have the target key, based on the input parameter.
getChangesByTypes method
Returns an iterator of the LogElement objects that are of the specified LogElement type.
getMapName method
Returns the name of the backing map to which the changes apply. The caller can use this name as input to the Session.getMap(string) method.
isDirty method
Returns whether this LogSequence has any LogElements that would dirty a Map. That is, if the LogSequence contains any LogElement objects that are of any type other than Fetch or Get, then the LogSequence is considered dirty.
isRollback method
Returns if this LogSequence was generated to roll back a transaction.
getObjectGridName method
Returns the name of the ObjectGrid that houses the map for which these changes apply.
LogElement and LogSequence
LogElement and LogSequence are widely used in ObjectGrid and by ObjectGrid plug-ins that are written by users when operations are propagated from one component or server to another component or server. For example, a LogSequence object can be used by the distributed ObjectGrid transaction propagation function to propagate the changes to other servers, or it can be applied to the persistence store by the loader. LogSequence is mainly used by the following interfaces.
- com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener
- com.ibm.websphere.objectgrid.plugins.Loader
- com.ibm.websphere.objectgrid.plugins.Evictor
- com.ibm.websphere.objectgrid.Session
For more details about these interfaces, see the API documentation.
Loader example
This section demonstrates how the LogSequence and LogElement objects are used in a Loader. A Loader is used to load data from and persist data into a persistent store. The batchUpdate method of the Loader interface uses LogSequence object:
void batchUpdate(TxID txid, LogSequence sequence) throws LoaderException, OptimisticCollisionException;
The batchUpdate method is called when an ObjectGrid needs to apply all current changes to the Loader. The Loader is given a list of LogElement objects for the map, encapsulated in a LogSequence object. The implementation of the batchUpdate method must iterate over the changes and apply them to the backend. The following code snippet demonstrates how a Loader uses a LogSequence object. The snippet iterates over the set of changes and builds up three batch Java database connectivity (JDBC) statements: one that has inserts, one that has updates and, a third statement that has deletes:
public void batchUpdate(TxID tx, LogSequence sequence) throws LoaderException
{
Connection conn = getConnection(tx);
try
{
Iterator iter = sequence.getPendingChanges();
while ( iter.hasNext() )
{
LogElement logElement = (LogElement)iter.next();
Object key = logElement.getCacheEntry().getKey();
Object value = logElement.getCurrentValue();
switch ( logElement.getType().getCode() )
{
case LogElement.CODE_INSERT:
buildBatchSQLInsert( key, value, conn );
break;
case LogElement.CODE_UPDATE:
buildBatchSQLUpdate( key, value, conn );
break;
case LogElement.CODE_DELETE:
buildBatchSQLDelete( key, conn );
break;
}
}
Collection statements = getPreparedStatementCollection( tx, conn );
iter = statements.iterator();
while ( iter.hasNext() )
{
PreparedStatement pstmt = (PreparedStatement) iter.next();
pstmt.executeBatch();
}
} catch (SQLException e)
{
LoaderException ex = new LoaderException(e);
throw ex;
}
}
The previous sample illustrates the high level logic of processing the LogSequence argument and the details of how an SQL insert, update, or delete statement is built are not illustrated. This example illustrates that the getPendingChanges method is called on LogSequence argument to obtain an iterator of LogElement objects that a Loader needs to process, and the LogElement.getType().getCode() method is used to determine whether a LogElement is for a SQL insert, update, or delete operation.
Evictor sample
This example explores how LogSequence and LogElement objects are used in an Evictor. An Evictor is used to evict the map entries from the backing map based on certain criteria. The apply method of the Evictor interface uses LogSequence:
/**
* This is called during cache commit to allow the evictor to track object usage
* in a backing map. This will also report any entries that have been successfully
* evicted.
*
* @param sequence LogSequence of changes to the map
*/
void apply(LogSequence sequence);
For information on how the apply method uses LogSequence, refer to the code sample in the Evictors topic.
LogSequenceFilter and LogSequenceTransformer interfaces
Sometimes, it is necessary to filter the LogElement objects so that only LogElement objects with certain criteria are accepted, and reject other objects. For example, you might want to serialize a certain LogElement based on some criterion.
LogSequenceFilter solves this problem with the following method:
public boolean accept (LogElement logElement);
This method returns true if the given LogElement should be used in the operation, and returns false if the given LogElement should not be used.
LogSequenceTransformer is a class that uses the LogSequenceFilter function. It uses the LogSequenceFilter to filter out some LogElement objects and then serialize the accepted LogElement objects. This class has two methods. The first method follows:
public static void serialize(Collection logSequences, ObjectOutputStream stream, LogSequenceFilter filter, DistributionMode mode) throws IOException
This method allows the caller to provide a filter for determining which LogElements to include in the serialization process. The DistributionMode parameter allows the caller to control the serialization process. For example, if the distribution mode is invalidation only, then there is no need to serialize the value. The second method of this class follows:
public static Collection inflate(ObjectInputStream stream, ObjectGrid objectGrid) throws IOException, ClassNotFoundException
This method reads the log sequence serialized form, which was created by the serialize method, from the provided object input stream.
© Copyright IBM Corporation 2007,2009. All Rights Reserved.
