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.

Once an application has a reference to an ObjectGrid instance, it can get to work. A thread in an application needs its own Session. We recommend that once the application wants to use the ObjectGrid on a thread, it should just call one of the getSession() methods to obtain one. This operation is cheap--there is no need to pool these normally.  If the application is using an injection framework, a Session can easily be injected into an application bean when it is needed.

In order to access data stored in Maps in the ObjectGrid, the application now has two choices. If it is using entities, the EntiyManager APIs can be used. These can be obtained from the Session using the Session.getEntityManager() method. See the appropriate section for more information on EntityManagers. The EntityManager interface is a simpler interface than the Map-based API but does carry a performance overhead due to the overhead of tracking changes in objects.  The Map-based API is obtained by using the Session.getMap() method.

The ObjectGrid uses transactions. When an application interacts with a Session, it must be in the context of a transaction. Normally, a transaction is begun and committed or rolled back using the Session.begin(), Session.commit() and Session.rollback() methods on Session. Applications can also work in auto-commit mode, where the Session automatically begins and commits a transaction whenever the application interacts with Maps. We do not recommend this mode because it is slower.

What if I do not want transactions?

Customers often say transactions sound slow. ObjectGrid uses transactions for three reasons:

• allow rollback of changes if an exception occurs or business logic needs to undo state changes
• locks on data are held and released within the lifetime of a transaction, allowing a set of changes to be made atomically, that is, all changes or no changes to data
• a transaction is an atomic unit of replication

ObjectGrid lets a Session customize how much "transaction" is really needed. An application can turn off rollback support and locking but does so at a cost to the application. The application must handle the lack of these features itself.

For example, an application can turn off locking by configuring the BackingMap locking strategy to be NONE. This is fast but concurrent transactions can now modify the same data with no protection from each other. The application is responsible for all locking and data consistency when NONE is used.

An application can also change the way objects touched by the transaction are copied. It can specify this using the ObjectMap.setCopyMode method. This allows copying to be turned off. This is normally used for read only transactions if it is okay for a get to return different values for the same object within a transaction. This can happen because when it did an ObjectMap.get for the object at T1, it got the value at that point in time. If it calls that method again within that transaction at a later time T2, another thread may have changed the value. Thus, the application sees a different value. If the application modifies an object retrieved using a NONE CopyMode, it is changing the committed copy of that object directly. Rolling back the transaction has no meaning in this mode. You are changing the ObjectGrid's only copy. While this is fast, clearly there are side effects to worry about here. An application using a NONE CopyMode must never rollback the transaction as if it does then indexes will not be updated with the changes AND the changes will not be replicated if replication is turned on. ObjectGrid's defaults are easy to use and bulletproof. If you start trading performance in exchange for less bulletproofing, the application needs to be aware of what it is doing to avoid unintended side effects.

Be Careful Be careful when changing either locking or the CopyMode. ObjectGrid provides a lot of flexibility to the customer. But that flexibility must be used responsibly, or unpredictable application behavior is almost guaranteed.

Interacting with data stored in the ObjectGrid

Once a session has been obtained then the following code fragment shows the typical pattern when using the MAP API for inserting data.

Session session = ...;
ObjectMap personMap = session.getMap("PERSON");
session.begin
Person p = new Person();
p.name = "John Doe";
personMap.insert(p.name, p);
session.commit();

Here is the same example using the EntityManager. This assumes Person is mapped to an Entity as described elsewhere.

Session session = ...;
EntityManager em = session.getEntityManager();
session.begin
Person p = new Person();
p.name = "John Doe";
em.persist(p);
session.commit();

The ObjectMap interface has the usual Map operations such as put, get and remove. However, we recommend using the more specific verbs: get, getForUpdate, insert, update and remove. These methods convey the intent more precisely that the traditional Map APIs.

There is also a way of associating keywords with entries and then working with entries using the keywords as a grouping mechanism. As of V6.1, we do not recommend this approach as the indexing support is more flexible and does the same thing.

Here is an example for updating an Object

session.begin
Person p = (Person)personMap.getForUpdate("John Doe");
p.name = "John Doe";
p.age = 30;
personMap.update(p.name, p);
session.commit();

Note, the application should normally use the getForUpdate method rather than a simple get to lock the record. The update method must be called to actually provide the updated value to the Map. If update is not called then the Map is unchanged. Here is the same fragment using the EntityManager

session.begin
Person p = (Person)em.findForUpdate(Person.class, "John Doe");
p.age = 30;
session.commit();

This is a lot simpler than the Map approach. The ObjectGrid finds the Entity and returns a managed object to the application. The application modifies the object and commits the transaction. ObjectGrid tracks changes to managed objects automatically at commit time and does the necessary updates.

Partitions and transactions

ObjectGrid transactions can only update a single partition. Transactions from a clients can read from multiple partitions but they can only update one. If an application attempts to update two partitions then the transaction will fail and be rolled back. A transaction using an embedded ObjectGrid (grid logic) has no routing capability and can only see data in that partition. This business logic can always get a second session thats a true client session to access other partitions but this would be on an independant transaction.

Queries and partitions

If a transaction has already searched for an entity, the transaction is pinned to the partition for that entity. Any queries executed on a pinned transaction are routed to the pinned partition.

If a query is executed in a partition before it is pinned, the programmer must set the partition id to use for the query. This is an integer. The query is then routed to that partition.

Query only searches within a single partition. However, it is trivial to use the DataGrid APIs to run the same query in parallel on all partitions or a subset of partitions. This is the recommended way to find an entry that could be in any partition.

Wiki Disclaimer and License

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