Program guide > Access data with client applications

BackMap interface

Each ObjectGrid instance contains a collection of BackingMap objects. Use the defineMap method or the createMap method of the ObjectGrid interface to name and add each BackingMap to an ObjectGrid instance. These methods return a BackingMap instance that is then used to define the behavior of an individual Map. A BackingMap can be considered as an in-memory cache of committed data for an individual map.

Session interface

The Session interface is used to begin a transaction and to obtain the ObjectMap or JavaMap that is required for performing transactional interaction between an application and a BackingMap object. However, the transaction changes are not applied to the BackingMap object until the transaction is committed. A BackingMap can be considered as an in-memory cache of committed data for an individual map. For more information, see Use Sessions to access data in the grid.

The BackingMap interface provides methods for setting BackingMap attributes. Some of the set methods allow extensibility of a BackingMap through several custom designed plug-ins. See the following list of the set methods for setting attributes and providing custom designed plug-in support:

// For setting BackingMap attributes.
public void setReadOnly(boolean readOnlyEnabled);
public void setNullValuesSupported(boolean nullValuesSupported);
public void setLockStrategy( LockStrategy lockStrategy );
public void setCopyMode(CopyMode mode, Class valueInterface);
public void setCopyKey(boolean b);
public void setNumberOfBuckets(int numBuckets);
public void setNumberOfLockBuckets(int numBuckets);
public void setLockTimeout(int seconds);
public void setTimeToLive(int seconds);
public void setTtlEvictorType(TTLType type);
public void setEvictionTriggers(String evictionTriggers);

// For setting an optional custom plug-in provided by application.
public abstract void setObjectTransformer(ObjectTransformer t);
public abstract void setOptimisticCallback(OptimisticCallback checker);
public abstract void setLoader(Loader loader);
public abstract void setPreloadMode(boolean async);
public abstract void setEvictor(Evictor e);
public void setMapEventListeners( List /*MapEventListener*/ eventListenerList );
public void addMapEventListener(MapEventListener eventListener );
public void removeMapEventListener(MapEventListener eventListener );
public void addMapIndexPlugin(MapIndexPlugin index);
public void setMapIndexPlugins(List /\* MapIndexPlugin \*/ indexList );
public void createDynamicIndex(String name, boolean isRangeIndex,
String attributeName, DynamicIndexCallback cb);
public void createDynamicIndex(MapIndexPlugin index, DynamicIndexCallback cb);
public void removeDynamicIndex(String name);

A corresponding get method exists for each of the set methods listed.

BackMap attributes

Each BackingMap has the following attributes that can be set to modify or control the BackingMap behavior:

• ReadOnly: This attribute indicates if the Map is a read-only Map or a read and write Map. If this attribute is never set for the Map, then the Map is defaulted to be a read and write Map. When a BackingMap is set to be read only, ObjectGrid optimizes performance for read only when possible.

• NullValuesSupported: This attribute indicates if a null value can be put into the Map. If this attribute is never set, the Map does not support null values. If null values are supported by the Map, a get operation that returns null can mean that either the value is null or the map does not contain the key specified by the get operation.

• LockStrategy: This attribute determines if a lock manager is used by this BackingMap. If a lock manager is used, then the LockStrategy attribute is used to indicate whether an optimistic locking or pessimistic locking approach is used for locking the map entries. If this attribute is not set, then the optimistic LockStrategy is used. See the Locking topic for details on the supported lock strategies.

• CopyMode: This attribute determines if a copy of a value object is made by the BackingMap when a value is read from the map or is put into the BackingMap during the commit cycle of a transaction. Various copy modes are supported to allow the application to make the trade-off between performance and data integrity. If this attribute is not set, then the COPY_ON_READ_AND_COMMIT copy mode is used. This copy mode does not have the best performance, but it has the greatest protection against data integrity problems. If the BackingMap is associated with an EntityManager API entity, then the CopyMode setting has no effect unless the value is set to COPY_TO_BYTES. If any other CopyMode is set, it is always set to NO_COPY.

  To override the CopyMode for an entity map, use the ObjectMap.setCopyMode method. For more information about the copy modes, see CopyMode method best practices.

• CopyKey: This attribute determines if the BackingMap makes a copy of a key object when an entry is first created in the map. The default action is to not make a copy of key objects because keys are normally unchangeable objects.

• NumberOfBuckets: This attribute indicates the number of hash buckets to be used by the BackingMap. The BackingMap implementation uses a hash map for its implementation. If a lot of entries exist in the BackingMap, then more buckets means better performance. The number of keys that have the same bucket becomes lower as the number of buckets grows. More buckets also mean more concurrency. This attribute is useful for fine tuning performance. An undefined default value is used if the application does not set the NumberOfBuckets attribute.

• NumberOfLockBuckets: This attribute indicates the number of lock buckets that are be used by the lock manager for this BackingMap. When the LockStrategy is set to OPTIMISTIC or PESSIMISTIC, a lock manager is created for the BackingMap. The lock manager uses a hash map to keep track of entries that are locked by one or more transactions. If a lot of entries exist in the hash map, more lock buckets lead to better performance because the number of keys that collide on the same bucket is lower as the number of buckets grows. More lock buckets also means more concurrency. When the LockStrategy attribute is set to NONE, no lock manager is used by this BackingMap. In this case, setting numberOfLockBuckets has no effect. If this attribute is not set, an undefined value of is used.

• LockTimeout: This attribute is used when the BackingMap is using a lock manager. The BackingMap uses a lock manager when the LockStrategy attribute is set to either OPTIMISTIC or PESSIMISTIC. The attribute value is in seconds and determines how long the lock manager waits for a lock to be granted. If this attribute is not set, then 15 seconds is used as the LockTimeout value. See Pessimistic locking for details regarding the lock wait timeout exceptions that can occur.

• TtlEvictorType: Every BackingMap has its own built in time to live evictor that uses a time-based algorithm to determine which map entries to evict. By default, the built in time to live evictor is not active. You can activate the time to live evictor by calling the setTtlEvictorType method with one of these values: CREATION_TIME, LAST_ACCESS_TIME, LAST_UPDATE_TIME, or NONE. A value of CREATION_TIME indicates that the evictor adds the TimeToLive attribute to the time that the map entry was created in the BackingMap to determine when the evictor should evict the map entry from the BackingMap. A value of LAST_ACCESS_TIME (or LAST_UPDATE_TIME) indicates that the evictor adds the TimeToLive attribute to the time that the map entry was last accessed (or accessed and updated) by some transaction that the application is running to determine when evictor should evict the map entry. The map entry is evicted only if a map entry is never accessed by any transaction for a period of time that is specified by the TimeToLive attribute. A value of NONE indicates the evictor should remain inactive and never evict any of the map entries. If this attribute is never set, then NONE is used as the default and the time to live evictor is not active. See Evictors for details regarding the built-in time to live evictor.

• TimeToLive: This attribute is used to specify the number of seconds that the built in time to live evictor needs to add to the creation or last access time for each entry as described for the TtlEvictorType attribute. If this attribute is never set, then the special value of zero is used to indicate the time to live is infinity. If this attribute is set to infinity, map entries are never evicted by the evictor.

The following example demonstrates how to define the someMap BackingMap in the someGrid ObjectGrid instance and set various attributes of the BackingMap by using the set methods of the BackingMap interface:

import com.ibm.websphere.objectgrid.BackingMap;
import com.ibm.websphere.objectgrid.LockStrategy;
import com.ibm.websphere.objectgrid.ObjectGrid;
import com.ibm.websphere.objectgrid.ObjectGridManagerFactory;

...

ObjectGrid og =
ObjectGridManagerFactory.getObjectGridManager().createObjectGrid("someGrid");
BackingMap bm = objectGrid.getMap("someMap");
bm.setReadOnly( true ); // override default of read/write
bm.setNullValuesSupported(false); // override default of allowing Null values
bm.setLockStrategy( LockStrategy.PESSIMISTIC ); // override default of OPTIMISTIC
bm.setLockTimeout( 60 ); // override default of 15 seconds.
bm.setNumberOfBuckets(251); // override default (prime numbers work best)
bm.setNumberOfLockBuckets(251); // override default (prime numbers work best)

BackMap plug-ins

The BackingMap interface has several optional plug points for more extensible interactions with the ObjectGrid:

• ObjectTransformer plug-in: For some map operations, a BackingMap might need to serialize, deserialize, or copy a key or value of an entry in the BackingMap. The BackingMap can perform these actions by providing a default implementation of the ObjectTransformer interface. An application can improve performance by providing a custom designed ObjectTransformer plug-in that is used by the BackingMap to serialize, deserialize, or copy a key or value of an entry in the BackingMap. See ObjectTransformer plug-in for more information.

• Evictor plug-in: The built in time to live evictor uses a time-based algorithm to decide when an entry in BackingMap must be evicted. Some applications might need to use a different algorithm for deciding when an entry in a BackingMap needs to be evicted. The Evictor plug-in makes a custom designed Evictor available to the BackingMap to use. The Evictor plug-in is in addition to the built in time to live evictor. It does not replace the time to live evictor. ObjectGrid provides a custom Evictor plug-in that implements well-known algorithms such as "least recently used" or "least frequently used". Applications can either plug-in one of the provided Evictor plug-ins or it can provide its own Evictor plug-in. See Eviction.

• MapEventListener plug-in: An application might want to know about BackingMap events such as a map entry eviction or a preload of a BackingMap completion. A BackingMap calls methods on the MapEventListener plug-in to notify an application of BackingMap events. An application can receive notification of various BackingMap events by using the setMapEventListener method to provide one or more custom designed MapEventListener plug-ins to the BackingMap. The application can modify the listed MapEventListener objects by using the addMapEventListener method or the removeMapEventListener method. See MapEventListener plug-in for more information.

• Loader plug-in: A BackingMap is an in-memory cache of a Map. A Loader plug-in is an option that is used by the BackingMap to move data between memory and a persistent store.. For example, a Java™ database connectivity (JDBC) Loader can be used to move data in and out of a BackingMap and one or more relational tables of a relational database. A relational database does not need to be used as the persistent store for a BackingMap. The Loader can also be used to moved data between a BackingMap and a file, between a BackingMap and a Hibernate map, between a BackingMap and a Java 2 Platform, Enterprise Edition (JEE) entity bean, between a BackingMap and another application server, and so on. The application must provide a custom-designed Loader plug-in to move data between the BackingMap and the persistent store for every technology that is used. If a Loader is not provided, the BackingMap becomes a simple in-memory cache. See Use a Loader for more information.

• OptimisticCallback plug-in: When the LockStrategy attribute for a BackingMap is set to OPTIMISTIC, either the BackingMap or a Loader plug-in must perform comparison operations for the values of the map. The OptimisticCallback plug-in is used by the BackingMap and the Loader to perform the optimistic versioning comparison operations. See OptimisticCallback plug-in for more information.

• MapIndexPlugin plug-in: A MapIndexPlugin plug-in, or an Index in short, is an option that is used by the BackingMap to build an index that is based on the specified attribute of the stored object. The index allows the application to find objects by a specific value or a range of values. There are two types of index: static and dynamic. Refer to Indexing for detailed information.

For more information regarding plug-ins, see Introduction to plug-ins.

Parent topic:

Access data with client applications

Related concepts

ObjectGrid interface

Interacting with an ObjectGrid using ObjectGridManager

Data access with indexes (Index API)

Access data in WebSphere eXtreme Scale

Use Sessions to access data in the grid

Cache objects with no relationships involved (ObjectMap API)

Cache objects and their relationships (EntityManager API)

Retrive entities and objects (Query API)

Configure clients with WebSphere eXtreme Scale

Related tasks

Program for transactions

Configure the lock timeout value

Related reference

Connect to a distributed ObjectGrid

Constant field values

+

Search Tips   |   Advanced Search