com.ibm.websphere.objectgrid.em
Interface QueryQueue

public interface QueryQueue

A query queue allows users to get entities qualified by a query in an iterative manner. A query queue is similar to a query. It contains a query string, and named parameters or positioned parameters. However, it gets the results in an iterative manner. In a client server environment, retrieval of entities to the client is triggered by the getNextEntity(long) or getNextEntities(int, long) method calls. A timeout value (in milliseconds) can be used in these two methods to indicate the timeout value. Therefore, the user will not wait forever.

Setting parameters on the QueryQueue object can only be done before the getNextEntity(long) or getNextEntities(int, long) method is called. A query queue is uniquely identified by the query string and the parameters. You cannot dynamic change the parameters for a query queue like you can do with a query.

A partition indicates where the the query must be routed to in a distributed environment. If the partition id is not specified, the QueryQueue will be routed to all partitions, starting from a random partition.

For example, the following code get the next Task entity for a specific task type and status. After the task is read, we assign it to an agent, changing the status to STATUS_ASSIGNED, which removes it from the result set:

 QueryQueue queue = em.createQueryQueue("SELECT t FROM Tasks t WHERE t.type=?1 AND t.status=?2", Task.class);
 queue.setParameter(1, TYPE_SALES_QUESTION);
 queue.setParameter(2, STATUS_UNASSIGNED);

 EntityTransaction tran = em.getTransaction();
 tran.begin();
 Task nextTask = (Task) queue.getNextEntity(10000);
 if (nextTask != null) {
     // Change the status of the task, assign to an agent.
     assignTask(task);
 }
 tran.commit();

 

In this example, the entity returned is of Task type. An entity class is used to specify which class the result(s) will be projected to. The specified entity class must have the same entity name as specified in the query string. If a null value is used as the entity class, then the result will not be projected; the key Tuple(s) will be returned.

For the same example, you can use an subset entity type, such as SubTask, to get a subset entity (an entity class with a subset of the attributes of the actual entity), or you can use null to get the key Tuple(s).

Since:

WAS XD 6.1 FIX3

See Also:

Tuple

Field Summary

static long	TIMEOUT_INFINITE Used as a parameter on the getNextEntity(long) or getNextEntity(long) method.
static long	TIMEOUT_NONE Used as a parameter on the getNextEntity(long) or getNextEntity(long) method.

Method Summary

Object[]	getNextEntities(int numEntities, long timeout) Get the next batch of entities.
Object	getNextEntity(long timeout) Get the next entity.
QueryQueue	setParameter(int position, Object value) Bind an argument to a positional parameter.
QueryQueue	setParameter(String name, Object value) Bind an argument to a named parameter.
QueryQueue	setPartition(int partitionId) Set the partition to route the QueryQueue to.

Field Detail

TIMEOUT_NONE

static final long TIMEOUT_NONE

Used as a parameter on the getNextEntity(long) or getNextEntity(long) method. It specifies the method should not block.

See Also:

Constant Field Values

TIMEOUT_INFINITE

static final long TIMEOUT_INFINITE

Used as a parameter on the getNextEntity(long) or getNextEntity(long) method. It specifies the method should block until an entity becomes available.

See Also:

Constant Field Values

Method Detail

setParameter

QueryQueue 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 QueryQueue 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 QueryQueue is run.

IllegalStateException - if this method is called after the getNextEntity(long) or getNextEntities(int, long) method is called.

setParameter

QueryQueue 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 QueryQueue 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 QueryQueue is run.

IllegalStateException - if this method is called after the getNextEntity(long) or getNextEntities(int, long) method is called.

setPartition

QueryQueue setPartition(int partitionId)

Set the partition to route the QueryQueue to.

Required if the maps in the QueryQueue 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.

The default partition ID for a QueryQueue is -1, which means the query is sent to all partitions.

Parameters:

partitionId - the partition to route the QueryQueue to.

Returns:

the same QueryQueue instance

getNextEntity

Object getNextEntity(long timeout)
                     throws ObjectGridException

Get the next entity.

Parameters:

timeout - the timeout value for this method call. The method will return after the specified time. If the value is set to TIMEOUT_INFINITE. it will wait until an entity is retrieved. If the value is set to TIMEOUT_NONE, it will not wait.

Returns:

the next entity. null if there is no entity matched with the query queue.

Throws:

ObjectGridException

See Also:

TIMEOUT_NONE, TIMEOUT_INFINITE

getNextEntities

Object[] getNextEntities(int numEntities,
                         long timeout)
                         throws ObjectGridException

Get the next batch of entities. The number in this batch is specified by the parameter numEntities.

The parameter numEntities is just a hint. It does not guarantee that the actual number of returned entities. For example, if numEntities is 10, and there are only 5 matched entities left in one partition, the number of returned entities will be 5. However, it does guarantee that the number of returned entities will never exceed the specified number. If there is no matched entity, an empty array will be returned.

Parameters:

numEntities - the number of entities to return

timeout - the timeout value for this method call. The method will return after the specified time. If the value is set to TIMEOUT_INFINITE. it will wait until an entity is retrieved. If the value is set to TIMEOUT_NONE, it will not wait.

Returns:

an array of entities. An 0-length array will be returned if there is no entity matched with the QueryQueue query.

Throws:

ObjectGridException

See Also:

TIMEOUT_NONE, TIMEOUT_INFINITE