Configuring the HashIndex plug-in

You can configure the built-in HashIndex, the com.ibm.websphere.objectgrid.plugins.index.HashIndex class, with an XML file, programmatically or with an entity annotation on an entity map.

About this task

Configuring a composite index is the same as configuring a regular index with XML, except for the attributeName property value. In a composite index, the value of attributeName property is a comma-delimited list of attributes. For example, the value class Address has three attributes: city, state, and zipcode. A composite index can be defined with the attributeName property value as "city,state,zipcode" indicating that city, state, and zipcode are included in the composite index.

The composite HashIndexes do not support range lookups and therefore cannot have the RangeIndex property set to true.

Procedure

Configure a composite index 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.HashIndex">
	<property name="Name" type="java.lang.String" value="Address.CityStateZip"/>
	<property name="AttributeName" type="java.lang.String" value="city,state,zipcode"/>
</bean>

Configure a composite index programmatically.

The following example code creates the same composite index:

	  HashIndex mapIndex = new HashIndex();
    mapIndex.setName("Address.CityStateZip");
    mapIndex.setAttributeName(("city,state,zipcode"));
    mapIndex.setRangeIndex(false);

    BackingMap bm = objectGrid.defineMap("mymap");
    bm.addMapIndexPlugin(mapIndex);

Configure a composite index with entity notations.
If you are using entity maps, you can use an annotation approach to define a composite index. You can define a list of CompositeIndex within the CompositeIndexes annotation on the entity class level. The CompositeIndex has a name and attributeNames property. Each CompositeIndex is associated with a HashIndex instance applied to the backing map that is associated with the entity. The HashIndex is configured as a non-range index.
```
@Entity
@CompositeIndexes({
    @CompositeIndex(name="CityStateZip", attributeNames="city,state,zipcode"), 
    @CompositeIndex(name="lastnameBirthday", attributeNames="lastname,birthday")
 })
public class Address {
    @Id int id;
    String street;
    String city;
    String state;
    String zipcode;
    String lastname;
    Date birthday;
}
```
The name property for each composite index must be unique within the entity and backing map. If the name is not specified, a generated name is used. The attributeName property is used to populate the HashIndex attributeName with the comma-delimited list of attributes. The attribute names coincide with the persistent field names when the entities are configured to use field-access, or the property name as defined for the JavaBeans naming conventions for property-access entities. For example: If the attribute name is street, the property getter method is named getStreet.

Example: Adding a HashIndex class into a BackingMap instance

In the following example, you configure the HashIndex plug-in by adding static index plug-ins to the XML file:

<backingMapPluginCollection id="person">
   <bean id="MapIndexPlugin" 
      className="com.ibm.websphere.objectgrid.plugins.index.HashIndex">
         <property name="Name" type="java.lang.String" value="CODE" 
            description="index name" />
         <property name="RangeIndex" type="boolean" value="true" 
            description="true for MapRangeIndex" />
         <property name="AttributeName" type="java.lang.String" value="employeeCode" 
            description="attribute name" />
   </bean>
</backingMapPluginCollection>

In this XML configuration example, the built-in HashIndex class is used as the index plug-in. The HashIndex supports properties that users can configure, such as Name, RangeIndex, and AttributeName.

The Name property is configured as CODE, 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 RangeIndex property is configured as true, which means the application can cast the retrieved index object to the MapRangeIndex interface. If the RangeIndex property is configured as false, the application can only cast the retrieved index object to the MapIndex interface. A MapRangeIndex supports functions to find data using range functions such as greater than, less than, or both, while a MapIndex supports equals functions only. If the index is to be used by query, the RangeIndex property must be configured to true on single-attribute indexes or false on relationship or composite indexes. For a relationship index and composite index, the RangeIndex property must be configured to false.
The AttributeName property is configured as employeeCode, which means the employeeCode attribute of the cached object is used to build a single-attribute index. If an application must search for cached objects with multiple attributes, the AttributeName property can be set to a comma-delimited list of attributes, yielding a composite index.

In summary, the previous example defines a single-attribute range HashIndex. It is a single-attribute HashIndex because the AttributeName property value is employeeCode that includes only one attribute name. It also is a range HashIndex.