Home

BackingMap interface

+

Search Tips   |   Advanced Search


Overview

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 Using 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.


BackingMap attributes

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

backingMap attributes

copyKey
Specifies if the a copy of the key is required when a map entry is created. Copying the key object allows the application to use the same key object for each ObjectMap operation. Set true to copy the key object when a map entry is created. The default value is false. (Optional)

CopyMode
Specifies if a get operation of an entry in the BackingMap instance returns the actual value, a copy of the value, or a proxy for the value. Set the CopyMode attribute to one of five values:

COPY_ON_READ_AND_COMMIT

The default value is

COPY_ON_READ_AND_COMMIT. Set the value to COPY_ON_READ_AND_COMMIT to ensure that an application never has a reference to the value object that is in the BackingMap instance. Instead, the application is always working with a copy of the value that is in the BackingMap instance. (Optional)

COPY_ON_READ

Set the value to COPY_ON_READ to improve performance over the COPY_ON_READ_AND_COMMIT value by eliminating the copy that occurs when a transaction is committed. To preserve the integrity of the BackingMap data, the application commits to delete every reference to an entry after the transaction is committed. Setting this value results in an ObjectMap.get method returning a copy of the value instead of a reference to the value, which ensures changes that are made by the application to the value does not affect the BackingMap element until the transaction is committed.

COPY_ON_WRITE

Set the value to COPY_ON_WRITE to improve performance over the COPY_ON_READ_AND_COMMIT value by eliminating the copy that occurs when ObjectMap.get method is called for the first time by a transaction for a given key. Instead, the ObjectMap.get method returns a proxy to the value instead of a direct reference to the value object. The proxy ensures that a copy of the value is not made unless the application calls a set method on the value interface.

NO_COPY

Set the value to NO_COPY to allow an application to never modify a value object that is obtained using an ObjectMap.get method in exchange for performance improvements. Set the value to NO_COPY for maps associated with EntityManager API entities.

COPY_TO_BYTES

Set the value to COPY_TO_BYTES to improve memory footprint for complex Object types and to improve performance when the copying of an Object relies on serialization to make the copy. If an Object is not Cloneable or a custom ObjectTransformer with an efficient copyValue method is not provided, the default copy mechanism is to serialize and inflate the object to make a copy. With the COPY_TO_BYTES setting, inflate is only performed during a read and serialize is only performed during commit.
For more information about these settings, see Tuning the copy mode .
evictionTriggers
Set the types of additional eviction triggers to use. All evictors for the backing map use this list of additional triggers. To avoid an IllegalStateException, this attribute must be called before the ObjectGrid.initialize() method. Also, note that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if the method has yet to be called by the application. Entries in the list of triggers are separated by semicolons. Current eviction triggers include MEMORY_USAGE_THRESHOLD. For more information, see Plug-ins for evicting cache objects . (Optional)
lockStrategy
Specifies if the internal lock manager is used whenever a map entry is accessed by a transaction. Set this attribute to one of three values:

OPTIMISTIC,

PESSIMISTIC, or NONE. The default value is

OPTIMISTIC. (Optional)

The optimistic locking strategy is typically used when a map does not have a loader plug-in, is mostly read and not frequently written to or updated, and the locking is not provided by the persistence manager using eXtreme Scale as a side cache or by the application. An exclusive lock is obtained on a map entry that is inserted, updated, or removed at commit time. The lock ensures that the version information cannot be changed by another transaction while the transaction being committed is performing an optimistic version check.

The pessimistic locking strategy is typically used for a map that does not have a loader plug-in, and locking is not provided by a persistence manager using eXtreme Scale as a side cache, by a loader plug-in, or by the application. The pessimistic locking strategy is used when the optimistic locking strategy fails too often because update transactions frequently collide on the same map entry.

The no locking strategy indicates that the internal LockManager is not needed. Concurrency control is provided outside of eXtreme Scale, either by the persistence manager using eXtreme Scale as a side cache or application, or by the loader plug-in that uses database locks to control concurrency.

For more information, see Lock manager .

lockTimeout
Set the lock timeout used by the lock manager for the BackingMap instance. Set the lockStrategy attribute to OPTIMISTIC or PESSIMISTIC to create a lock manager for the BackingMap instance. To prevent deadlocks from occurring, the lock manager has a default timeout value of 15 seconds. If the timeout limit is exceeded, a LockTimeoutException exception occurs. The default value of 15 seconds is sufficient for most applications, but on a heavily loaded system, a timeout might occur when no deadlock exists. Use the lockTimeout attribute to increase the value from the default to prevent false timeout exceptions from occurring. Set the lockStrategy attribute to NONE to specify the BackingMap instance use no lock manager. (Optional)
name
Name that is assigned to the backingMap instance. If this attribute is missing, the XML validation fails. (Required)
nearCacheEnabled
Set true to enable the client local cache. To use a near cache, the lockStrategy attribute must be set to NONE or OPTIMISTIC.

Default: true (Optional)

nearCacheInvalidationEnabled
Set true to enable the removal of stale data from the near cache as quickly as possible. Any update, deletion, or invalidation operation against the data grid triggers an asynchronous invalidation in the near cache . Because the invalidation is asynchronous, client applications might access stale data for a short time period after an update has occurred before the stale value is removed from the near cache . To use near cache invalidation, the lockStrategy attribute must be set to NONE or OPTIMISTIC.

Default: false (Optional)

nearCacheLastAccessTTLSyncEnabled
Set true to enable time-to-live (TTL) information to be synchronized with the remote data grid. The LAST_ACCESS_TIME TTL evictor type must be enabled when you enable this property.

Default: false (Optional)

nullValuesSupported
Set true to support null values in the ObjectMap. When null values are supported, a get operation that returns null might mean that the value is null or that the map does not contain the key that is passed to the method. Default is true. (Optional)

numberOfBuckets

Deprecated: This property has been deprecated. Use the nearCacheEnabled attribute to enable the near cache . Number of buckets for the BackingMap instance to use. The BackingMap instance uses a hash map for implementation. If multiple entries exist in the BackingMap, more buckets lead to better performance because the risk of collisions is lower as the number of buckets increases. More buckets also lead to more concurrency. Specify a value of

0 to disable the near cache on a client. When you set the value to 0 for a client, set the value in the client override ObjectGrid XML descriptor file only. (Optional)

numberOfLockBuckets
Set the number of lock buckets used by the lock manager for the BackingMap instance. Set the lockStrategy attribute to OPTIMISTIC or PESSIMISTIC to create a lock manager for the BackingMap instance. The lock manager uses a hash map to track entries that are locked by one or more transactions. If many entries exist, more lock buckets lead to better performance because the risk of collisions is lower as the number of buckets grows. More lock buckets also lead to more concurrency. Set the lockStrategy attribute to NONE to specify the BackingMap instance use no lock manager. (Optional)

pluginCollectionRef
Specifies a reference to a backingMapPluginCollection plug-in. The value of this attribute must match the ID attribute of a backingMapCollection plug-in. Validation fails if no matching ID exists. Set the attribute to reuse BackingMap plug-ins. (Optional)

preloadMode
Set the preload mode if a loader plug-in is set for this BackingMap instance. The default value is false. If the attribute is set to true, the Loader.preloadMap(Session, BackingMap) method is invoked asynchronously. Otherwise, running the method is blocked when loading data so that the cache is unavailable until preload completes. Preloading occurs during initialization. (Optional)

readOnly
Set a BackingMap instance as read/write when you specify the attribute as false. When you specify the attribute as true, the BackingMap instance is read-only. (Optional)

template
Specifies if dynamic maps can be used. Set this value to true if the BackingMap map is a template map. Template maps can be used to dynamically create maps after the ObjectGrid is started. Calls to Session.getMap(String) result in dynamic maps being created if the name passed to the method matches the regular expression specified in the name attribute of the backingMap. The default value is false. (Optional)

timeToLive
Specifies in seconds how long each map entry is present. The default value of

0 means that the map entry is present forever, or until the application explicitly removes or invalidates the entry. Otherwise, the TTL evictor evicts the map entry based on this value. (Optional)

ttlEvictorType
Specifies how the expiration time of a BackingMap entry is computed. Set this attribute to one of these values:

CREATION_TIME,

LAST_ACCESS_TIME,

LAST_UPDATE_TIME, or NONE. The CREATION_TIME value indicates that an entry expiration time is the sum of the creation time of the entry plus the timeToLive attribute value. The LAST_ACCESS_TIME value indicates that an entry expiration time is the sum of the last access time of the entry (whether the entry was updated or merely read), plus the timeToLive attribute value. The LAST_UPDATE_TIME value indicates that an entry expiration time is the sum of the last update time of the entry plus the timeToLive attribute value. The NONE value, which is the default, indicates that an entry has no expiration time and is present in the BackingMap instance until the application explicitly removes or invalidates the entry. (Optional)

valueInterfaceClassName
Specifies a class that is required when you set the CopyMode attribute to COPY_ON_WRITE. This attribute is ignored for all other modes. The COPY_ON_WRITE value uses a proxy when ObjectMap.get method calls are made. The proxy ensures that a copy of the value is not made unless the application calls a set method on the class specified as the valueInterfaceClassName attribute. (Optional)

viewRef
Specifies that the backingMap is a view map. (Optional)

writeBehind
Specifies that the write-behind support is enabled with write-behind parameters (Optional). Write-behind parameters consist of a maximum update time and a maximum key update count. The format of the write-behind parameter is

"[T(time)][;][C(count)]". The database is updated when one of the following events occurs:

  • The maximum update time, specified in seconds, has passed since the last update.
  • The number of available updates in the queue map has reached the maximum update count.

For more information, see Write-behind caching .

Write-behind support is an extension of the Loader plug-in, which you use to integrate eXtreme Scale with the database. For example, consult the Configuring JPA loaders information about configuring a JPA loader.

The following example demonstrates how to define the someMap BackingMap in the someGrid ObjectGrid instance and set various attributes of the BackingMap 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)


BackingMap plug-ins

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