WebSphere eXtreme Scale Programming Guide >



Access data in WebSphere eXtreme Scale


After an application has a reference to an ObjectGrid instance or a client connection to a remote grid, you can access and interact with data in the WebSphere eXtreme Scale configuration. With the ObjectGridManager API, use one of the createObjectGrid methods to create a local instance, or the getObjectGrid method for a client instance with a distributed grid.

A thread in an application needs its own Session. When an application wants to use the ObjectGrid on a thread, it should just call one of the getSession methods to obtain a thread. This operation is cheap--there is no need to pool these operations in most cases. If the application is using a dependency injection framework such as Spring, you can inject a Session into an application bean when necessary.

After you obtain a Session, the application can access data stored in maps in the ObjectGrid. If the ObjectGrid uses entities, you can use the EntityManager API, which you can obtain with the Session.getEntityManager method. Because it is closer to Java™ specifications, the EntityManager interface is simpler than the map-based API. However, the EntityManager API carries a performance overhead because it tracks changes in objects. The map-based API is obtained by using the Session.getMap method.

WebSphere eXtreme Scale uses transactions. When an application interacts with a Session, it must be in the context of a transaction. A transaction is begun and committed or rolled back using the Session.begin, Session.commit, and Session.rollback methods on the Session object. Applications can also work in auto-commit mode, where the Session automatically begins and commits a transaction whenever the application interacts with Maps. However, the auto-commit mode is slower.


The logic of using transactions

Transactions may seem to be slow, but eXtreme Scale uses transactions for three reasons:

  1. To allow rollback of changes if an exception occurs or business logic needs to undo state changes.

  2. To hold locks on data and release locks within the lifetime of a transaction, allowing a set of changes to be made atomically, that is, all changes or no changes to data.

  3. To produce an atomic unit of replication.

WebSphere eXtreme Scale 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 strategy 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 are copied when accessed by the transaction . The application can specify how objects are copied with the ObjectMap.setCopyMode method. With this method, you can turn off CopyMode. Turning off CopyMode is normally used for read-only transactions if different values can be returned for the same object within a transaction. Different values can be returned for the same object within a transaction.

For example, if the transaction called the ObjectMap.get method for the object at T1, it got the value at that point in time. If it calls the get method again within that transaction at a later time T2, another thread might have changed the value. Because the value has been changed by another thread, the application sees a different value. If the application modifies an object retrieved using a NONE CopyMode value, it is changing the committed copy of that object directly. Rolling back the transaction has no meaning in this mode. You are changing the only copy in the ObjectGrid. Although using the NONE CopyMode is fast, be aware of its consequences. An application that uses a NONE CopyMode must never roll back the transaction. If the application rolls back the transaction, the indexes are not updated with the changes and the changes are not replicated if replication is turned on. The default values are easy to use and less prone to errors. If you start trading performance in exchange for less reliable data, the application needs to be aware of what it is doing to avoid unintended problems.

CAUTION:

Be careful when you are changing either the locking or the CopyMode values. If you change the values, unpredictable application behavior will occur.


Interacting with stored data

After a session has been obtained, you can use the following code fragment to use 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();

The same example using the EntityManager API follows. This code sample assumes that the Person object is mapped to an Entity. 

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

The pattern is designed to obtain references to the ObjectMaps for the Maps that the thread will work with, start a transaction, work with the data, then commit the transaction.

The ObjectMap interface has the typical Map operations such as put, get and remove. However, use the more specific operation names such as: get, getForUpdate, insert, update and remove. These method names convey the intent more precisely that the traditional Map APIs.

You can also use the indexing support, which is flexible.

The following 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();

The application normally uses 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. The following is the same fragment using the EntityManager API: 

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

The EntityManager API is simpler than the Map approach. In this case, eXtreme Scale finds the Entity and returns a managed object to the application. The application modifies the object and commits the transaction, and eXtreme Scale tracks changes to managed objects automatically at commit time and performs the necessary updates.


Transactions and partitions

WebSphere eXtreme Scale transactions can only update a single partition. Transactions from a client can read from multiple partitions, but they can only update one partition. If an application attempts to update two partitions, then the transaction fails and is rolled back. A transaction that is using an embedded ObjectGrid (grid logic) has no routing capability and can only see data in the local partition. This business logic can always get a second session that is a true client session to access other partitions. However, this transaction would be an independent transaction.


Queries and partitions

If a transaction has already searched for an Entity, the transaction is associated with the partition for that Entity. Any queries that run on a transaction that is associated with an Entity are routed to the associated partition.

If a query is run on a transaction before it is associated with a partition, set the partition ID to use for the query. The partition ID is an integer value. The query is then routed to that partition.

Queries only search within a single partition. However, you can use the DataGrid APIs to run the same query in parallel on all partitions or a subset of partitions. Use the DataGrid APIs to find an entry that might be in any partition.

[v7 iFix 2+] The REST data service allows any HTTP client to access a WebSphere eXtreme Scale grid, and is compatible with WCF Data Services in the Microsoft .NET Framework 3.5 SP1. For more information see the user guide for the eXtreme Scale REST data service .


+

Search Tips   |   Advanced Search