com.ibm.websphere.objectgrid.plugins
Interface Loader

All Known Subinterfaces:

RetryableLoader

All Known Implementing Classes:

JPAEntityLoader, JPALoader

public interface Loader

Data in a map sometimes are backed up by a "database". This "database" can be any kind of storage. It could be database, a text file, or even an in-memory object. This plugin allows users to plug in their own "database" access protocol to load and store data.

This Loader instance will be used by a BackingMap implementation at runtime.

A Loader implementation that also implements the BackingMapLifecycleListener interface will be automatically added as an EventListener on the BackingMap when the loader set on the backing map.

A Loader may also implement the BackingMapPlugin interface in order to receive enhanced BackingMap plug-in lifecycle method calls. The plug-in is then also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Since:

WAS XD 6.0

See Also:

BackingMap.addMapEventListener(EventListener), BackingMap.setLoader(Loader), TransactionCallback

Nested Class Summary

static class

Loader.SpecialValue Special value class used for representing the key not being found in the Loader.

Field Summary

static Loader.SpecialValue

KEY_NOT_FOUND A special value type indicating that the key cannot be found

Method Summary

void	batchUpdate(TxID txid, LogSequence sequence) Called to tell the Loader to write the provided changes to the backend.
List	get(TxID txid, List keyList, boolean forUpdate) Returns the list of values corresponding to the set of keys passed in.
void	preloadMap(Session session, BackingMap backingMap) Signals the Loader to preload the data into the map.

Field Detail

KEY_NOT_FOUND

static final Loader.SpecialValue KEY_NOT_FOUND

A special value type indicating that the key cannot be found

Method Detail

preloadMap

void preloadMap(Session session,
                BackingMap backingMap)
                throws LoaderException

Signals the Loader to preload the data into the map.

The Session parameter should be used for session demarcation. The session parameter has no security enabled and allows the various maps to be accessed without credentials. The Loader is considered system code. The loader should use the Session.beginNoWriteThrough() method for all session transactions. It should also use several smaller session transactions when the amount of data is very large to avoid running out of log space.

This method also provides Loader initialization semantics since it is called when an ObjectGrid is initialized. The Session and BackingMap parameters should provide all of the necessary access to the various ObjectGrid objects, such as the PartitionManager.

The preload can be asynchronous when the async preload attribute is set to true on the BackingMap.

Objects implementing this interface should also consider implementing the ReplicaPreloadController interface as this interface allows a recoverable preload when the map is being replicated. This interface allows a replica to resume preload if the primary fails before preload completes.

Parameters:

session - a Session reference to use for demarcating transactions.

backingMap - the BackingMap this object is associated with

Throws:

LoaderException - if an error occurs during processing of this method

See Also:

BackingMap, BackingMap.setPreloadMode(boolean), PartitionManager, ReplicaPreloadController, Session, Session.beginNoWriteThrough()

get

List get(TxID txid,
         List keyList,
         boolean forUpdate)
         throws LoaderException

Returns the list of values corresponding to the set of keys passed in.

Each key provided will have a corresponding entry in the returned list. If no entry exists for a specified key, the special value Loader.KEY_NOT_FOUND should be returned as the value for that key. This value exist to distinguish between a null value and a value not being found in the Loader. For a loader in an ObjectMap that is configured to use a OutputFormat.RAW, the key objects passed will be a SerializedKey objects. If required, you can use the DataObjectEntry.getObject() method to retrieve (possibly inflating the serialized key) the original key object.

Parameters:

txid - the transaction ID object

keyList - List of keys or SerializedKey objects as described

forUpdate - true when a getForUpdate method is called. This parameter can be used to do a "SELECT for UPDATE" invocation for proper database locking.

Returns:

List of Object values

Throws:

LoaderException - if an error occurs during processing of this method

See Also:

KEY_NOT_FOUND, TxID

batchUpdate

void batchUpdate(TxID txid,
                 LogSequence sequence)
                 throws LoaderException,
                        OptimisticCollisionException

Called to tell the Loader to write the provided changes to the backend. The LogSequence parameter is the set of changes that have been applied to the BackingMap associated with this loader. If the BackingMap uses a value interface, the loader can use partial update support for improved performance. If the loader knows the values that were modified, it should update the object returned from LogElement.getCurrentValue() with the value actually in the database. This rule applies when using automatic sequence columns in a database or when using database triggers to modify the value indirectly. Under no circumstances should the committed value be modified. For a loader in an ObjectMap that is configured to use OutputFormat.RAW for the keys or value, the keys and values objects in the LogSequence will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object. To override the map's output format configuration, use the PluginOutputFormat annotation in the implementation class.

Parameters:

txid - the transaction id object

sequence - the set of changes being applied to this object's map

Throws:

LoaderException - if an error occurs during processing of this method

OptimisticCollisionException - if a version mismatch is detected

See Also:

BackingMap.setCopyMode(CopyMode, Class), LogElement.getCurrentValue(), LogSequence, TxID, ValueProxyInfo