com.ibm.websphere.objectgrid.query
Interface ObjectQuery

public interface ObjectQuery

An ObjectQuery provides a mechanism for introspecting one or more ObjectMaps using standard ObjectGrid query language syntax. ObjectQuery instances are retrieved using the Session.createObjectQuery(String) method and are valid for the session and inherits the session's current state. For example, if the session has a transaction active, the ObjectQuery.getResultMap() method will participate in that transaction.

Since:

WAS XD 6.1

See Also:

Session.createObjectQuery(String)

Nested Class Summary

static class

ObjectQuery.ResultType The result type indicates when the query engine will return the cached objects results in their native Object form or in the RAW form.

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 in an Iterator where each result is either an Object (for a single valued query) or Object[] (for a multiple valued query).
ObjectMap	getResultMap() Execute a SELECT query and return the query results in an ObjectMap with the results in query-specified order.
ObjectQuery.ResultType	getResultType() Return the current ResultType for the ObjectQuery.
Object	getSingleResult() Execute a SELECT query that returns a single result.
ObjectQuery	setFirstResult(int startPosition) Set the position of the first result to retrieve.
ObjectQuery	setForUpdate(boolean forUpdate) Set the update intent for the query.
ObjectQuery	setHint(String hintName, Object value) Set a query hint.
ObjectQuery	setMaxResults(int maxResults) Set the maximum number of results to retrieve.
ObjectQuery	setParameter(int position, Object value) Bind an argument to a positional parameter.
ObjectQuery	setParameter(String name, Object value) Bind an argument to a named parameter.
ObjectQuery	setPartition(int partitionId) Set the partition to route the query to.
ObjectQuery	setResultMapName(String resultMapName) The map to insert the results into.
void	setResultType(ObjectQuery.ResultType type) Set the ObjectQuery.ResultType for a query using an ObjectMap that is configured with a KeySerializerPlugin or ValueSerializerPlugin.

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 map name
 <AttributeName> ::= An indexed attribute.
 

Example:

 ObjectQuery q = session.createObjectQuery("SELECT p FROM Person p WHERE p.name=?1 AND p.city=?2 AND p.state=?3");
 q.setHint(ObjectQuery.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

setResultType

void setResultType(ObjectQuery.ResultType type)

Set the ObjectQuery.ResultType for a query using an ObjectMap that is configured with a KeySerializerPlugin or ValueSerializerPlugin. The keys and values objects returned from the query will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

Attribute objects returned from the query will be in their native format even if the RAW result type is set. Example:

 ObjectQuery q = session.createObjectQuery("SELECT p FROM Person p WHERE p.name=?1 AND p.city=?2 AND p.state=?3");
 q.setResultType(ObjectQuery.ResultType.RAW);
 q.setParameter(1, "Smith");
 q.setParameter(2, "Rochester");
 q.setParameter(3, "MN");
 Iterator it = q.getResultIterator();
 while (it.hasNext()) {
      Person p = ((SerializedValue)it.next()).getObject();
 }
 

Parameters:

type - the type of object to return when returning cache objects.

getResultType

ObjectQuery.ResultType getResultType()

Return the current ResultType for the ObjectQuery.

Returns:

the current ResultType for the ObjectQuery.

getResultMap

ObjectMap getResultMap()

Execute a SELECT query and return the query results in an ObjectMap with the results in query-specified order. The 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 Object[] where each element in the object array is based on it's ordinal position within the query's select clause.

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";
 ObjectQuery q = createObjectQuery(ql);
 ObjectMap resultMap = q.getResultMap();
 Object oResult = (Object[]) resultMap.get(new Long(0));
 while(oResult != null) {
     // The first attribute is name and has an ordinal position of 0.
     String name = (String) oResult[0];
     Integer id = (Integer) oResult[1];
     Dept d = (Dept) oResult[2];
     ...
 }
 

Returns:

an ObjectMap that contains the results of the query.

Throws:

ObjectQueryException - thrown if query validation fails or if there is no active transaction. The resulting transaction will be marked to rollback.

getResultIterator

Iterator getResultIterator()

Execute a SELECT query and return the query results in 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 Iterator is only valid only for the current transaction.

Example:
The following query returns 2 rows:

 String ql = "SELECT e.name, e.id, e from Employee e WHERE e.dept.number=5";
 ObjectQuery q = session.createObjectQuery(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:

ObjectQueryException - thrown if query validation fails or if there is no active transaction. The resulting transaction will be marked to rollback.

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 of type 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 = (Employee) session.createObjectQuery(ql).getSingleResult();

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

Returns:

the result

Throws:

NoResultException - if there is no result

NonUniqueResultException - if more than one result

ObjectQueryException - thrown if query validation fails. The resulting transaction will be marked to rollback.

setMaxResults

ObjectQuery setMaxResults(int maxResults)

Set the maximum number of results to retrieve.

Parameters:

maxResults - the maximum number of results to retrieve.

Returns:

the same ObjectQuery instance

Throws:

IllegalArgumentException - if the argument is negative

setFirstResult

ObjectQuery 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 ObjectQuery instance

Throws:

IllegalArgumentException - if the argument is negative

setResultMapName

ObjectQuery setResultMapName(String resultMapName)

The map to insert the results into. If not specified or is null, the map name is undefined.

If the result map name is specified and the map already exists, the query will fail.

Parameters:

resultMapName - the name of the ObjectMap to insert the query results into.

Returns:

the same ObjectQuery instance

setHint

ObjectQuery 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

ObjectQuery 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 ObjectQuery 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

ObjectQuery 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 ObjectQuery instance

Throws:

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

setPartition

ObjectQuery setPartition(int partitionId)

Set the partition to route the query to.

The partition id is required if the maps in the query are partitioned and the Session commit strategy is set to LOCAL.

Use the PartitionManager to determine the number of partitions for a given backing map and to calculate the partition number from an object.

Parameters:

partitionId - the partition to route the query to.

Returns:

the same ObjectQuery instance

setForUpdate

ObjectQuery 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 ObjectQuery 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 a map is to be scanned, an index used and the order in which the maps are accessed.

Returns:

a string representation of the query plan.

Throws:

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

Since:

WAS XD 6.1.0.3