WebSphere eXtreme Scale Programming Guide > Access data in WebSphere eXtreme Scale > Query API
|
| |
Use the ObjectQuery API
The ObjectQuery API provides methods for querying data in the ObjectGrid that is stored using the ObjectMap API. When a schema is defined in the ObjectGrid instance, the ObjectQuery API can be used to create and run queries over the heterogeneous objects stored in the object maps.
Query and object maps
You can use an enhanced query capability for objects that are stored using the ObjectMap API. These queries allow retrieval of objects using non-key attributes and performs simple aggregations such as sum, avg, min, and max against all the data that matches a query. Applications can construct a query using the Session.createObjectQuery method. This method returns an ObjectQuery object which can then be interrogated to obtain the query results. The query object also allows the query to be customized before running the query. The query is run automatically when any method returning the result is called.
Figure 1. The interaction of the query with the ObjectGrid object maps and how a schema is defined for classes and associated with an ObjectGrid map
Define an ObjectMap schema
Object maps are used to store objects in various forms and are largely unaware of the format. A schema must be defined in the ObjectGrid that defines the format of the data. A schema is composed of the following pieces:
- The type of object stored in the ObjectMap
- Relationships between ObjectMaps
- The method for which each query should access the data attributes in the objects (fields or property methods)
- The primary key attribute name in the object.
See Configure an ObjectQuery schema for details.
For an example on creating a schema programmatically or using the ObjectGrid descriptor XML file, see ObjectQuery tutorial.
Query objects with the ObjectQuery API
The ObjectQuery interface allows the querying of non-entity objects, which are heterogeneous objects that are stored directly in the ObjectGrid ObjectMaps. The ObjectQuery API provides an easy way to find ObjectMap objects without using the keyword and index mechanisms directly.
There are two methods for retrieving results from an ObjectQuery: getResultIterator and getResultMap.
Retrive query results using getResultIterator
Query results are basically a list of attributes. Suppose the query was select a,b,c from X where y=z. This query returns a list of rows containing a, b and c. This list is actually stored in a transaction scoped Map, which means that associate an artificial key with each row and use an integer that increases with each row. This map is obtained using the ObjectQuery.getResultMap() method. You can access the elements of each row using code similar to the following:
ObjectQuery q = session.createQuery(
"select c.id, c.firstName, c.surname from Customer c where c.surname=?1");
q.setParameter(1, "Claus");
Iterator iter = q.getResultIterator();
while(iter.hasNext())
{
Object[] row = (Object[])iter.next();
System.out.println("Found a Claus with id "
+ row[objectgrid: 0 ] + ", firstName: "
+ row[objectgrid: 1 ] + ", surname: "
+ row[objectgrid: 2 ]);
}
Retrive query results using getResultMap
Query results can also be retrieved using the result map directly. The following example shows a query retrieving specific parts of the matching Customers and demonstrates how to access the resulting rows. Notice that if you use the ObjectQuery object to access the data, then the generated long row identifier is hidden. The long row is only visible when using the ObjectMap to access the result.
When the transaction is completed this map disappears. The map is also only visible to the session used, that is, normally to just the thread that created it. The map uses a key of type Long which represents the row ID. The values stored in the map either are of type Object or Object[], where each element matches the type of the element in the select clause of query.
ObjectQuery q = em.createQuery(
"select c.id, c.firstName, c.surname from Customer c where c.surname=?1");
q.setParameter(1, "Claus");
ObjectMap qmap = q.getResultMap();
for(long rowId = 0; true; ++rowId)
{
Object[] row = (Object[]) qmap.get(new Long(rowId));
if(row == null) break;
System.out.println(" I Found a Claus with id " + row[0]
+ ", firstName: " + row[1]
+ ", surname: " + row[2]);
}
For examples on using the ObjectQuery, see ObjectQuery tutorial.
- Configure an ObjectQuery schema
ObjectQuery relies on schema or shape information to perform semantic checking and to evaluate path expressions. This section describes how to define the schema in XML or programmatically.