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

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

All Implemented Interfaces:

BackingMapPlugin, Destroyable, MapIndexPlugin, Initializable

public final class InverseRangeIndex
extends Object
implements MapIndexPlugin, BackingMapPlugin

InverseRangeIndex is a built-in index implementation of MapIndexPlugin for storing range data and could be used for looking up single item with in a range.

This is a final class and can not be extended by other classes.

When used with Java Objects (POJO), InverseRangeIndex 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 an algorithm to structurally store the data and retrieve using a specific look up key.

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

Property Name	Applicability	Description
Name	POJO, Serializer	The name of the index. The name must be unique for each map.
AttributeName	POJO, 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.
AddressableKeyName	POJO	If this is set, the index will check the attribute names suffixed with value of AddressableKeyName and dot as path separator for key attribute. Default value for this is "key". All attribute names which do not have this prefix will be treated as value attributes. This property will be ignored when using a serializer.

The following is an ObjectGrid descriptor XML file example that defines the built-in InverseRangeIndex:

  <?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="inverseRangeIndexSampleGrid">
              <backingMap name="person" pluginCollectionRef="product" readOnly="false"
                             preloadMode="false" lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" />
          </objectGrid>
      </objectGrids>
      <backingMapPluginCollections>
          <backingMapPluginCollection id="product">
              <bean id="MapIndexPlugin" className="com.ibm.websphere.objectgrid.plugins.index.InverseRangeIndex">
                 <property name="Name" type="java.lang.String" value="inverse_range_index" description="index name" />
                 <property name="AttributeName" type="java.lang.String" value="productName[KeyAttribute.productName],promotionDate[KeyAttribute.startPromotionDate ,KeyAttribute.endPromotionDate], RAM[KeyAttribute.minRAM,KeyAttribute.maxRAM], condition[KeyAttribute.condition], KeyAttribute.country" description="attribute name" />
                 <property name="AddressableKeyName" type="java.lang.String" value="KeyAttribute" description="default is key" />
                 <property name="FieldAccessAttribute" type="boolean" value="false" description="default is false" />
              </bean>
          </backingMapPluginCollection>
      </backingMapPluginCollections>
   </objectGridConfig>
 

These properties can also be set programmatic way, using the JavaBean pattern. For example:

      BackingMap productBackingMap = ivObjectGrid.getMap("product");

      InverseRangeIndex inverseRangeIndex = new InverseRangeIndex();
      inverseRangeIndex.setName("inverse_range_index");
      inverseRangeIndex.setAddressableKeyName("KeyAttribute");
      inverseRangeIndex.setAttributeName("productName[KeyAttribute.productName],promotionDate[KeyAttribute.startPromotionDate ,KeyAttribute.endPromotionDate], RAM[KeyAttribute.minRAM,KeyAttribute.maxRAM], condition[KeyAttribute.condition], KeyAttribute.country" description="attribute name");
      inverseRangeIndex.setFieldAccessAttribute(false);
      productBackingMap.addMapIndexPlugin(inverseRangeIndex);
 

Since:

WAS XS 8.6

See Also:

MapIndexPlugin, MapIndex, MapRangeIndex

Field Summary

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

SYSTEM_KEY_INDEX_NAME

Constructor Summary

InverseRangeIndex()

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.
String	getAddressableKeyName() return the value for the addressableKeyName property.
Object	getAttribute(Object valueOrKey) Extracts the attribute value 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.
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.
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	isInitialized() Answers true if the bean is in the initialized state, false otherwise.
boolean	isRangeIndex() Indicates if this index is the type of MapRangeIndex interface.
void	setAddressableKeyName(String addressableKeyName) Setter for the addressableKeyName property.
void	setAttributeName(String attributeName) Sets the comma-delimited values of attribute names to include in the inverse range 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	setName(String indexName) Sets the name of this index.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

InverseRangeIndex

public InverseRangeIndex()

Method Detail

initialize

public void initialize()

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

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.

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.

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)

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.

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

getAttribute

public Object getAttribute(Object valueOrKey)

Extracts the attribute value from a specified object.

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.

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)

setAttributeName

public void setAttributeName(String attributeName)

Sets the comma-delimited values of attribute names to include in the inverse range index.

There are three different type of attributes:

• Non-Range attribute - Non-Range attribute that is used as identifier.
• Simple Range Attribute - A Range Attribute contains boundary values for a given Range.
  For example: min/max or start/finish or begin/end or high/low
• Multi-Range Attribute - An array/List of Range Attributes where each element in again an array/List with two boundary values.

The value for attributeName should contain one or more non-range attributes and one or more simple range attributes(or Multi-Range Attribute). An attribute name should not contain a mixture of simple range attributes and multi-Range attributes.

Syntax for AttributeName:

 attribute_name_string ::= ({simple_attribute}, {range_attribute}) | ({simple_attribute}, multi_range_attribute) 
 
      simple_attribute ::= (search_attribute_name, "[", index_attribute_name, "]") | (index_attribute_name);
       range_attribute ::= search_attribute_name "[" low_index_attribute_name "," high_index_attribute_name "]";
 multi_range_attribute ::= [search_attribute_list_name] "[[" index_attribute_list_name "]]";
 

Attribute names for indexing key:

index_attribute_name is non-range attribute name to be part of inverse range index key.

low_index_attribute_name is low boundary for range attribute name to be part of inverse range index key.

high_index_attribute_name is high boundary for range attribute name to be part of inverse range index key.

index_attribute_list_name is attribute name for List/array of range values. Each element in List/array should again be an array/List with two values, which are low and high boundary values for a range.

Attribute names for search key:

search_attribute_name is attribute name to be part of inverse range search key. This is required for range_attribute and optional for simple_attribute. When not specified for simple_attribute, index_attribute_name will be used.

search_attribute_list_name is attribute name of List/array type, to be part of inverse range search key. This is optional for multi_range_attribute. When not specified, index_attribute_list_name will be used.

Example with Simple Range Attribute:

productName[key.productName],promotionDate[key.startPromotionDate ,key.endPromotionDate], RAM[key.minRAM,key.maxRAM], condition[key.condition], key.country

In the above example:

• productName, condition and country are Non-Range Attributes looked up in the key and same names will be used for search key.
  
• startPromotionDate and endPromotionDate are read from the key and treated as one Simple Range Attribute. promotionDate will be read from the search key for findAll(Object searchKey) operation.
• minRAM and maxRAM are read from the key and treated as one Simple Range Attribute. RAM will be read from the search key for findAll(Object searchKey) operation.
  
  

Example with Multi-Range Attribute:

identifier[key.identifier],rangeValues[[key.rangeValues]]

In the above example:

• identifier is a Non-Range Attribute and same name will be used for the search key
• rangeValues is treated as a Multi-Range Attribute. Which can be an array/List of elements and each element should be an array/List with two boundary values. Same name will be used for search key. In search key each element in array/List will contain only one value for search instead of two boundary values.
  
  

Note that the AddressableKeyName property is only applicable for indexing key attribute names and not for search key attributes.

The setFieldAccessAttribute(boolean) identifies how to access the cache object: by field or by getter method.

Specified by:

setAttributeName in interface MapIndexPlugin

Parameters:

attributeName - the name of the attribute to set.

See Also:

MapIndexPlugin.setAttributeName(String)

setAddressableKeyName

public void setAddressableKeyName(String addressableKeyName)

Setter for the addressableKeyName property.

default value is "key".

Parameters:

addressableKeyName -

getAddressableKeyName

public String getAddressableKeyName()

return the value for the addressableKeyName property.

Returns:

addressableKeyName

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

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)

setName

public void setName(String indexName)

Sets the name of this index.

Parameters:

indexName - the name of the index

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)

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)