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 the value to 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
- Sets 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.
- lockTimeout
- Sets the lock timeout that is 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
- Specifies the name that is assigned to the backingMap instance.
If this attribute is missing, the XML validation fails. (Required)
nearCacheEnabled
- Set the value to 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 the value to 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 the value to 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 the value to 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. The default
value is true. (Optional)
- numberOfBuckets

Deprecated: This property has been deprecated. Use the
nearCacheEnabled attribute to enable the near cache.
The BackingMap instance
uses a hash map for implementation. The numberOfBuckets attribute specifies the number of buckets for the BackingMap instance
to use. 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
- The lock manager uses a hash map to track entries that are locked
by one or more transactions. The numberOfLockBuckets attribute sets the number of lock buckets that are 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. 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
- Sets 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
- Sets 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 that is 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 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)
BackingMap plug-ins
The BackingMap interface
has several optional plug points for more extensible interactions
with the ObjectGrid:
- Evictor: An evictor plug-in is a default mechanism is provided
for evicting cache entries and a plug-in for creating custom evictors.
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 a cache entry
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. You can use the provided 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. For more information, see Plug-ins for evicting cache objects.
ObjectTransformer:
An ObjectTransformer plug-in allows you to serialize, deserialize,
and copy objects in the cache. The ObjectTransformer interface
has been replaced by the DataSerializer plug-ins,
which you can use to efficiently store arbitrary data in WebSphere eXtreme Scale so that existing product
APIs can efficiently interact with your data. For more information,
see ObjectTransformer plug-in.
OptimisticCallback:
An OptimisticCallback plug-in allows you to customize versioning and
comparison operations of cache objects when you are using the optimistic
lock strategy. The OptimisticCallback plug-in has been replaced by
the ValueDataSerializer.Versionable interface,
which you can implement when you use the DataSerializer plug-in with
the COPY_TO_BYTES copy mode or when you use the @Version annotation
with the EntityManager API. For more information,
see Plug-ins for versioning and comparing cache objects.
- MapEventListener: A MapEventListener plug-in provides callback
notifications and significant cache state changes that occur for a
BackingMap. 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. For more
information, see MapEventListener plug-in.
- BackingMapLifecycleListener: A BackingMapLifecycleListener
plug-in provides BackingMap life cycle events for the BackingMap instance.
The BackingMapLifecycleListener plug-in can be used as an optional
mix-in interface for all other BackingMap plug-ins.
- BackingMapPlugin: A BackingMapPlugin is an optional mix-in
interface that provides extended life cycle management events for
all other BackingMap plug-ins.
- Indexing: Use the indexing
feature, which is represented
by the MapIndexplug-in plug-in, to build an index or several indexes
on a BackingMap map to support non-key data access.
- Loader: A Loader plug-in on an ObjectGrid map acts as a
memory cache for data that is typically kept in a persistent store
on either the same system or some other system. (Server side only)
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.
For more information, see Plug-ins for communicating with databases.
- MapSerializerPlugin: A MapSerializerPlugin allows you to
serialize and inflate Java objects
and non-Java data in the cache. It is used with the DataSerializer
mix-in interfaces, allowing robust and flexible options for high-performance
applications.