Configuring the InverseRangeIndex plug-in

[Version 8.6 and later] You can configure the built-in InverseRangeIndex, the com.ibm.websphere.objectgrid.plugins.index.InverseRangeIndex class, with an XML file or programmatically.

Before you begin

In a partitioned environment, one of the key requirements for InverseRangeIndex is a data partition that is based on the non-range attributes configured for a given index. All cache entries and search keys with the same value of non-range attributes must be routed to the same partition. For more information about partitioning, see Routing cache objects to the same partition.
InverseRangeIndex is a MapIndexPlugin implementation. MapIndexPlugin can only be accessed from the server-side of the object grid and not the client-side. To perform search operations on the client-side, you can implement the MapGridAgent interface. For more information, see DataGrid API example.

About this task

The InverseRangeIndex plug-in is designed to support lookups with a specific search key in range style data. Range style data contain attributes with boundary values. Consider the following sample table, which includes both non-range and range style data. The table Product Data contains non-range attributes, including ProductName, Condition, and Country. These attributes are part of the index key. The table also includes range style attributes, including StartPromotionDate, EndPromotionDate, MinimumRAM, and MaximumRAM, which are also part of the index key. The attribute Price is the value for the cached object that is not part of the indexing key or search key in the data grid. To define an inverse range index, you must use the AttributeName property that is a comma-delimited list of attributes, of which must contain one or more non-range attributes and one or more range style attributes. Indexing attributes might be part of the cache key or cache value and specified with the AddressableKeyName property. For more information about AttributeName, see InverseRangeIndex plug-in attributes.

Table 1. Example: Product data
ProductName	StartPromotionDate	EndPromotionDate	MinimumRAM	MaximumRAM	Condition	Country	Price
PC01	01/01/11	12/31/11	2	4	Good	US	199
PC01	01/01/11	12/31/11	6	8	Good	US	259
PC01	01/01/12	12/31/12	2	4	Good	US	299
PC01	01/01/12	12/31/12	2	8	Good	US	499
PC02	01/01/08	12/31/10	2	4	Good	US	99
PC02	01/01/10	12/31/11	2	4	Good	US	289
PC02	01/01/12	12/31/12	4	6	Good	US	389

The index key class ProductKey has three non-range attributes: productName, condition, and country. It also has four range-style attributes with boundary values: [startPromotionDate, endPromotionDate], [minimumRAM, maximumRAM]. The following classes are used while objects are placed in the map:

public class ProductKey {
String productName; 
Date startPromotionDate;
Date endPromotionDate;
Integer minimumRAM;
Integer maximumRAM;
String condition;
String country;
}

The search key class ProductSearchKey has five attributes that search for range style data: productName, promotionDate, RAM, condition, and country. The following objects are used in the MapIndexPlugin operation:

public class ProductSearchKey {
String productName;
Date promotionDate;
Integer RAM;
String condition;
String country; 
}

Based on these classes, the InverseRangeIndex can be configured with AttributeName property as:

key.productName, promotionDate[key.startPromotionDate, key.endPromotionDate], 
RAM[key.minimumRAM,key.maximumRAM], condition[key.condition], key.country

For more information about the syntax of AttributeName, see InverseRangeIndex plug-in attributes.

Procedure

Configure an InverseRangeIndex in the ObjectGrid descriptor XML file.

Use the backingMapPluginCollections element to define the plug-in:

<bean id="MapIndexPlugin"  
   className="com.ibm.websphere.objectgrid.plugins.index.InverseRangeIndex">
	<property name="Name" type="java.lang.String" value="productData"/>
	<property name="AttributeName" type="java.lang.String" value="key.productName, 
	promotionDate[key.startPromotionDate, key.endPromotionDate], 
  RAM[key.minimumRAM,key.maximumRAM], 
	condition[key.condition], key.country"/>
</bean>

For more information about the backingMapPluginCollections element, see ObjectGrid descriptor XML file.

Configure an InverseRangeIndex programmatically.
The following example code creates the same inverse range index:
```
InverseRangeIndex mapIndex = new InverseRangeIndex();
mapIndex.setName("productInfo");
mapIndex.setAttributeName(("key.productName, promotionDate[key.startPromotionDate, 
key.endPromotionDate], RAM[key.minimumRAM,key.maximumRAM], 
condition[key.condition], key.country")); 
BackingMap bm = objectGrid.defineMap("mymap");
bm.addMapIndexPlugin(mapIndex);
```
You can add the InverseRangeIndex plug-in into a backing map. In the following example, you can configure the InverseRangeIndex plug-in by adding static index plug-ins to an XML file:
```
<backingMapPluginCollection id="product">
   <bean id="MapIndexPlugin" 
      className="com.ibm.websphere.objectgrid.plugins.index.InverseRangeIndex">
         <property name="Name" type="java.lang.String" value="productData" 
            description="index name" />
         <property name="AddressableKeyName" type="java.lang.String" value="key" 
            description="key is default" />
         <property name="AttributeName" type="java.lang.String" 
value="key.productName, promotionDate[key.startPromotionDate, key.endPromotionDate], 
RAM[key.minimumRAM,key.maximumRAM], condition[key.condition], key.country" 
            description="attribute names for indexing" />
   </bean>
</backingMapPluginCollection>
```
The built-in InverseRangeIndex class is used as the index plug-in. InverseRangeIndex supports properties that users can configure, such as Name, AddressableKeyName, AttributeName, and FieldAccessAttribute.
The Name property is configured as productData, a string that identifies this index plug-in. The Name property value must be unique within the scope of the backing map. The name can be used to retrieve the index object by name from the ObjectMap instance for the BackingMap.
The AttributeName property is configured as “key.productName, promotionDate[key.startPromotionDate, key.endPromotionDate], RAM[key.minimumRAM,key.maximumRAM], condition[key.condition], key.country”,, which means the productName, condition, country are non-range attributes and startPromotionDate, endPromotionDate, minimumRAM, maximumRAM are range attributes of the cached key object to build the index. If an application must search for a cached object with a different attribute name, then an alias can be set for each attribute. For more information, see the exampleInverse range cache.