Program guide > Access data with client applications



Retrive entities and objects (Query API)

WebSphere eXtreme Scale provides a flexible query engine for retrieving entities using the EntityManager API and Java™ objects using the ObjectQuery API.


WebSphere eXtreme Scale query capabilities

With the eXtreme Scale query engine, you can perform SELECT type queries over an entity or object-based schema using the eXtreme Scale query language.

This query language provides the following capabilities:


Query interface

Use the query interface to control entity query execution.

Use the EntityManager.createQuery(String) method to create a Query. Use each query instance multiple times with the EntityManager instance in which it was retrieved.

Each query result produces an entity, where the entity key is the row ID (of type long) and the entity value contains the field results of the SELECT clause. Use each query result in subsequent queries.

The following methods are available on the com.ibm.websphere.objectgrid.em.Query interface.


public ObjectMap getResultMap()

The getResultMap method runs a SELECT query and returns the results in an ObjectMap object with the results in query-specified order. The resulting ObjectMap is valid only for the current transaction.

The map key is the result number, of type long, starting at 1. The map value is of type com.ibm.websphere.projector.Tuple where each attribute and association is named based on its ordinal position within the select clause of the query. Use the method to retrieve the EntityMetadata for the Tuple object that is stored within the map.

The getResultMap method is the fastest method for retrieving query result data where multiple results can exist. You can retrieve the name of the resulting entity using the ObjectMap.getEntityMetadata() and EntityMetadata.getName() methods.

Example: The following query returns two rows. 

String ql = SELECT e.name, e.id, d from Employee e join e.dept d WHERE d.number=5
 Query q = em.createQuery(ql);
 ObjectMap resultMap = q.getResultMap();
 long rowID = 1; // starts with index 1
 Tuple tResult = (Tuple) resultMap.get(new Long(rowID));
 while(tResult != null) {
     // The first attribute is name and has an attribute name of 1
     // But has an ordinal position of 0.
     String name = (String)tResult.getAttribute(0);
     Integer id = (String)tResult.getAttribute(1);

     // Dept is an association with a name of 3, but
     // an ordinal position of 0 since it's the first association.
     // The association is always a OneToOne relationship,
     // so there is only one key.
     Tuple deptKey = tResult.getAssociation(0,0);
     ...
     ++rowID;
     tResult = (Tuple) resultMap.get(new Long(rowID));

 }


public Iterator getResultIterator

The getResultIterator method runs a SELECT query and returns the query results using an Iterator where each result is either an Object for a single-valued query, or an Object array for a multiple-valued query. The values in the Object[] result are stored in query order. The result Iterator is valid for the current transaction only.

This method is preferred for retrieving query results within the EntityManager context. Use the optional setResultEntityName(String) method to name the resulting entity so that it can be used in further queries.

Example: The following query returns two rows. 

String ql = SELECT e.name, e.id, e.dept from Employee e WHERE e.dept.number=5
 Query q = em.createQuery(ql);
 Iterator results = q.getResultIterator();
 while(results.hasNext()) {
     Object[] curEmp = (Object[]) results.next();
     String name = (String) curEmp[0];
     Integer id = (Integer) curEmp[1];
     Dept d = (Dept) curEmp[2];
     ...
 }


public Iterator getResultIterator(Class resultType)

The getResultIterator(Class resultType) method runs a SELECT query and returns the query results using an entity Iterator. The entity type is determined by the resultType parameter. The result Iterator is valid only for the current transaction.

Use this method when to use the EntityManager APIs to access the resulting entities.

Example: The following query returns all of the employees and the department to which they belong for one division, ordering by salary.

To print out the five employees with the highest salaries and then select work with employees from only one department in the same working set, use the following code. 

String string_ql = "SELECT e.name, e.id, e.dept from Employee e WHERE
        e.dept.division='Manufacturing' ORDER BY e.salary DESC";
Query query1 = em.createQuery(string_ql);
query1.setResultEntityName("AllEmployees");
Iterator results1 = query1.getResultIterator(EmployeeResult.class);
int curEmployee = 0;
System.out.println("Highest paid employees");
while (results1.hasNext() && curEmployee++
< 5) {
    EmployeeResult curEmp = (EmployeeResult) results1.next();            
    System.out.println(curEmp);
    // Remove the employee from the resultset.
    em.remove(curEmp);
}

// Flush the changes to the result map.
em.flush();

// Run a query against the local working set without the employees we
// removed
String string_q2 = "SELECT e.name, e.id, e.dept from AllEmployees e
        WHERE e.dept.name='Hardware'";
Query query2 = em.createQuery(string_q2);
Iterator results2 = query2.getResultIterator(EmployeeResult.class);
System.out.println("Subset list of Employees");
while (results2.hasNext()) {
    EmployeeResult curEmp = (EmployeeResult) results2.next();            
    System.out.println(curEmp);
}


public Object getSingleResult

The getSingleResult method runs a SELECT query that returns a single result.

If the SELECT clause has more than one field defined, then the result is an object array, where each element in the array is based on its ordinal position within the SELECT clause of the query. 

String ql = SELECT e from Employee e WHERE e.id=100"
 Employee e = em.createQuery(ql).getSingleResult();

 String ql = SELECT e.name, e.dept from Employee e WHERE e.id=100"
 Object[] empData = em.createQuery(ql).getSingleResult();
 String empName= (String) empData[0];
 Department empDept = (Department) empData[1];


public Query setResultEntityName(String entityName)

The setResultEntityName(String entityName) method specifies the name of the query result entity.

Each time the getResultIterator or getResultMap methods are invoked, an entity with an ObjectMap is dynamically created to hold the results of the query. If the entity is not specified, or null, the entity and ObjectMap name are automatically generated.

Because all query results are available for the duration of a transaction, a query name cannot be reused in a single transaction.


public Query setPartition(int partitionId)

Set the partition to where the query routes.

This method is required if the maps in the query are partitioned and if the entity manager does not have affinity to a single schema root entity partition.

Use the PartitionManager Interface to determine the number of partitions for the backing map of a given entity.

The following table provides descriptions of the other methods that are available through the query interface.

Table 1. Other methods.
Method Result
public Query setMaxResults(int maxResult) Set the maximum number of results to retrieve.
public Query setFirstResult(int startPosition) Set the position of the first result to retrieve.
public Query setParameter(String name, Object value) Bind an argument to a named parameter.
public Query setParameter(int position, Object value) Bind an argument to a positional parameter.
public Query setFlushMode(FlushModeType flushMode) Set the flush mode type to be used when the query runs, overriding the flush mode type set on the EntityManager.


eXtreme Scale query elements

With the eXtreme Scale query engine, you can use a single query language for searching the eXtreme Scale cache. This query language can query Java objects that are stored in ObjectMap objects and Entity objects. Use the following syntax for creating a query string.

An eXtreme Scale query is a string that contains the following elements:

Collections of Java objects are identified in queries through the use of their name in the query FROM clause.

The elements of query language are discussed in more detail in the following related topics:

The following topics describe the means to use the Query API:


Parent topic:

Access data with client applications


Related concepts

ObjectGrid interface

BackMap interface

Interacting with an ObjectGrid using ObjectGridManager

Data access with indexes (Index API)

Access data in WebSphere eXtreme Scale

Use Sessions to access data in the grid

Cache objects with no relationships involved (ObjectMap API)

Cache objects and their relationships (EntityManager API)

Configure clients with WebSphere eXtreme Scale


Related tasks

Program for transactions

Related reference

Connect to a distributed ObjectGrid


+

Search Tips   |   Advanced Search