com.ibm.websphere.objectgrid.plugins.index
Interface MapIndexPlugin

All Known Implementing Classes:

HashIndex, InverseRangeIndex

public interface MapIndexPlugin

An index implementation must implement this interface to get modifications to the Map so it can maintain the index as transactions are committed. Only attributes that implement the Comparable interface are eligible to be indexed.

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

A MapIndexPlugin 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.1

See Also:

BackingMap.addMapEventListener(EventListener), BackingMap.addMapIndexPlugin(MapIndexPlugin), BackingMap.createDynamicIndex(MapIndexPlugin, DynamicIndexCallback), MapIndex, MapRangeIndex

Field Summary

static String

SYSTEM_KEY_INDEX_NAME A built-in index of the the local ObjectGrid instance that allows iterating over all of the keys in a map.

Method Summary

void	doBatchUpdate(TxID txid, LogSequence sequence) Called by ObjectGrid runtime to allow the index to be updated as the result of changes applied to a map during the commit cycle of a transaction.
Object	getAttribute(Object value) Extracts the attribute from a specified value Object.
String	getAttributeName() Gets the name of the indexed attribute.
Object	getIndexProxy(MapIndexInfo map) Gets an index proxy object for performing index lookup operations.
String	getName() Gets the name of the index.
Properties	getProperties() Extract properties from a MapIndexPlugin instance.
boolean	isRangeIndex() Indicates if this index is the type of MapRangeIndex interface.
void	setAttributeName(String attributeName) Sets the name of the attribute to be indexed.
void	setEntityMetadata(EntityMetadata entityMetadata) Called by the ObjectGrid runtime to set the EntityMetadata of the BackingMap.
void	setProperties(Properties properties) Set properties of a MapIndexPlugin instance.
void	undoBatchUpdate(TxID txid, LogSequence sequence) Called by the ObjectGrid runtime to undo any changes made to the index as a result of a prior call to the doBatchUpdate(TxID, LogSequence) method.

Field Detail

SYSTEM_KEY_INDEX_NAME

static final String SYSTEM_KEY_INDEX_NAME

A built-in index of the the local ObjectGrid instance that allows iterating over all of the keys in a map. This index does not require a transaction and does not hold any locks. The keys that are returned are a snapshot and are not guaranteed to be consistent.

This index does not support client/server indexes. Invoking this index on a client will allow iterating over the keys in the client cache (if enabled) and will not iterate over all keys in the grid.

Since:

7.1.0.3

See Also:

Constant Field Values

Method Detail

setProperties

void setProperties(Properties properties)

Set properties of a MapIndexPlugin instance. The MapIndexPlugin instance can initialize itself with the passed properties. In distributed ObjectGrid scenario, both setProperties and getProperties methods are required to support dynamic indexing.

Parameters:

properties - The Properties object that can be used to initialize a MapIndexPlugin instance.

Since:

WAS XD 6.1

See Also:

getProperties()

getProperties

Properties getProperties()

Extract properties from a MapIndexPlugin instance. The extracted properties can be used to initialize another MapIndexPlugin instance to have the same internal states. In distributed ObjectGrid scenario, both setProperties and getProperties methods are required to support dynamic indexing.

Since:

WAS XD 6.1

See Also:

setProperties(Properties)

setEntityMetadata

void setEntityMetadata(EntityMetadata entityMetadata)

Called by the ObjectGrid runtime to set the EntityMetadata of the BackingMap.

The EntityMetadata is required for supporting Tuple indexing.

Parameters:

entityMetadata - the EntityMetadata of the BackingMap.

Since:

WAS XD 6.1

isRangeIndex

boolean isRangeIndex()

Indicates if this index is the type of MapRangeIndex interface.

Since:

WAS XD 6.1

See Also:

MapRangeIndex

getAttribute

Object getAttribute(Object value)

Extracts the attribute from a specified value Object. For example, if an Employee object has an attribute called employeeName that is indexed, the getAttribute method can be used to extract the employeeName attribute value from the specified Employee object. This method is required in distributed ObjectGrid environment.

Parameters:

value - The value Object.

Returns:

attribute from the value Object, which may be a null reference.

Since:

WAS XD 6.1

getAttributeName

String getAttributeName()

Gets the name of the indexed attribute.

Since:

WAS XD 6.1

setAttributeName

void setAttributeName(String attributeName)

Sets the name of the attribute to be indexed.

If the object has an attribute called employeeName or EmployeeName, the index will call the "getEmployeeName" method. The attribute name must be the same as that in the get method and the attribute must implement the Comparable interface. If the attribute type is boolean, the "isAttributeName" method pattern is supported too.

Parameters:

attributeName - the name of the attribute to set.

getName

String getName()

Gets the name of the index.

Returns:

the name of the index.

See Also:

ObjectMap.getIndex(String)

getIndexProxy

Object getIndexProxy(MapIndexInfo map)

Gets an index proxy object for performing index lookup operations.

The caller must cast the object returned to either a MapIndex or MapRangeIndex to perform the lookup operations.

Parameters:

map - the MapIndexInfo object required for maintaining the index. .

Returns:

a proxy to either an object that implements MapIndex or MapRangeIndex.

See Also:

MapIndex, MapRangeIndex, ObjectMap.getIndex(String)

doBatchUpdate

void doBatchUpdate(TxID txid,
                   LogSequence sequence)
                   throws ObjectGridRuntimeException

Called by ObjectGrid runtime to allow the index to be updated as the result of changes applied to a map during the commit cycle of a transaction.

Use the LogElement.getType() method to determine what operation is required for updating the index. Use the LogElement.getBeforeImage() method to get the value object that existed prior to the committing transaction applying a change to the map. Use the LogElement.getAfterImage() method to get the value object after the committing transaction applied the change to the map entry.

For a MapIndexPlugin in an ObjectMap that is configured to use OutputFormat.RAW for the keys or values, 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.

Note, the undoBatchUpdate(TxID, LogSequence) method may be called later to undo these changes if an exception occurs that causes the committing transaction to be rolled back instead.

Parameters:

txid - the transaction context (TxID) for the changes.

sequence - the log sequence that contains the changes from transaction.

Throws:

ObjectGridRuntimeException - is a failure occurs that requires transaction to be rolled back.

See Also:

undoBatchUpdate(TxID, LogSequence), LogElement.getType(), LogElement.getBeforeImage(), LogElement.getAfterImage(), LogSequence, TxID

undoBatchUpdate

void undoBatchUpdate(TxID txid,
                     LogSequence sequence)
                     throws ObjectGridException

Called by the ObjectGrid runtime to undo any changes made to the index as a result of a prior call to the doBatchUpdate(TxID, LogSequence) method.

This method is called when an exception or error condition that requires all changes made by a transaction to be rolled back. For this reason, the implementation of this method should catch all Throwables and continue with the next LogElement in the LogSequence until all LogElements are processed so that as many changes to the index are undone as possible. An ObjectGridException should only be thrown after processing the entire LogSequence and this method was unable to successfully undo one or more changes in the LogSequence.

Use the LogElement.getUndoType() method to determine what operation is required to undo any change made to the index. Use the LogElement.getBeforeImage() to get the value object that existed prior to the committing transaction applying a change to the map. Use the LogElement.getAfterImage() to get the value object after the committing transaction applied the change to the map entry.

For a MapIndexPlugin in an ObjectMap that is configured to use OutputFormat.RAW for the keys or values, 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 context (TxID) for the changes.

sequence - the log sequence that contains changes from transaction.

Throws:

ObjectGridException - is an error occurred during processing

See Also:

LogElement.getUndoType(), LogElement.getBeforeImage(), LogElement.getAfterImage(), LogSequence, TxID