com.edustructures.sifworks
Interface Topic

public interface Topic

Aggregates publish, subscribe, and query activity across multiple zones.

An agent typically registers with its zones at startup, creates Topic instances for the data types it is interested in, and then joins topics to each zone by calling join(Zone). Topics can be joined to any number of zones. If an agent wishes to manage publish and subscribe activity on a per-zone basis, it can do so by provisioning the zones directly by calling Provisioner.setPublisher(Publisher), Provisioner.setQueryResults(QueryResults), or Provisioner.setSubscriber(Subscriber, ElementDef, SubscriptionOptions)

The ADK applies publish, subscribe, and query functionality equally to all zones joined to a topic. Thus, if the topic provides authoritative data to its zones (that is, it is registered with the ZIS as a Provider), it will do so for all zones by delegating incoming queries to the Publisher registered with this topic. Similarly, the topic will query all zones for data objects when the query(Query) method is called. (An exception to this is directed queries, which require that the caller specify a zone and agent name to direct the query.)

Consult the ADK Developer Guide for more information about working with multiple zones.

Version:

1.0

Method Summary

Query	createQuery() Creates a Query instance that is initialized to request the object type encapsulated by this Topic and this SIFContext.
ElementDef	getObjectDef() Gets the ElementDef representing the SIF Data Object associated with this topic
java.lang.String	getObjectType() Gets the name of the SIF Data Object associated with this topic
Publisher	getPublisher() Gets the Publisher registered with this topic
QueryResults	getQueryResultsObject() Gets the QueryResults object that is registered with this topic.
ReportPublisher	getReportPublisher() Gets the ReportPublisher registered with this topic
SIFContext	getSIFContext() Gets the SIFContext that this Topic is bound to.
Subscriber	getSubscriber() Gets the Subscriber registered with this topic
Zone[]	getZones() Gets all zones joined to this topic
void	join(Zone zone) Joins a zone with this topic.
void	purgeQueue(boolean incoming, boolean outgoing) Purge all pending incoming and/or outgoing messages from this agent's queue.
void	query() Query the topic by sending a SIF_Request message to all zones joined with the topic.
void	query(Query query) Query the topic by sending a SIF_Request message to all zones joined with the topic
void	query(Query query, int queryOptions) Query the topic by sending a SIF_Request message to all zones joined with the topic
void	query(Query query, MessagingListener listener) Query the topic by sending a SIF_Request message to all zones joined with the topic.
void	query(Query query, MessagingListener listener, int queryOptions) Query the topic by sending a SIF_Request message to all zones joined with the topic.
void	query(Query query, MessagingListener listener, java.lang.String destinationId, int queryOptions) Query the topic by sending a SIF_Request message to all zones joined with the topic.
void	query(Query query, java.lang.String destinationId, int queryOptions) Query the topic by sending a SIF_Request message to all zones joined with the topic
void	setPublisher(Publisher publisher, PublishingOptions flags) Register a Publisher message handler to process SIF_Request messages received on the zones joined with this topic.
void	setQueryResults(QueryResults queryResultsObject, QueryResultsOptions flags) Sets the QueryResults message handler registered with this topic.
void	setReportPublisher(ReportPublisher publisher, ReportPublishingOptions flags) Register a ReportPublisher message handler to process SIF_Request messages received for SIF_ReportObject objects from the zones joined with this topic.
void	setSubscriber(Subscriber subscriber, SubscriptionOptions flags) Register a Subscriber message handler to process SIF_Event messages received on the zones joined with this topic.

Method Detail

join

void join(Zone zone)
          throws ADKException

Joins a zone with this topic.

All SIF messaging performed on this topic will be propagated to all zones joined with the topic. For example, calling the query method queries all of the topic's zones, and SIF_Responses received by each zone are first dispatched to the topic's QueryResults object.

Parameters:

zone - A Zone created by the agent ZoneFactory

Throws:

ADKException - is thrown if the zone is already joined to a topic or if there is a SIF error during agent registration.

getObjectType

java.lang.String getObjectType()

Gets the name of the SIF Data Object associated with this topic

Returns:

A SIF Data Object type such as "StudentPersonal"

getObjectDef

ElementDef getObjectDef()

Gets the ElementDef representing the SIF Data Object associated with this topic

Returns:

The ElementDef used to create this Topic instance, such as StudentDTD.STUDENTPERSONAL

getSIFContext

SIFContext getSIFContext()

Gets the SIFContext that this Topic is bound to. A single Topic can only be bound to a single SIF Context.

Returns:

The SIFContext that this Topic is bound to.

getZones

Zone[] getZones()

Gets all zones joined to this topic

Returns:

An array of Zones

setPublisher

void setPublisher(Publisher publisher,
                  PublishingOptions flags)
                  throws ADKException

Register a Publisher message handler to process SIF_Request messages received on the zones joined with this topic. The message handler will be called whenever a SIF_Request is received for the SIF Data Object type associated with the topic.

For Topics created to represent the SIF_ReportObject object type, register a publisher message handler with the setReportPublisher method instead.

Parameters:

publisher - An object that implements the Publisher interface.

flags - Specify ADKFlags.PROV_PROVIDE to register the agent as the default provider of the object type associated with this topic. The ADK will send a SIF_Provide message to each zone joined with the topic. Specify ADKFlags.PROV_NONE if the agent can respond to requests for the object type but will not register as the authoritative provider.

Throws:

ADKException - Thrown

setReportPublisher

void setReportPublisher(ReportPublisher publisher,
                        ReportPublishingOptions flags)

Register a ReportPublisher message handler to process SIF_Request messages received for SIF_ReportObject objects from the zones joined with this topic. ReportPublisher is implemented by Vertical Reporting applications that publish report data via the SIF_ReportObject object (SIF 1.5 and later).

This method must be called instead of setPublisher for topics created to represent the SIF_ReportObject data type.

Parameters:

publisher - An object that implements the Publisher interface.

flags - Specify ADKFlags.PROV_PROVIDE to register the agent as the default provider of the object type associated with this topic. The ADK will send a SIF_Provide message to each zone joined with the topic. Specify ADKFlags.PROV_NONE if the agent can respond to requests for the object type but will not register as the authoritative provider.

Since:

ADK 1.5

getPublisher

Publisher getPublisher()

Gets the Publisher registered with this topic

Returns:

The object passed to the setPublisher method

getReportPublisher

ReportPublisher getReportPublisher()

Gets the ReportPublisher registered with this topic

Returns:

The object passed to the setReportPublisher method

See Also:

setReportPublisher(ReportPublisher, ReportPublishingOptions)

setSubscriber

void setSubscriber(Subscriber subscriber,
                   SubscriptionOptions flags)
                   throws ADKException

Register a Subscriber message handler to process SIF_Event messages received on the zones joined with this topic. The message handler will be called whenever a SIF_Event is received for the SIF Data Object type associated with the topic.

Parameters:

subscriber - An object that implements the Subscriber interface

flags - Specify ADKFlags.PROV_SUBSCRIBE to register the agent as a subscriber of the object type. The ADK will send a SIF_Subscribe message to each zone joined with the topic.

Throws:

ADKException

getSubscriber

Subscriber getSubscriber()

Gets the Subscriber registered with this topic

Returns:

The object passed to the setSubscriber method

setQueryResults

void setQueryResults(QueryResults queryResultsObject,
                     QueryResultsOptions flags)
                     throws ADKException

Sets the QueryResults message handler registered with this topic. This object will be called whenever a SIF_Response message is received by one of the zones joined with this topic and the response contains data associated with the topic. Note that SIF_Response messages are dispatched to this handler only if the initial request was issued by calling one of the Topic.query methods.

Parameters:

queryResultsObject - An QueryResults message handler

flags - The QueryResultsOptions that should be used for this agent, or Null to accept defaults

Throws:

ADKException

See Also:

query(Query), getQueryResultsObject()

getQueryResultsObject

QueryResults getQueryResultsObject()

Gets the QueryResults object that is registered with this topic.

Returns:

The message handler instance passed to the setQueryResults method, or null if no message handler is registered with this topic.

createQuery

Query createQuery()

Creates a Query instance that is initialized to request the object type encapsulated by this Topic and this SIFContext.

It is good practice that this factory method be used when creating Query instances for Topics. If a Query object is created outside of this method, it may still work, but if created incorrectly (using the wrong ElementDef or SIFContext), This topic will not be able to process the results of the Query.

Returns:

a Query instance that has been set to represent a SIF_Request for the SIFDataObject type represented by this topic

query

void query()
           throws ADKException

Query the topic by sending a SIF_Request message to all zones joined with the topic. To specify query conditions for this object, call createQuery() to get a Query instance, add query Conditions by calling Query.addCondition(ElementDef, ComparisonOperators, String), and then call query(Query)

Throws:

ADKException

query

void query(Query query)
           throws ADKException

Query the topic by sending a SIF_Request message to all zones joined with the topic

Parameters:

query - A Query object that encapsulates the elements to query and the optional field restrictions placed on the results

Throws:

ADKException

query

void query(Query query,
           MessagingListener listener)
           throws ADKException

Query the topic by sending a SIF_Request message to all zones joined with the topic. This form of the query method also notifies a MessagingListener of any SIF_Request messaging that takes place.

Parameters:

query - A Query object that encapsulates the elements to query and the optional field restrictions placed on the results

listener - A MessagingListener that will be notified when the SIF_Request message is sent to the zone. Any other MessagingListeners registered with the zone will also be called.

Throws:

ADKException

Since:

ADK 1.5

query

void query(Query query,
           int queryOptions)
           throws ADKException

Query the topic by sending a SIF_Request message to all zones joined with the topic

Parameters:

query - A Query object that encapsulates the elements to query and the optional field restrictions placed on the results

queryOptions - Reserved for future use

Throws:

ADKException

query

void query(Query query,
           MessagingListener listener,
           int queryOptions)
           throws ADKException

Query the topic by sending a SIF_Request message to all zones joined with the topic. This form of the query method also notifies a MessagingListener of any SIF_Request activity that takes place.

Parameters:

query - A Query object that encapsulates the elements to query and the optional field restrictions placed on the results

queryOptions - Reserved for future use

listener - A MessagingListener that will be notified when the SIF_Request message is sent to the zone. Any other MessagingListeners registered with the zone will also be called.

Throws:

ADKException

Since:

ADK 1.5

query

void query(Query query,
           java.lang.String destinationId,
           int queryOptions)
           throws ADKException

Query the topic by sending a SIF_Request message to all zones joined with the topic

Parameters:

query - A Query object that encapsulates the elements to query and the optional field restrictions placed on the results

destinationId - The SourceId of the agent to which the SIF_Request message should be delivered. When null, the message is delivered to the object provider as defined by the SIF Zone

queryOptions - Reserved for future use

Throws:

ADKException

query

void query(Query query,
           MessagingListener listener,
           java.lang.String destinationId,
           int queryOptions)
           throws ADKException

Query the topic by sending a SIF_Request message to all zones joined with the topic. This form of the query method also notifies a MessagingListener of any SIF_Request messaging that takes place.

Parameters:

query - A Query object that encapsulates the elements to query and the optional field restrictions placed on the results.

listener - A MessagingListener that will be notified when the SIF_Request message is sent to the zone. Any other MessagingListeners registered with the zone will also be called.

destinationId - The SourceId of the agent to which the SIF_Request message should be delivered. When null, the message is delivered to the object provider as defined by the SIF Zone.

queryOptions - Reserved for future use.

Throws:

ADKException

Since:

ADK 1.5

purgeQueue

void purgeQueue(boolean incoming,
                boolean outgoing)
                throws ADKException

Purge all pending incoming and/or outgoing messages from this agent's queue. Only messages destined to and originating from the zones joined to this topic are affected. See also the Agent.purgeQueue and Zone.purgeQueue methods to purge the queues of all zones to which the agent is connected or a specific zone, respectively.

• If the Agent Local Queue is enabled, messages are permanently and immediately removed from the queue. Any messages in transit are not affected.
• If the underlying messaging protocol offers a mechanism to clear the agent's queue, it is invoked. (SIF 1.0 does not have such a mechanism.)
• Otherwise, all incoming messages received by the agent having a timestamp earlier than or equal to the time this method is called are discarded. This behavior persists until the agent is terminated or until a message is received having a later timestamp.

Parameters:

incoming - true to purge incoming messages

outgoing - true to purge outgoing messages (e.g. pending SIF_Events) when the Agent Local Queue is enabled

Throws:

ADKException