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.
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:
- 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 three values: CREATION_TIME,
LAST_ACCESS_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
indicates that the evictor adds the TimeToLive attribute to the time
that the map entry was last accessed 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)
BackingMap 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 is used for a persistent store for
the BackingMap. 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 Using 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.