See the WebSphere eXtreme Scale Wiki for links to eXtreme Scale Version 7.0 documentation.
If you log in with your developerWorks ID, you can leave comments and feedback for the development team.

This topic describes how applications interact with ObjectGrid using the ObjectMap and JavaMap interfaces. These two interfaces are used for transactional interaction between applications and BackingMaps.

ObjectMap interface

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.

Autocommit Transactions

Operations against BackingMaps that use ObjectMaps and JavaMaps are performed most effiently within a Session transaction. ObjectGrid 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

Following is an explanation of the semantics behind each method on the ObjectMap and JavaMap interfaces. The setDefaultKeyword method, the invalidateUsingKeyword method, and the methods that have a Serializable argument are discussed in the Keywords topic. The setTimeToLive method is discussed in the Evictors topic. See the API documentation for more information on these methods.

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 semantics of this method 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 are flushed to the loader.

get method
The get method fetches the entry from the BackingMap. If the entry is not found in the BackingMap but a Loader is associated with the BackingMap, it 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 aSELECT for UPDATEquery to a database backend. If a Pessimistic LockingStrategy is defined for the BackingMap, the lock manager locks the entry. The getAllForUpdate method is provided to allow batch fetch processing.

insert method
Inserts an entry into the BackingMap and the Loader. Using this method tells the BackingMap and Loader that you want to insert a previously nonexistent entry. 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 agetmethod, 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();

This code sample adds an entry forBilly. 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 performs a global invalidate. The next get method that is issued gets the entry from the Loader ignoring the transaction's 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 existent entry in the BackingMap or Loader, the put method invocation is interpreted as an update and returns the previous value in the transaction. A put method invocation without a previous get method invocation or a previous get method invocation that did not find an entry 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.

remove method

The remove method removes the entry from the BackingMap and the Loader, if one is plugged in. The value of the object that was removed is returned by this mehtod. 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 for this ObjectMap. With this method, an application can override the CopyMode that is specified on the BackingMap. The specified CopyMode is in effect until clearCopyMode method is invoked. Both methods are invoked outside of transactional bounds. A CopyMode cannot be changed in the middle of a transaction.

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 due to 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 an ObjectGrid 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 will only clear out the map on which it is called, leaving any related entity maps unaffected. This method will also not invoke the Loader plug-in.

JavaMap interface

A JavaMap instance is obtained from an ObjectMap object. The JavaMap interface has the same method signatures as ObjectMap, but with different exception handling. JavaMap extends the java.util.Map interface, so all exceptions are instances of the java.lang.RuntimeException class. Because JavaMap extends the java.util.Map interface, it is easy to quickly use ObjectGrid with an existing application that uses a java.util.Map interface for object caching.

Obtain a JavaMap instance

An application gets a JavaMap instance from an ObjectMap object using the ObjectMap.getJavaMap method. The following code snippet demonstrates how to obtain a JavaMap instance.

ObjectGrid objectGrid = ...;
BackingMap backingMap = objectGrid.defineMap("mapA");
Session sess = objectGrid.getSession();
ObjectMap objectMap = sess.getMap("mapA");
java.util.Map map = objectMap.getJavaMap();
JavaMap javaMap = (JavaMap) javaMap;

A JavaMap is backed by the ObjectMap from which it was obtained. Calling getJavaMap multiple times using a particular ObjectMap always returns the same JavaMap instance.

Supported methods

The JavaMap interface only supports a subset of the methods on the java.util.Map interface. The java.util.Map interface supports the following methods:

• containsKey(java.lang.Object)
• get(java.lang.Object)
• put(java.lang.Object, java.lang.Object)
• putAll(java.util.Map)
• remove(java.lang.Object)
• clear()

All other methods inherited from the java.util.Map interface result in a java.lang.UnsupportedOperationException exception.

Wiki Disclaimer and License

© Copyright IBM Corporation 2007,2009. All Rights Reserved.