com.ibm.websphere.objectgrid.plugins.index
Class HashIndex

java.lang.Object
  com.ibm.websphere.objectgrid.plugins.index.HashIndex

All Implemented Interfaces:

BackingMapPlugin, Destroyable, MapIndexPlugin, Initializable

public class HashIndex
extends Object
implements MapIndexPlugin, BackingMapPlugin

HashIndex is a built-in index implementation of a MapIndexPlugin and can be used for typical indexing operations. This index plug-in supports both the MapIndex and MapRangeIndex interfaces and can be used for maps that store native Java Objects, EntityManager API entities or when a DataSerializer plug-in is used.

Client applications should not extend this class.

When used with Java Objects (POJO), HashIndex uses Java reflection to dynamically introspect objects stored in a map when they are updated. It can index any individual fields or properties in the key or value portion of a map. The index implementation uses a synchronized HashMap to index the attributes for a non-range mode or a synchronized TreeMap for range mode.

When used with the KeySerializerPlugin and ValueSerializerPlugin BackingMap plug-ins, the DataSerializer.DataAttributeInflatable.inflateDataObjectAttributes(DataObjectContext, XsDataInputStream, Object) is used to inflate and introspect the cache data. HashIndex does not require that the attributes be defined in the DataDescriptor.

When used with a BackingMap associated with an EntityManager API entity, the attributes are fetched directly from the underlying Tuple. HashIndex validates configured index attributes against the associated EntityMetadata.

The following properties can be used to configure the index using the ObjectGrid deployment descriptor XML file or programmatically:

Property Name	Applicability	Description
Name	POJO, Entity, Serializer	The name of the index. The name must be unique for each map.
AttributeName	POJO, Entity, Serializer	The comma-delimited names of the attributes to index. For field-access indexes, the attribute names are equivalent to the field names. For property-access indexes, the attribute names is the JavaBean-compatible property names. For indexes associated with a MapSerializerPlugin configured BackingMap, the attribute name is a path to the attribute, which can be in the KeySerializerPlugin or ValueSerializerPlugin. See the setAttributeName(String) method for details.
FieldAccessAttribute	POJO	If true, the object is accessed using the fields directly. If not specified or false, the attribute's getter method is used to access the data.
POJOKeyIndex	POJO	If true, the index will introspect the object in the key part of the map. This is useful when the key is a composite key and the value does not have the key embedded within it. If not specified or false, then the index will introspect the object in the value part of the map.
RangeIndex	POJO, Entity, Serializer	If true, range indexing is enabled.
GlobalIndexEnabled	POJO, Entity, Serializer	If true, global index support is enabled.

The following is an ObjectGrid descriptor XML file example that defines the built-in HashIndex MapIndexPlugin for BackingMap:

  <?xml version="1.0" encoding="UTF-8"?>
  <objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
   xmlns="http://ibm.com/ws/objectgrid/config">
      <objectGrids>
          <objectGrid name="indexSampleGrid">
              <backingMap name="person" pluginCollectionRef="person" readOnly="false"
                             preloadMode="false" lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" />
          </objectGrid>
      </objectGrids>
      <backingMapPluginCollections>
          <backingMapPluginCollection id="person">
              <bean id="MapIndexPlugin" className="com.ibm.websphere.objectgrid.plugins.index.HashIndex">
                 <property name="Name" type="java.lang.String" value="person.employeeCode" description="index name" />
                 <property name="AttributeName" type="java.lang.String" value="employeeCode" description="attribute name" />
                 <property name="RangeIndex" type="boolean" value="true" description="true for MapRangeIndex" />
                 <property name="FieldAccessAttribute" type="boolean" value="false" description="property-access" />
                 <property name="POJOKeyIndex" type="boolean" value="false" description="Attribute is in the value (not the key)" />
              </bean>
          </backingMapPluginCollection>
      </backingMapPluginCollections>
   </objectGridConfig>
 

These properties can also be set programmatically, using the JavaBean pattern. For example, the setName(String) method is for setting Name property:

      BackingMap personBackingMap = ivObjectGrid.getMap("person");
      //use the built-in HashIndex class as the index plug-in class.
      HashIndex mapIndexPlugin = new HashIndex();
      mapIndexPlugin.setName("person.employeeCode");
      mapIndexPlugin.setAttributeName("employeeCode");
      mapIndexPlugin.setRangeIndex(true);
      mapIndexPlugin.setFieldAccessAttribute(true);
      mapIndexPlugin.setPOJOKeyIndex(true);
      personBackingMap.addMapIndexPlugin(mapIndexPlugin);
 

Since:

WAS XD 6.0.1

See Also:

MapIndexPlugin, MapIndex, MapRangeIndex

Field Summary

Fields inherited from interface com.ibm.websphere.objectgrid.plugins.index.MapIndexPlugin

SYSTEM_KEY_INDEX_NAME

Constructor Summary

HashIndex()
Creates a new HashIndex object.

Method Summary

void	destroy() Invoked when the bean's state has been set and is ready to be destroyed.
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 valueOrKey) Extracts the attribute from a specified object.
String	getAttributeName() Retrieves the attribute name or comma-delimited list of attribute names that was set with the setAttributeName(String) method.
String[]	getAttributeNames() Retrieves the names of each attribute included in the index that was set with the setAttributeName(String) method.
BackingMap	getBackingMap() Retrieve the BackingMap instance associated with this plug-in.
Object	getIndexProxy(MapIndexInfo map) Gets an index proxy object for performing index lookup operations.
Object	getIndexProxy(MapIndexInfo map, boolean forUpdate) Gets an index proxy object for performing index lookup operations, optionally requesting upgradeable (U) locks when accessing maps during validation.
String	getName() Gets the name of the index.
Properties	getProperties() Extract properties from a MapIndexPlugin instance.
void	initialize() Invoked when the bean's state has been set and is ready to be initialized.
boolean	isDestroyed() Answers true if the bean is in the destroyed state, false otherwise.
boolean	isFieldAccessAttribute() return the value of FieldAccessAttribute property
boolean	isGlobalIndexEnabled() return the value of globalIndexEnabled property
boolean	isInitialized() Answers true if the bean is in the initialized state, false otherwise.
boolean	isPOJOKeyIndex() return the value of POJOKeyIndex property
boolean	isRangeIndex() Indicates if this index is the type of MapRangeIndex interface.
void	setAttributeName(String attributeName) Sets the comma-delimited set of attribute names to include in the index.
void	setBackingMap(BackingMap map) The BackingMap instance is at an undefined state, depending on the type of plug-in and how it was registered with the map.
void	setEntityMetadata(EntityMetadata entityMetadata) Called by the ObjectGrid runtime to set the EntityMetadata of the BackingMap.
void	setFieldAccessAttribute(boolean isFieldAccessAttribute) Setter for the fieldAccessAttribute property.
void	setGlobalIndexEnabled(boolean globalIndexEnabled) Sets whether to enable global index and create a MapGlobalIndex.
void	setName(String name) Sets the name of this index.
void	setPOJOKeyIndex(boolean isPOJOKeyIndex) Setter for the POJOKeyIndex property.
void	setProperties(Properties properties) Set properties of a MapIndexPlugin instance.
void	setRangeIndex(boolean rangeIndex) Sets whether to create a MapRangeIndex or a MapIndex.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HashIndex

public HashIndex()

Creates a new HashIndex object.

Method Detail

setFieldAccessAttribute

public void setFieldAccessAttribute(boolean isFieldAccessAttribute)

Setter for the fieldAccessAttribute property.

This property does not apply BackingMaps that have an EntityManager API entity associated or if the BackingMap has a MapSerializerPlugin configured.

Parameters:

isFieldAccessAttribute -

isFieldAccessAttribute

public boolean isFieldAccessAttribute()

return the value of FieldAccessAttribute property

Returns:

fieldAccessAttribute property

setPOJOKeyIndex

public void setPOJOKeyIndex(boolean isPOJOKeyIndex)

Setter for the POJOKeyIndex property.

This property does not apply BackingMaps that have an EntityManager API entity associated or if the BackingMap has a MapSerializerPlugin configured.

Parameters:

isPOJOKeyIndex -

isPOJOKeyIndex

public boolean isPOJOKeyIndex()

return the value of POJOKeyIndex property

Returns:

ivPOJOKeyIndex property

setProperties

public void setProperties(Properties properties)

Description copied from interface: MapIndexPlugin

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.

Specified by:

setProperties in interface MapIndexPlugin

Parameters:

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

See Also:

MapIndexPlugin.getProperties()

getProperties

public Properties getProperties()

Description copied from interface: MapIndexPlugin

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.

Specified by:

getProperties in interface MapIndexPlugin

See Also:

MapIndexPlugin.setProperties(Properties)

setName

public void setName(String name)

Sets the name of this index.

Parameters:

name - the name of the index

setRangeIndex

public void setRangeIndex(boolean rangeIndex)

Sets whether to create a MapRangeIndex or a MapIndex.

If this method is never called, a MapIndex is used as the default implementation.

Parameters:

rangeIndex - true for a MapRangeIndex, false for MapIndex

See Also:

MapIndex, MapRangeIndex, ObjectMap.getIndex(String)

isGlobalIndexEnabled

public boolean isGlobalIndexEnabled()

return the value of globalIndexEnabled property

Returns:

globalIndexEnabled property

setGlobalIndexEnabled

public void setGlobalIndexEnabled(boolean globalIndexEnabled)

Sets whether to enable global index and create a MapGlobalIndex.

Parameters:

globalIndexEnabled - true for support of MapGlobalIndex, false for no support of MapGlobalIndex.

See Also:

MapGlobalIndex, ObjectMap.getIndex(String)

isRangeIndex

public boolean isRangeIndex()

Description copied from interface: MapIndexPlugin

Indicates if this index is the type of MapRangeIndex interface.

Specified by:

isRangeIndex in interface MapIndexPlugin

See Also:

MapRangeIndex

getAttributeNames

public String[] getAttributeNames()

Retrieves the names of each attribute included in the index that was set with the setAttributeName(String) method.

Returns:

an array of attribute names as specified as an argument to the setAttributeName(String) method. Answers null if the setAttributeName method was not previously called.

Since:

7.0

See Also:

setAttributeName(String)

setEntityMetadata

public void setEntityMetadata(EntityMetadata entityMetadata)

Description copied from interface: MapIndexPlugin

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

The EntityMetadata is required for supporting Tuple indexing.

Specified by:

setEntityMetadata in interface MapIndexPlugin

Parameters:

entityMetadata - the EntityMetadata of the BackingMap.

doBatchUpdate

public void doBatchUpdate(TxID txid,
                          LogSequence sequence)
                   throws ObjectGridRuntimeException

Description copied from interface: MapIndexPlugin

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.

Specified by:

doBatchUpdate in interface MapIndexPlugin

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:

MapIndexPlugin.doBatchUpdate(TxID,LogSequence)

undoBatchUpdate

public void undoBatchUpdate(TxID txid,
                            LogSequence sequence)
                     throws ObjectGridException

Description copied from interface: MapIndexPlugin

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.

Specified by:

undoBatchUpdate in interface MapIndexPlugin

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:

MapIndexPlugin.undoBatchUpdate(TxID, LogSequence)

getAttribute

public Object getAttribute(Object valueOrKey)
                    throws ObjectGridRuntimeException

Extracts the attribute from a specified object. If the index is for an attribute extracted by a KeySerializerPlugin or ValueSerializerPlugin, then the object passed in should be the key or value object as appropriate for the index.

Specified by:

getAttribute in interface MapIndexPlugin

Parameters:

valueOrKey - The value or key object.

Returns:

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

Throws:

ObjectGridRuntimeException - is thrown if any exception occurs attempting to extract the attribute value from the value or key Object.

getName

public String getName()

Description copied from interface: MapIndexPlugin

Gets the name of the index.

Specified by:

getName in interface MapIndexPlugin

Returns:

the name of the index.

See Also:

ObjectMap.getIndex(String)

getAttributeName

public String getAttributeName()

Retrieves the attribute name or comma-delimited list of attribute names that was set with the setAttributeName(String) method.

Specified by:

getAttributeName in interface MapIndexPlugin

Returns:

the name specified as an argument to the setAttributeName(String) method or null if the setAttributeName method was not previously called or if more than one attribute is defined.

See Also:

setAttributeName(String), getAttributeNames()

setAttributeName

public void setAttributeName(String attributeName)

Sets the comma-delimited set of attribute names to include in the index.

The attribute name format is dependent on how the associated BackingMap is configured:

• POJO - A map that stores Java Objects without an EntityManager API entity or MapSerializerPlugin configured. The HashIndex uses reflection to interact with the data in the cache objects.
• Entity - A map that has an EntityManager API entity associated.
• MapSerializerPlugin - A map that has a MapSerializerPlugin configured.

For POJO maps, attributes are accessed using reflection, using the field name or the property name as defined by the JavaBean specification. The setPOJOKeyIndex(boolean) property identifies if the attribute is in the key or value of the cache entry. The setFieldAccessAttribute(boolean) identifies how to access the cache object: by field or by getter method.

For entity maps, attributes are accessed directly from the Tuple object stored in the map. The attribute name must match the attribute name assocated in the EntityMetadata.

For MapSerializerPlugin maps, the attribute names are passed directly to the DataSerializer.DataAttributeInflatable.getAttributeContexts(String...) method and the attribute values are fetched using the DataSerializer.DataAttributeInflatable.inflateDataObjectAttributes(DataObjectContext, XsDataInputStream, Object) method. The attribute name is a path to an attribute within the key or value. A key attribute is specified by including the "key" path prefix, or the prefix specified by the MapDataDescriptor.getAddressableKeyName() method. The path delmiter is specified in the DataDescriptor.getPathSeparator() for the DataDescriptor for each KeyDataSerializer or ValueSerializer.

MapSerializerPlugin index attribute examples:
(assuming the default addressible key name of "key" and path separator of ".")

• name - Indexes the "name" attribute in the value.
• key.ssn - Indexes the "ssn" attribute in the key.
• address.country.code - Indexes the "code" attribute from the "country" embedded type from the "address" embedded type in the value.

Specified by:

setAttributeName in interface MapIndexPlugin

Parameters:

attributeName - the name of the attribute to set.

See Also:

MapIndexPlugin.setAttributeName(String)

getIndexProxy

public Object getIndexProxy(MapIndexInfo map)

Description copied from interface: MapIndexPlugin

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.

Specified by:

getIndexProxy in interface MapIndexPlugin

Parameters:

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

Returns:

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

See Also:

MapIndexPlugin.getIndexProxy(MapIndexInfo)

getIndexProxy

public Object getIndexProxy(MapIndexInfo map,
                            boolean forUpdate)

Gets an index proxy object for performing index lookup operations, optionally requesting upgradeable (U) locks when accessing maps during validation.

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.

forUpdate - if true, request upgradeable (U) locks when validating results, otherwise request shareable (S) locks.

Returns:

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

See Also:

MapIndex, MapRangeIndex, ObjectMap.getIndex(String), MapIndexPlugin.getIndexProxy(MapIndexInfo)

setBackingMap

public void setBackingMap(BackingMap map)

Description copied from interface: BackingMapPlugin

The BackingMap instance is at an undefined state, depending on the type of plug-in and how it was registered with the map. Use the BackingMap.getState() method to determine what state the map is in.

Specified by:

setBackingMap in interface BackingMapPlugin

Parameters:

map - the BackingMap associated with this plug-in instance.

getBackingMap

public BackingMap getBackingMap()

Description copied from interface: BackingMapPlugin

Retrieve the BackingMap instance associated with this plug-in.

During normal operation, this method may be called to confirm the correct operation of the BackingMapPlugin. It must return the BackingMap instance previously set using the BackingMapPlugin.setBackingMap(BackingMap) method.

Specified by:

getBackingMap in interface BackingMapPlugin

Returns:

the BackingMap instance.

initialize

public void initialize()
                throws ObjectGridRuntimeException

Description copied from interface: Initializable

Invoked when the bean's state has been set and is ready to be initialized. The result should be that the bean is in the initialized state.

Specified by:

initialize in interface Initializable

Throws:

ObjectGridRuntimeException

isInitialized

public boolean isInitialized()

Description copied from interface: Initializable

Answers true if the bean is in the initialized state, false otherwise.

During normal operation, this method may be called to confirm the correct operation of the Initializable.initialize() method.

Specified by:

isInitialized in interface Initializable

Returns:

true if the bean is in the initialized state.

destroy

public void destroy()

Description copied from interface: Destroyable

Invoked when the bean's state has been set and is ready to be destroyed. The result should be that the bean is in the destroyed state.

Specified by:

destroy in interface Destroyable

isDestroyed

public boolean isDestroyed()

Description copied from interface: Destroyable

Answers true if the bean is in the destroyed state, false otherwise.

During normal operation, this method may be called to confirm the correct operation of the Destroyable.destroy() method.

Specified by:

isDestroyed in interface Destroyable

Returns:

true if the bean is in the destroyed state.