com.ibm.websphere.objectgrid.em
Interface Query

public interface Query

Interface used to control entity query execution.

Use the EntityManager.createQuery(String) method to create a Query. Each query instance can be used multiple times using the EntityManager 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. Each query result can be included in subsequent queries.

Since:

WAS XD 6.1

See Also:

EntityManager

Field Summary

static String

HINT_USEINDEX Hint to the query engine to use the specified index.

Method Summary

String	getPlan() Return a string representation of the query plan.
Iterator	getResultIterator() Execute a SELECT query and return the query results using an Iterator where each result is either an Object (for a single valued query) or Object[] (for a multiple valued query).
Iterator	getResultIterator(Class resultType) Execute a SELECT query and return the query results using an entity Iterator where the entity type is determined by the resultType parameter.
ObjectMap	getResultMap() Execute a SELECT query and return the query results in an ObjectMap with the results in query-specified order.
Object	getSingleResult() Execute a SELECT query that returns a single result.
Query	setFirstResult(int startPosition) Set the position of the first result to retrieve.
Query	setFlushMode(FlushModeType flushMode) Set the flush mode type to be used when the query is executed, overriding the flush mode type set on the EntityManager.
Query	setForUpdate(boolean forUpdate) Set the update intent for the query.
Query	setHint(String hintName, Object value) Set a query hint.
Query	setMaxResults(int maxResult) Set the maximum number of results to retrieve.
Query	setParameter(int position, Object value) Bind an argument to a positional parameter.
Query	setParameter(String name, Object value) Bind an argument to a named parameter.
Query	setPartition(int partitionId) Set the partition to route the query to.
Query	setResultEntityName(String entityName) Specify the name of the query result entity.

Field Detail

HINT_USEINDEX

static final String HINT_USEINDEX

Hint to the query engine to use the specified index.

String Format:

 <IndexHint>     ::= <Entity Name> "." <AttributeName>
 <Entity Name>   ::= ObjectGrid entity name
 <AttributeName> ::= An indexed attribute.
 

Example:

 Query q = em.createQuery("SELECT p FROM Person p WHERE p.name=?1 AND p.city=?2 AND p.state=?3");
 q.setHint(Query.HINT_USEINDEX, "Person.city");
 q.setParameter(1, "Smith");
 q.setParameter(2, "Rochester");
 q.setParameter(3, "MN");
 Iterator it = q.getResultIterator();
 

Since:

WAS XD 6.1.0.4

See Also:

setHint(String, Object), Constant Field Values

Method Detail

getResultMap

ObjectMap getResultMap()

Execute a SELECT query and return the query results in an ObjectMap with the results in query-specified order. The result ObjectMap is only valid only for the current transaction.

The map key is the result number (of type long) starting at 0.

The map value is of type Tuple where each attribute and association is named based on it's ordinal position within the query's select clause. Use the ObjectMap.getEntityMetadata() method to retrieve the EntityMetadata for the Tuple object stored within the map.

This method is the fastest method for retrieving query result data where there can be multiple results. The name of the resulting entity can be retrieved using the ObjectMap.getEntityMetadata() and EntityMetadata.getName() methods.

Example:
The following query returns 2 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=0;
 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));
     ...
 }
 

Returns:

an ObjectMap that contains the results of the query.

Throws:

PersistenceException - thrown if query validation fails. This exception may be deferred until the query is run.

getResultIterator

Iterator getResultIterator()

Execute a SELECT query and return the query results using an Iterator where each result is either an Object (for a single valued query) or Object[] (for a multiple valued query). The values in the Object[] result are stored in query order. The result Iterator is valid only for the current transaction.

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

Example:
The following query returns 2 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];
     ...
 }
 

Returns:

an Iterator with the query results in the form of Object or Object[]

Throws:

PersistenceException - thrown if query validation fails. This exception may be deferred until the query is run.

TransactionRequiredException - if invoked without an active transaction.

getResultIterator

Iterator getResultIterator(Class resultType)

Execute a SELECT query and return the query results using an entity Iterator where the entity type is determined by the resultType parameter. The result Iterator is valid only for the current transaction.

Use this method when it is desirable to use the EntityManager APIs to access the resulting entities. Example:
The following query returns all of the employees and the department they belong to for one division, ordering by salary. We want to print out the 5 employees with the highest salaries and then select work with employees from only one department in the same working set:

 em.getTransaction().begin();

 String ql = SELECT e.name, e.id, e.dept from Employee e WHERE e.dept.division='Manufacturing' ORDER BY e.salary DESC
 Query q = em.createQuery(ql);
 q.setResultEntityName("AllEmployees");
 Iterator results = q.getResultIterator(EmployeeResult.class);
 int curEmployee=0;
 while(results.hasNext() && curEmployee++ < 5) {
     EmployeeResult curEmp = (EmployeeResult) results.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 ql = SELECT e.name, e.id, e.dept from AllEmployees e WHERE e.dept.name="Hardware""
 Query q = em.createQuery(ql);
 Iterator results = q.getResultIterator(EmployeeResult.class);
 while(results.hasNext()) {
     EmployeeResult curEmp = (EmployeeResult) results.next();
     System.out.println(curEmp);
 }


 @Entity
 public class EmployeeResult {
     String name;
     Integer id;
     @ManyToOne
     Dept dept;

     public String toString() {
        return "Name=" + name + ", ID=" + id + ", Department=" + dept.name();
     }
 }

 

Parameters:

resultType - the type of object to convert the results into.

Returns:

an Iterator that contains the results of the query.

Throws:

PersistenceException - thrown if query validation fails. This exception may be deferred until the query is run.

TransactionRequiredException - if invoked without an active transaction.

getSingleResult

Object getSingleResult()

Execute a SELECT query that returns a single result.

If the SELECT clause has more than one field defined, then the result will be a Object[] where each element in the object array is based on it's ordinal position within the query's select clause.

 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];
 

Returns:

the result Object or array of Objects

Throws:

NoResultException - if there is no result

NonUniqueResultException - if more than one result

PersistenceException - thrown if query validation fails

setMaxResults

Query setMaxResults(int maxResult)

Set the maximum number of results to retrieve.

Parameters:

maxResult - the maximum number of results to retrieve.

Returns:

the same query instance

Throws:

IllegalArgumentException - if argument is negative

setFirstResult

Query setFirstResult(int startPosition)

Set the position of the first result to retrieve.

Parameters:

startPosition - position of the first result, numbered from 0

Returns:

the same query instance

Throws:

IllegalArgumentException - if argument is negative

setResultEntityName

Query setResultEntityName(String entityName)

Specify the name of the query result entity.

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

Since all query results are available for the duration of a transaction, a query name may not be reused in a single transaction.

Parameters:

entityName - the name of the entity

Returns:

the same query instance

setHint

Query setHint(String hintName,
              Object value)

Set a query hint. If the hint name is not recognized, it is silently ignored.

Parameters:

hintName - the name of the hint. See the constant values defined in this interface.

value - the value of the hint.

Returns:

the same query instance

Throws:

IllegalArgumentException - thrown if the second argument is not valid for the hint. This exception may be deferred until the query is run.

Since:

WAS XD 6.1.0.4

setParameter

Query setParameter(String name,
                   Object value)

Bind an argument to a named parameter.

Parameters:

name - the parameter name

value - the value of the parameter.

Returns:

the same query instance

Throws:

IllegalArgumentException - if parameter name does not correspond to parameter in query string or argument is of incorrect type. This exception may be deferred until the query is run.

setParameter

Query setParameter(int position,
                   Object value)

Bind an argument to a positional parameter.

Parameters:

position - the position of the parameter. The first parameter is 1.

value - the value of the parameter.

Returns:

the same query instance

Throws:

IllegalArgumentException - if position does not correspond to positional parameter of query or argument is of incorrect typel This exception may be deferred until the query is run.

setFlushMode

Query setFlushMode(FlushModeType flushMode)

Set the flush mode type to be used when the query is executed, overriding the flush mode type set on the EntityManager.

Parameters:

flushMode - the FlushModeType to set for this query instance.

Returns:

the same query instance

setPartition

Query setPartition(int partitionId)

Set the partition to route the query to.

Required if the maps in the query are partitioned and the EntityManager does not have affinity to a single schema root entity's partition.

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

Parameters:

partitionId - the partition to route the query to.

Returns:

the same query instance

setForUpdate

Query setForUpdate(boolean forUpdate)

Set the update intent for the query. If set to true, subsequent query executions will lock records appropriately for updating.

If not set, the default is false.

Parameters:

forUpdate - if true, lock records for update.

Returns:

the same query instance

Since:

WAS XD 6.1.0.1

getPlan

String getPlan()

Return a string representation of the query plan.

This method can be used to explain the plan of a query without running the query. The plan describes when an entity is to be scanned, an index used and the order in which the entities are accessed.

Returns:

a string representation of the query plan.

Throws:

PersistenceException - thrown if query validation fails. The transaction will not be marked to rollback.

Since:

WAS XD 6.1.0.3