WebSphere eXtreme Scale Programming Guide > Access data in WebSphere eXtreme Scale > ObjectMap API

Dynamic maps

With the dynamic maps feature you can create maps after the grid has already been initialized.

In previous versions, eXtreme Scale has required you to define maps before initializing the ObjectGrid. As a result, you had to create all of the maps to be used before running transactions against any of the maps.

Advantages of dynamic maps

The introduction of dynamic maps reduces the restriction of having to define all maps prior to initialization. Through the use of template maps, maps can now be created after the ObjectGrid has been initialized.

Template maps are defined in the ObjectGrid XML file. Template comparisons are run when a Session requests a map that has not been previously defined. If the new map name matches the regular expression of a template map, the map is created dynamically and assigned the name of the requested map. This newly created map inherits all of the settings of the template map as defined by the ObjectGrid XML file.

Create dynamic maps

Dynamic map creation is tied to the Session.getMap(String) method. Calls to this method return an ObjectMap based on the BackingMap that was configured by the ObjectGrid XML file.

Pass in a String that matches the regular expression of a template map will result in the creation of an ObjectMap and an associated BackingMap.

See the API documentation for more information about the Session.getMap(String cacheName) method.

Define a template map in XML is as simple as setting a template boolean attribute on the backingMap element. When template is set to true, the name of the backingMap is interpreted as a regular expression.

WebSphere eXtreme Scale uses Java™ regular expression pattern matching. For more information about the regular expression engine in Java, see the API documentation for the java.util.regex package and classes.

A sample ObjectGrid XML file with a template map defined follows.

<?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="accounting">
            <backingMap name="payroll" readOnly="false" />
            <backingMap name="templateMap.*" template="true"
                pluginCollectionRef="templatePlugins" lockStrategy="PESSIMISTIC" />
        </objectGrid>
    </objectGrids>

    <backingMapPluginCollections>
        <backingMapPluginCollection id="templatePlugins">
            <bean id="Evictor"
                className="com.ibm.websphere.objectgrid.plugins.builtins.LFUEvictor" />
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>

The previous XML file defines one template map and one non-template map. The name of the template map is a regular expression: templateMap.*. When the Session.getMap(String) method is called with a map name matching this regular expression, the application creates a new map.

If you have defined more than one template map, assure that the name of any argument for the Session.getMap(String) method does not match more than one template map.

Example

Configuration of a template map is required in order to create a dynamic map. Add the template boolean to a backingMap in the ObjectGrid XML file.

<backingMap name="templateMap.*" template="true" />

The name of the template map is treated as a regular expression.

Call the Session.getMap(String cacheName) method with a cacheName that is a match for the regular expression results in the creation of the dynamic map. An ObjectMap object is returned from this method call, and an associated BackingMap object is created.

            Session session = og.getSession();
       ObjectMap map = session.getMap(“templateMap1”);

The newly created map is configured with all the attributes and plug-ins that were defined on the template map definition. Consider again the previous ObjectGrid XML file.

A dynamic map created based on the template map in this XML file would have an evictor configured and its lock strategy would be pessimistic.

A template is not an actual BackingMap. That is, the “accounting” ObjectGrid does not contain an actual “templateMap.*” map. The template is only used as a basis for dynamic map creation. However, include the dynamic map in the mapRef element of the deployment policy XML file named exactly as in the ObjectGrid XML. This identifies which mapSet the dynamic maps will be in.

Consider the change in behavior of the Session.getMap(String cacheName) method when using template maps. Before WebSphere eXtreme Scale Version 7.0, all calls to the Session.getMap(String cacheName) method resulted in an UndefinedMapException exception if the map requested did not exist. With dynamic maps, every name that matches the regular expression for a template map results in map creation. Be sure to note the number of maps that the application creates, particularly if the regular expression is generic.

Also, ObjectGridPermission.DYNAMIC_MAP is required for dynamic map creation when eXtreme Scale security is enabled. This permission is checked when the Session.getMap(String) method is called. For more information, see Application client authorization.

Limitations and considerations:

Limitations:

• You cannot use dynamic maps with Query.

• The QuerySchema does not support the template for mapName.

• You cannot use entities with dynamic maps.

• An entity BackingMap is implicitly defined, mapped to the entity through the class name.

Considerations:

• Many plug-ins have no way of determining the map with which each plug-in is associated.

• Other plug-ins differentiate themselves by using a map name or BackingMap name as an argument.

Parent topic

ObjectMap API

+

Search Tips   |   Advanced Search