com.edustructures.sifworks
Class TrackQueryResults

java.lang.Object
  com.edustructures.sifworks.impl.TrackQueryResultsImpl
      com.edustructures.sifworks.TrackQueryResults

All Implemented Interfaces:

QueryResults

public class TrackQueryResults
extends com.edustructures.sifworks.impl.TrackQueryResultsImpl

Synchronously issues one or more SIF Requests to a zone or topic and returns the results to the calling thread as they are received.

TrackQueryResults differs from normal (asynchonous) SIF Request and Response message handling in that responses are not dispatched to the usual QueryResults objects in the message dispatching chain. Rather, they are delvered directly to this class and returned to the calling thread by the next method. The calling thread is blocked when waitForResults is called for synchronous SIF Request processing.

When to Use

TrackQueryResults should be used when:

• Your agent needs to request one or more objects from a zone before proceeding with the current operation. In this case, a synchronous method of SIF Request and Response processing is ideal because the current thread can block until the query has completed, avoiding complex asynchronous interactions in your code. If results are not received in the specified period of time, the agent can timeout and abandon the operation in progress.
  
  
• Your agent needs to query a zone for objects while handling a SIF Event message. In this case, Selective Message Blocking is automatically invoked by the TrackQueryResults constructor. (Refer to the SIF Specification for more information on Selective Message Blocking.) Note: When the Agent Local Queue (ALQ) is enabled, Selective Message Blocking is not necessary. The ADK will dispatch messages from the local queue regardless. However, to ensure your code works properly even when the local queue is disabled, we suggest always using the TrackQueryResults class when sending SIF Requests during SIF Event handling.
  
  

How to Use

Follow these steps to use TrackQueryResults:

• Create an instance of the TrackQueryResults class. If your code is processing a SIF Event message from the Subscriber.onEvent method, pass the Event object to the constructor. This will invoke Selective Message Blocking on the event to prevent a deadlock condition at the Zone Integration Server.
  
  TrackQueryResult tqr = new TrackQueryResults();

  
• Call the addQuery method one or more times to specify the queries the TrackQueryResults object will issue. If you add more than one query, keep in mind the results may not be received in the same order as the queries were issued.
  
  // Query for a SchoolInfo object by RefId
SIFDTD dtd = ADK.DTD();
Query query = new Query( dtd.SCHOOLINFO );
query.addCondition( dtd.SCHOOLINFO_REFID, Condition.EQ, refId );
Topic schoolInfo = getTopicFactory().getInstance( dtd.SCHOOLINFO );

// Add the query to TrackQueryResults
tqr.addQuery( schoolInfoTopic, query );

  
• Create a loop that calls the waitForResults, available, and next methods as illustrated below to wait for and retrieve the results of all queries. The outermost waitForResults loop blocks until at least one result is available, all queries have completed (i.e. the last packet of each SIF_Response message has been received), or the timeout period has expired. The inner available method does not block.
  
  // Timeout if results are not received in 30 seconds...
while( tqr.waitForResults( 30000 ) )
{
// Retrieve all messages so far
while( tqr.available() )
{
SIFDataObject[] data = tqr.next();
for( int i = 0; i < data.length; i++ )
{
// Process the SIF Data Objects received...
}
}
}

  
  

TrackQueryResultsData

When TrackQueryResults receives a SIF Response message, it captures not only the SIF Data Objects provided by that message, but also the zone from which the message was received and the associated SIFMessageInfo object, which includes header fields and optionally the XML content of the message. TrackQueryResults packages this data to the caller by returning an instance of the TrackQueryResultsData class.

Version:

ADK 1.0

Nested Class Summary

Nested classes/interfaces inherited from class com.edustructures.sifworks.impl.TrackQueryResultsImpl

com.edustructures.sifworks.impl.TrackQueryResultsImpl.QueryWrapper

Constructor Summary

TrackQueryResults()
Constructs a TrackQueryResults object to be used when the agent is not processing a SIF_Event message.

TrackQueryResults(Event event, MessageInfo msgInfo)
Constructs a TrackQueryResults object to be used when the agent needs to query for additional data while processing a SIF_Event message.

Method Summary

void	addQuery(Topic topic, Query query) Add a query to be executed when the waitForResults method is called.
void	addQuery(Topic topic, Query query, java.lang.String destinationId) Add a query to be executed when the waitForResults method is called.
void	addQuery(Zone zone, Query query) Add a query to be executed when the waitForResults method is called
void	addQuery(Zone zone, Query query, java.lang.String destinationId) Add a query to be executed when the waitForResults method is called
int	available() Returns the number of results currently available
ADKException[]	getErrors() Gets any SIF_Request errors received when the queries were executed.
boolean	hasErrors() Determines if any SIF_Request errors occurred when the queries were executed.
boolean	hasNext() Determines if any results will be returned by the next method
boolean	isComplete() Have all requests been received?
TrackQueryResultsData	next() Returns the next group of result data, or null if no data is available.
void	setQueryOptions(int queryOptions) Sets optional query options
boolean	waitForResults(int timeout) Sends a SIF_Request message for each Query passed to the addQuery method and resets the timeout period to the given value.

Methods inherited from class com.edustructures.sifworks.impl.TrackQueryResultsImpl

onQueryPending, onQueryResults

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TrackQueryResults

public TrackQueryResults()
                  throws ADKException

Constructs a TrackQueryResults object to be used when the agent is not processing a SIF_Event message. If the agent is processing a SIF_Event in the Subscriber.onEvent method, the other form of constructor must be used to invoke Selective Message Blocking.

Throws:

ADKException

TrackQueryResults

public TrackQueryResults(Event event,
                         MessageInfo msgInfo)
                  throws ADKException

Constructs a TrackQueryResults object to be used when the agent needs to query for additional data while processing a SIF_Event message. The Event object passed to Subscriber.onEvent must be passed to this form of constructor. Selective Message Blocking is invoked when the Agent Local Queue is not being used.

Parameters:

event - The Event object passed to Subscriber.onEvent

msgInfo - The MessageInfo object passed to Subscriber.onEvent

Throws:

ADKException

Method Detail

setQueryOptions

public void setQueryOptions(int queryOptions)

Sets optional query options

addQuery

public void addQuery(Zone zone,
                     Query query)

Add a query to be executed when the waitForResults method is called

addQuery

public void addQuery(Zone zone,
                     Query query,
                     java.lang.String destinationId)

Add a query to be executed when the waitForResults method is called

addQuery

public void addQuery(Topic topic,
                     Query query)

Add a query to be executed when the waitForResults method is called.

addQuery

public void addQuery(Topic topic,
                     Query query,
                     java.lang.String destinationId)

Add a query to be executed when the waitForResults method is called.

waitForResults

public boolean waitForResults(int timeout)

Sends a SIF_Request message for each Query passed to the addQuery method and resets the timeout period to the given value. Blocks until at least one pending query returns data or the timeout period expires.

This method should be called repeatedly in a while loop as SIF_Response packets may be received by the agent in multiple packets. If not enclosed in a while loop, your agent will only process the first packet when a multi-packet SIF_Response is received. (If the caller only expects one packet - for example, when querying for a single SIF Data Object during SIF_Event processing - an outer while loop is not necessary.) Each time this method is called, the timeout period is reset and any new queries that have been added are executed. If called and all queries tracked by this object have returned data, no action is taken.

If a SIF_Request messages fails with an error acknowledgement from the ZIS or otherwise results in an exception, the error condition can be learned by calling the getErrors method. It is recommended that you always check for an error condition by calling the hasErrors or getErrors methods.

Returns:

true if result data is available, otherwise false

See Also:

getErrors(), hasErrors()

available

public int available()

Returns the number of results currently available

Returns:

The number of

hasNext

public boolean hasNext()

Determines if any results will be returned by the next method

isComplete

public boolean isComplete()

Have all requests been received?

next

public TrackQueryResultsData next()

Returns the next group of result data, or null if no data is available. This method must be called repeatedly to retrieve all results because TrackQueryResults may have received multiple SIF_Response messages in response to its queries.

getErrors

public ADKException[] getErrors()

Gets any SIF_Request errors received when the queries were executed.

When the waitForResults method is called, it executes all queries previously added to the TrackQueryResults object. If an error acknowledgement is received for a SIF_Request message, it is returned in this array. Call the ADKException.getZone method to learn the zone associated with each exception.

Returns:

An array of ADKExceptions representing all error acknowledgements received by TrackQueryResults when the queries were issued.

See Also:

hasErrors(), waitForResults(int)

hasErrors

public boolean hasErrors()

Determines if any SIF_Request errors occurred when the queries were executed.

See Also:

getErrors(), waitForResults(int)