The ObjectMap interface is used for transactional interaction
between applications and BackingMaps.
Purpose
An ObjectMap instance is obtained from
a Session object that corresponds to the current thread. The ObjectMap
interface is the main vehicle that applications use to make changes
to entries in a BackingMap.
Obtain an ObjectMap instance
An application
gets an ObjectMap instance from a Session object using the
Session.getMap(String) method. The following code snippet
demonstrates how to obtain an ObjectMap instance:
ObjectGrid objectGrid = ...;
BackingMap backingMap = objectGrid.defineMap("mapA");
Session sess = objectGrid.getSession();
ObjectMap objectMap = sess.getMap("mapA");
Each ObjectMap
instance corresponds to a particular Session object. Calling the
getMap method multiple times on a particular Session object
with the same BackingMap name always returns the same ObjectMap instance.
Automatically commit transactions
Operations
against BackingMaps that use ObjectMaps and JavaMaps are performed
most efficiently within a Session transaction. WebSphere® eXtreme Scale provides autocommit
support when methods on the ObjectMap and JavaMap interfaces are called
outside of a Session transaction. The methods start an implicit transaction,
perform the requested operation, and commit the implicit transaction.
Method semantics
An explanation of the semantics
behind each method on the ObjectMap and JavaMap interfaces follows.
- containsKey method
- The containsKey method determines if a key
has a value in the BackingMap or Loader. If null values are supported
by an application, this method can be used to determine if a null
reference that is returned from a get operation refers to a null value
or indicates that the BackingMap and Loader do not contain the key.
- flush method
- The flush method semantics are similar to the flush method on the Session interface. The notable difference
is that the Session flush applies the current pending changes for
all of the maps that are modified in the current session. With this
method, only the changes in this ObjectMap instance are flushed to
the loader.
- get method
- The get method fetches the entry from the BackingMap
instance. If the entry is not found in the BackingMap instance but
a Loader is associated with the BackingMap instance, the BackingMap
instance attempts to fetch the entry from the Loader. The getAll method is provided to allow batch fetch processing.
- getForUpdate method
- The getForUpdate method is the same as the get method, but using the getForUpdate method tells the BackingMap and Loader that the intention is to
update the entry. A Loader can use this hint to issue a SELECT for
UPDATE query to a database backend. If a pessimistic locking strategy
is defined for the BackingMap, the lock manager locks the entry. The getAllForUpdate method is provided to allow batch fetch
processing.
- insert method
- The insert method inserts an entry into the
BackingMap and the Loader. Using this method tells the BackingMap
and Loader that you want to insert an entry that did not previously
exist. When you invoke this method on an existing entry, an exception
occurs when the method is invoked or when the current transaction
is committed.
- invalidate method
- The semantics of the invalidate method depend
on the value of the isGlobal parameter that is
passed to the method. The invalidateAll method
is provided to allow batch invalidate processing.
Local invalidation
is specified when the value false is passed as the isGlobal parameter of the invalidate method. Local invalidation discards
any changes to the entry in the transaction cache. If the application
issues a get method, the entry is fetched from
the last committed value in the BackingMap. If no entry is present
in the BackingMap, the entry is fetched from the last flushed or committed
value in the Loader. When a transaction is committed, any entries
that are marked as locally invalidated have no impact on the BackingMap.
Any changes that were flushed to the Loader are still committed even
if the entry was invalidated.
Global invalidation is specified
when true is passed as the isGlobal parameter
of the invalidate method. Global invalidation discards
any pending changes to the entry in the transaction cache and bypasses
the BackingMap value on subsequent operations that are performed on
the entry. When a transaction is committed, any entries that are marked
as globally invalidated are evicted from the BackingMap.
Consider
the following use case for invalidation as an example: The BackingMap
is backed by a database table that has an auto increment column. Increment
columns are useful for assigning unique numbers to records. The application
inserts an entry. After the insert, the application needs to know
the sequence number for the inserted row. It knows that its copy of
the object is old, so it uses global invalidation to get the value
from the Loader. The following code demonstrates this use case:Session sess = objectGrid.getSession();
ObjectMap map = sess.getMap("mymap");
sess.begin();
map.insert("Billy", new Person("Joe", "Bloggs", "Manhattan"));
sess.flush();
map.invalidate("Billy", true);
Person p = map.get("Billy");
System.out.println("Version column is: " + p.getVersion());
map.commit();
// Close the session (optional in Version 7.1.1 and later) for improved performance
session.close();
This code sample adds an entry for Billy. The version attribute of Person is set using an auto-increment
column in the database. The application first performs an insert command.
It then issues a flush, which causes the insert to be sent to the
Loader and database. The database sets the version column to the next
number in the sequence, which makes the Person object in the transaction
outdated. To update the object, the application is globally invalidated.
The next get method that is issued gets the entry
from the Loader, ignoring the transaction value. The entry is fetched
from the database with the updated version value.
- put method
- The semantics of the put method are dependent
on whether a previous get method was invoked in
the transaction for the key. If the application issues a get operation that returns an entry that exists in the
BackingMap or loader, the put method invocation
is interpreted as an update and returns the previous value in the
transaction. If a put method invocation ran without
a previous get method invocation, or a previous get method invocation did not find an entry, the operation
is interpreted as an insert. The semantics of the insert and update methods apply when the put operation is committed. The putAll method is
provided to enable batch insert and update processing.

Note: The
setPutMode(PutMode.UPSERT) method is added to change the default behavior of the ObjectMap
and JavaMap
put() and
putAll() methods to behave like
ObjectMap.upsert() and
upsertAll() methods.
The PutMode.UPSERT method replaces the setPutMode(PutMode.INSERTUPDATE) method. Use the PutMode.UPSERT method to tell
the BackingMap and loader that an entry in the data grid needs to
place the key and value into the grid. The BackingMap and loader does
either an insert or an update to place the value into the grid and
loader. If you run the upsert API within your applications,
then the loader gets an UPSERT LogElement type, which allows loaders
to do database merge or upsert calls instead of using insert or update.
upsert method
- Use the upsert method to tell the BackingMap
and loader that an entry in the data grid needs to place the key and
value into the grid. The BackingMap and loader does either an insert
or an update to place the value into the grid and loader. If you run
the upsert API within your applications, then the
loader gets an UPSERT LogElement type, which allows loaders to do
database merge or upsert calls instead of using insert or update.
Note: Before the upsert method, you used the put or getForUpdate methods
to in your application code to insert or update data; for example:
session.begin();
map.getForUpdate();
map.put();
session.commit();
With the upsert method, you can use the
following lines of code to insert or update data:
session.begin();
map.upsert();
session.commit();
lock method
- When using pessimistic locking, you can use the lock method to
lock data, or keys, without returning any data values. With the lock
method, you can lock the key in the grid or lock the key and determine
whether the value exists in the grid. In previous releases, you used
the get and getForUpdate APIs to lock keys in the data grid. However,
if you did not need data from the client, performance is degraded
retrieving potentially large value objects to the client. Additionally,
containsKey does not currently hold any locks, so you were forced
do use get and getForUpdate to get appropriate locks when using pessimistic
locking. The lock API now gives you a containsKey semantics while
holding the lock. See the following examples:
- boolean ObjectMap.lock(Object key, LockMode lockMode);
Locks the key in the map, returning true if the key exists, and
returning false if the key does not exist.
- List<Boolean> ObjectMap.lockAll(List keys, LockMode
lockMode);
Locks a list of keys in the map, returning a
list of true or false values; returning true if the
key exists, and returning false if the key does not
exist.
LockMode is an enum with possible values SHARED, UPGRADABLE,
and EXCLUSIVE, where you can specify the keys that you want to lock.
See the following table to understand the relationship between these
lock mode values and the behaviour of existing methods:Table 1. LockMode values and existing method equivalentsLock mode |
Method equivalent |
SHARED |
get() |
UPGRADABLE |
getForUpdate() |
EXCLUSIVE |
getNextKey() and commit() |
See the following example code of the LockMode parameter:session.begin();
map.lock(key, LockMode.UPGRADABLE);
map.upsert();
session.commit()
- remove method
- The remove method removes the entry from the
BackingMap and the Loader, if a Loader is plugged in. The value of
the object that was removed is returned by this method. If the object
does not exist, this method returns a null value. The removeAll method is provided to enable batch deletion processing without the
return values.
- setCopyMode method
- The setCopyMode method specifies a CopyMode
value for this ObjectMap. With this method, an application can override
the CopyMode value that is specified on the BackingMap. The specified
CopyMode value is in effect until clearCopyMode method is invoked. Both methods are invoked outside of transactional
bounds. A CopyMode value cannot be changed in the middle of a transaction.
- touch method
- The touch method updates the last access time
for an entry. This method does not retrieve the value from the BackingMap.
Use this method in its own transaction. If the provided key does not
exist in the BackingMap because of invalidation or removal, an exception
occurs during commit processing.
- update method
- The update method explicitly updates an entry
in the BackingMap and the Loader. Using this method indicates to the
BackingMap and Loader that you want to update an existing entry. An
exception occurs if you invoke this method on an entry that does not
exist when the method is invoked or during commit processing.
- getIndex method
- The getIndex method attempts to obtain a named
index that is built on the BackingMap. The index cannot be shared
between threads and works on the same rules as a Session. The returned
index object should be cast to the right application index interface
such as the MapIndex interface, the MapRangeIndex interface, or a custom index interface.
- clear method
- The clear method removes all cache entries
from a map from all partitions. This operation is an auto-commit function,
so no active transaction should be present when calling clear.
Note: The clear method only clears out the map on which it is called, leaving
any related entity maps unaffected. This method does not invoke the
Loader plug-in.