com.edustructures.sifworks
Interface Zone

All Superinterfaces:

Provisioner

public interface Zone
extends Provisioner

A Zone is a logical grouping of applications that exchange data through the Schools Interoperability Framework. Each zone is managed by a Zone Integration Server (ZIS). Refer to the SIF Specifications for a more detailed definition. Agents developed with the ADK may connect to multiple zones concurrently.

Zones have the following characteristics:

• Each zone connects to a Zone Integration Server, which provides a reliable and persistent queue for the storage of messages pending delivery to the agent. The "connection" is a logical one. The ADK handles retrieving messages from the queue and dispatching them to the Publisher, Subscriber, and QueryResults interfaces registered with your agent's Zone or Topic objects.
  
  
• The ADK provides a persistent and reliable Agent Local Queue (ALQ) for each zone. Messages retrieved from the Zone Integration Server are stored in the local queue before being processed. A given message exists in the local queue or in the server queue but never in both. The Agent Local Queue provides for enhanced reliability and supports disconnected communications with the server.
  
  
• Each zone maintains its own set of properties. By default, a zone inherits its default properties from the agent. To set properties on a per-zone basis, call the Zone.getProperties method to obtain the zone's AgentProperties object, then call its accessor methods. Properties must be set prior to calling connect.
  
  

In order to exchange messages with a zone, the agent must be connected to the zone. The act of connecting establishes local resources for transport protocols and queuing. Depending on the flags passed to the connect method, the agent may also send SIF registration messages to establish similar resources on the server.

An agent obtains a Zone instance by calling Agent.getZoneFactory. When finished interacting with a zone, call the disconnect method to release local resources held by the ADK as well as to optionally send a SIF_Unregister message to the server. Disconnecting all zones to which an agent is connected is easily done by calling the Agent.shutdown method when the agent exits.

Agents typically use Topic objects to aggregate publish, subscribe, and query activity across multiple zones. Refer to the Topic interface for details.

Version:

ADK 1.0

Method Summary

void	addMessagingListener(MessagingListener listener) Register a MessagingListener to listen to messages received by the message handlers of this class.
void	connect(int flags) Connects the agent with this zone.
void	disconnect(int flags) Disconnects the agent from this zone.
Agent	getAgent() Gets the Agent object
java.util.List<SIFException>	getConnectWarnings() Gets a read-only list of any SIF Errors that resulted from the sending of provisioning messages to the zone.
UndeliverableMessageHandler	getErrorHandler() Gets the UndeliverableMessageHandler for this zone.
org.apache.log4j.Logger	getLog() Gets the Log4j Logger for this zone.
AgentProperties	getProperties() Gets the properties for this zone.
ServerLog	getServerLog() Gets the ServerLog for this zone.
java.lang.Object	getUserData() Gets the application-supplied object for this Zone
java.lang.String	getZoneId() Gets the zone identifier
SIF_ZoneStatus	getZoneStatus() Gets the SIF_ZoneStatus object from the ZIS managing this zone.
SIF_ZoneStatus	getZoneStatus(int timeout) Gets the SIF_ZoneStatus object from the ZIS managing this zone.
java.net.URL	getZoneUrl() Gets the URL of the Zone Integration Server that manages this zone
boolean	isConnected() Gets the connection state of this zone
boolean	isSleeping(int flags) Determines if the agent's queue for this zone is in sleep mode.
void	purgeQueue(boolean incoming, boolean outgoing) Purge all pending incoming and/or outgoing messages from this agent's queue.
java.lang.String	query(Query query) Query the zone.
java.lang.String	query(Query query, int queryOptions) Query the zone with options.
java.lang.String	query(Query query, MessagingListener listener) Query the zone and notify a MessagingListener
java.lang.String	query(Query query, MessagingListener listener, int queryOptions) Query the zone with options and notify a MessagingListener
java.lang.String	query(Query query, MessagingListener listener, java.lang.String destinationId, int queryOptions) Query a specific agent registered with this zone (a directed query) and notify a MessagingListener.
java.lang.String	query(Query query, java.lang.String destinationId, int queryOptions) Query a specific agent registered with this zone (a directed query).
void	removeMessagingListener(MessagingListener listener) Remove a MessagingListener previously registered with the addMessagingListener method.
void	reportEvent(Event event) Report a SIF Event to the zone
void	reportEvent(SIFDataObject obj, EventAction actionCode) Report a SIF Event to the zone
void	reportEvent(SIFDataObject obj, EventAction actionCode, SIFContext... contexts) Report a SIF Event to the zone in one or more specific SIF Contexts
void	reportEvent(SIFDataObject obj, EventAction action, java.lang.String destinationId) Report a directed SIF Event to the agent in the zone identified by destinationId.
void	setErrorHandler(UndeliverableMessageHandler handler) Sets the UndeliverableMessageHandler to be called when a dispatching error occurs on this zone.
void	setProperties(AgentProperties props) Assigns a new properties object to this zone.
void	setUserData(java.lang.Object data) Assigns an application-supplied object to this Zone
SIF_Ack	sifPing() Sends a SIF_Ping message to the ZIS that manages this zone.
SIF_Ack	sifProvide(java.lang.String[] objectType) Sends a SIF_Provide message to the ZIS.
SIF_Ack	sifRegister() Sends a SIF_Register message to the ZIS.
SIF_Ack	sifSend(java.lang.String xml) Sends arbitrary SIF_Message content to the zone.
SIF_Ack	sifSubscribe(java.lang.String[] objectType) Sends a SIF_Subscribe message to the ZIS.
SIF_Ack	sifUnprovide(java.lang.String[] objectType) Sends a SIF_Unprovide message to the ZIS.
SIF_Ack	sifUnregister() Sends a SIF_Unregister message to the ZIS.
SIF_Ack	sifUnsubscribe(java.lang.String[] objectType) Sends a SIF_Unsubscribe message to the ZIS.
void	sleep() Puts this zone into sleep mode.
java.lang.String	toString() Returns the string representation of this zone as "zoneId@zoneUrl"
void	wakeup() Wakes up this zone if currently in sleep mode.

Methods inherited from interface com.edustructures.sifworks.Provisioner

setPublisher, setPublisher, setQueryResults, setQueryResults, setReportPublisher, setSubscriber

Method Detail

getProperties

AgentProperties getProperties()

Gets the properties for this zone.

By default, a zone inherits the default agent properties.

Returns:

The zone properties

setProperties

void setProperties(AgentProperties props)

Assigns a new properties object to this zone.

By default, a zone inherits the default agent properties. To change a property, first call the getProperties method to obtain the zone's properties object, then call any of the accessor methods available on that object. Because zones are constructed with a default AgentProperties object, it is typically not necessary to call this method.

Parameters:

props - A new properties object to replace the existing object

getAgent

Agent getAgent()

Gets the Agent object

Returns:

The Agent that created this Zone instance

getZoneId

java.lang.String getZoneId()

Gets the zone identifier

Returns:

The name of the zone as defined by the Zone Integration Server

getZoneUrl

java.net.URL getZoneUrl()

Gets the URL of the Zone Integration Server that manages this zone

Returns:

The URL to the ZIS (e.g. "http://host:port/zoneId" is the URL convention employed by the SIFWorks ZIS)

connect

void connect(int flags)
             throws ADKException

Connects the agent with this zone.

An agent must connect to a zone in order to perform messaging within the context of the ADK Class Framework. A typical agent calls this method at startup for each zone it will connect to, then optionally joins the Zone with one or more Topics.

The ADK's Provisioning Mode affects the messages sent by this method. Refer to the AgentProperties class for more information.

The ADK will send <SIF_Subscribe> and <SIF_Provide> messages to the zone to provision the SIF Data Objects for which the agent has registered a Subscriber and Publisher message handlers, respectively. The adk.provisioning.batch agent property (refer to the AgentProperties class) determines whether the ADK sends a single message or individual messages for each SIF Data Object. When individual messages are sent (the default), Category 4 Access Control errors are treated as warnings. Connect warnings can be retrieved by calling the getConnectWarnings method. When a single message is sent, any SIF Error will result in the raising of a SIFException.

Note the SIF_Wakeup and SIF_Ping system control messages are sent to the server upon successful connection.

Parameters:

flags - One or more of the following flags:

Flag	Description
ADKFlags.REGISTER	Sends a SIF_Register message to the ZIS and wakes up the agent queue on the server if previously in sleep mode.

Throws:

java.lang.IllegalStateException - is thrown if this zone is already in the connected state (i.e. connect has already been called without a corresponding call to disconnect)

ADKException - is thrown if there is a SIF Error acknowledgement to a <SIF_Register>, <SIF_Subscribe>, or <SIF_Provide> message as described above

See Also:

disconnect(int)

disconnect

void disconnect(int flags)
                throws ADKException

Disconnects the agent from this zone.

Resources held by the Class Framework, including the Agent Local Queue, are closed. To ensure these resources are properly closed, agents should disconnect from zones even when not planning on sending a < SIF_Unregister> provisioning message.

Provisioning messages are sent as follows:

• If the agent is using ADK-managed provisioning, a < SIF_Unregister> message is sent to the ZIS when the ADKFlags.PROV_UNREGISTER flag is specified. When ADK-managed provisioning is disabled, no messages are sent to the zone.
• If Agent-managed provisioning is enabled, the flags flags have no affect. The agent must explicitly call the sifUnregister method to manually send those message to the zone.
• If ZIS-managed provisioning is enabled, no provisioning messages are sent by the agent regardless of the flags used and the methods are called.

Note that SIF Agent sessions are long-lived and therefore an agent may remain registered with a ZIS even when it is "disconnected" from the perspective of the ADK Class Framework.

Disconnecting a zone also places the agent's server queue in sleep mode. This functionality can be disabled via the zone properties.

Parameters:

flags - One or more flags as described above

Throws:

java.lang.IllegalStateException - is thrown if this zone is not in the connected state (i.e. connect has not been called, or disconnect has already been called)

ADKException - is thrown if there is an error sending a <SIF_Unregister> message

See Also:

connect(int)

getConnectWarnings

java.util.List<SIFException> getConnectWarnings()

Gets a read-only list of any SIF Errors that resulted from the sending of provisioning messages to the zone. Only access control errors (Category 4) are treated as warnings rather than errors; all other SIF Errors result in an exception thrown by the connect method

Returns:

A List of SIFExceptions

isConnected

boolean isConnected()

Gets the connection state of this zone

Returns:

true if the connect method has been called but the disconnect method has not

reportEvent

void reportEvent(Event event)
                 throws ADKException

Report a SIF Event to the zone

Parameters:

event - An Event object describing the SIF Data Object that has changed and how it has changed (added, updated, or removed)

Throws:

ADKException

reportEvent

void reportEvent(SIFDataObject obj,
                 EventAction actionCode)
                 throws ADKException

Report a SIF Event to the zone

Parameters:

obj - The object that was added, changed, or deleted

actionCode - The action being taken on the object ( ADD, CHANGE, or DELETE )

Throws:

ADKException

reportEvent

void reportEvent(SIFDataObject obj,
                 EventAction actionCode,
                 SIFContext... contexts)
                 throws ADKException

Report a SIF Event to the zone in one or more specific SIF Contexts

Parameters:

obj - the object that was added, changed, or deleted

actionCode - The action being taken on the object

contexts - An array or sequence (varargs) of specific SIF Contexts to report this event in.

Throws:

ADKException

reportEvent

void reportEvent(SIFDataObject obj,
                 EventAction action,
                 java.lang.String destinationId)
                 throws ADKException

Report a directed SIF Event to the agent in the zone identified by destinationId. Note: Directed SIF Events may not be supported by all zone integration servers.

Parameters:

obj - The object that was added, changed, or deleted

action - The action being taken on the object

destinationId - The SourceId of the agent to which the SIF Event will be routed by the zone integration server

Throws:

ADKException - If an error occurs while reporting the event

query

java.lang.String query(Query query)
                       throws ADKException

Query the zone.

Parameters:

query - A Query object describing the parameters of the query, including optional conditions and field restrictions

Returns:

The SIF_MsgId of the SIF_Request that was sent to the zone.

Throws:

ADKException - If an error occurs while sending the Query to the zone

query

java.lang.String query(Query query,
                       MessagingListener listener)
                       throws ADKException

Query the zone and notify a MessagingListener

Parameters:

query - A Query object describing the parameters of the query, including optional conditions and field restrictions

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.

Returns:

The SIF_MsgId of the SIF_Request that was sent to the zone.

Throws:

ADKException - If an error occurs while sending the query to the zone

Since:

ADK 1.5

query

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

Query the zone with options.

Parameters:

query - A Query object describing the parameters of the query, including optional conditions and field restrictions.

queryOptions - Reserved for future use.

Returns:

The SIF_MsgId of the SIF_Request that was sent to the zone

Throws:

ADKException - If an error occurs while sending the query to the zone

query

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

Query the zone with options and notify a MessagingListener

Parameters:

query - A Query object describing the parameters of the query, including optional conditions and field restrictions.

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.

queryOptions - Reserved for future use.

Returns:

The SIF_MsgId of the SIF_Request that was sent to the zone

Throws:

ADKException

Since:

ADK 1.5

query

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

Query a specific agent registered with this zone (a directed query).

Directed queries are used primarily when the source of data is known because of a message previously received from that agent. For example, if your agent receives a SIF_Event and you wish to query the author of that event for additional data, a directed query is appropriate.

In addition, some kinds of SIF Data Objects in SIF 1.5 and later may be designed to require agents to send directed queries if more than one agent in a zone typically offers support for the object. This is necessary because only one agent can be the authoritative provider of a given object type in each zone.

Parameters:

query - A Query object describing the parameters of the query, including optional conditions and field restrictions

destinationId - The SourceId of the agent to which the SIF Request will be routed by the zone integration server

queryOptions - Reserved for future use

Returns:

The SIF_MsgId of the SIF_Request that was sent to the zone.

Throws:

ADKException

query

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

Query a specific agent registered with this zone (a directed query) and notify a MessagingListener.

Directed queries are used primarily when the source of data is known because of a message previously received from that agent. For example, if your agent receives a SIF_Event and you wish to query the author of that event for additional data, a directed query is appropriate.

In addition, some kinds of SIF Data Objects in SIF 1.5 and later may be designed to require agents to send directed queries if more than one agent in a zone typically offers support for the object. This is necessary because only one agent can be the authoritative provider of a given object type in each zone.

Parameters:

query - A Query object describing the parameters of the query, including optional conditions and field restrictions

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 will be routed by the zone integration server

queryOptions - Reserved for future use

Returns:

The SIF_MsgId of the SIF_Request that was sent to the zone.

Throws:

ADKException - Thrown if an error occurs while sending the query to the zone

Since:

ADK 1.5

getZoneStatus

SIF_ZoneStatus getZoneStatus()
                             throws ADKException

Gets the SIF_ZoneStatus object from the ZIS managing this zone. The method blocks until a result is received.

Returns:

The SIF_ZoneStatus object for the zone

Throws:

ADKException - If the ADK cannot connect to the zone to request the SIF_ZoneStatus object

getZoneStatus

SIF_ZoneStatus getZoneStatus(int timeout)
                             throws ADKException

Gets the SIF_ZoneStatus object from the ZIS managing this zone. The method blocks for the specified timeout period.

Parameters:

timeout - The amount of time to wait for a SIF_ZoneStatus object to be received by the agent (or -1 to wait infinitely)

Returns:

The SIF_ZoneStatus object for the zone

Throws:

ADKException - If the ADK cannot connect to the zone to request the SIF_ZoneStatus object

addMessagingListener

void addMessagingListener(MessagingListener listener)

Register a MessagingListener to listen to messages received by the message handlers of this class.

NOTE: Agents may register a MessagingListener with the Agent or Zone classes. When a listener is registered with both classes, it will be called twice. Consequently, it is recommended that most implementations choose to register MessagingListeners with only one of these classes depending on whether the agent is interested in receiving global notifications or notifications on only a subset of zones.

Parameters:

listener - a MessagingListener implementation

removeMessagingListener

void removeMessagingListener(MessagingListener listener)

Remove a MessagingListener previously registered with the addMessagingListener method.

Parameters:

listener - a MessagingListener implementation

purgeQueue

void purgeQueue(boolean incoming,
                boolean outgoing)
                throws ADKException

Purge all pending incoming and/or outgoing messages from this agent's queue. Only messages associated with this zone are affected. See also the Agent.purgeQueue and Topic.purgeQueue methods to purge the queues of all zones with which the agent is connected, or all zones joined with a given topic, 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 - Thrown if an error occurs while purging the queue

sleep

void sleep()
           throws ADKException

Puts this zone into sleep mode.

A SIF_Sleep message is sent to the Zone Integration Server to request that this agent's queue be put into sleep mode. If successful, the ZIS should not deliver further messages to this agent until it is receives a SIF_Register or SIF_Wakeup message from the agent. Note the ADK keeps an internal sleep flag for each zone, which is initialized when the connect method is called by sending a SIF_Ping to the ZIS. This flag is set so that the ADK will return a Status Code 8 ("Receiver is sleeping") in response to any message received by the ZIS for the duration of the session.

If the SIF_Sleep message is not successful, an exception is thrown and the ADK's internal sleep flag for this zone is not changed.

Throws:

ADKException - thrown if the SIF_Sleep message is unsuccessful

wakeup

void wakeup()
            throws ADKException

Wakes up this zone if currently in sleep mode.

A SIF_Wakeup message is sent to the Zone Integration Server to request that sleep mode be removed from this agent's queue. Note the ADK keeps an internal sleep flag for each zone, which is initialized when the connect method is called by sending a SIF_Ping to the ZIS. This flag is cleared so that the ADK will no longer return a Status Code 8 ("Receiver is sleeping") in response to messages received by the ZIS.

If the SIF_Sleep message is not successful, an exception is thrown and the ADK's internal sleep flag for this zone is not changed.

Throws:

ADKException - thrown if the SIF_Wakeup message is unsuccessful

setErrorHandler

void setErrorHandler(UndeliverableMessageHandler handler)

Sets the UndeliverableMessageHandler to be called when a dispatching error occurs on this zone. For more information, please refer to the UnderliverableMessageHandler class comments.

Parameters:

handler - The handler to call when the ADK cannot dispatch an inbound message

getErrorHandler

UndeliverableMessageHandler getErrorHandler()

Gets the UndeliverableMessageHandler for this zone. If not set, the error handler of the Agent is used if defined.

Returns:

The class that has been set as the UndeliverableMessageHandler for this zone

See Also:

setErrorHandler(com.edustructures.sifworks.UndeliverableMessageHandler)

isSleeping

boolean isSleeping(int flags)
                   throws ADKException

Determines if the agent's queue for this zone is in sleep mode.

Parameters:

flags - When ADKFlags.LOCAL_QUEUE is specified, returns true if the Agent Local Queue is currently in sleep mode. False is returned if the Agent Local Queue is disabled. When ADKFlags.SERVER_QUEUE is specified, queries the sleep mode of the Zone Integration Server by sending a SIF_Ping message.

Returns:

True if the zone is sleeping

Throws:

ADKException - Thrown if an error occurs while checking the zone's sleep status

sifRegister

SIF_Ack sifRegister()
                    throws ADKException

Sends a SIF_Register message to the ZIS. This method can be called by agents that have chosen to use Agent-managed provisioning. If ZIS-managed or ADK-managed provisioning is enabled for this zone, the method has no effect.

Returns:

The SIF_Ack returned from the ZIS

Throws:

ADKException - Thrown if an error occurs while sending the sif

sifUnregister

SIF_Ack sifUnregister()
                      throws ADKException

Sends a SIF_Unregister message to the ZIS. This method can be called by agents that have chosen to use Agent-managed provisioning. If ZIS-managed or ADK-managed provisioning is enabled for this zone, the method has no effect.

Throws:

ADKException

sifSubscribe

SIF_Ack sifSubscribe(java.lang.String[] objectType)
                     throws ADKException

Sends a SIF_Subscribe message to the ZIS. This method can be called by agents that have chosen to use Agent-managed provisioning. If ZIS-managed or ADK-managed provisioning is enabled for this zone, the method has no effect.

Throws:

ADKException

sifUnsubscribe

SIF_Ack sifUnsubscribe(java.lang.String[] objectType)
                       throws ADKException

Sends a SIF_Unsubscribe message to the ZIS. This method can be called by agents that have chosen to use Agent-managed provisioning. If ZIS-managed or ADK-managed provisioning is enabled for this zone, the method has no effect.

Throws:

ADKException

sifProvide

SIF_Ack sifProvide(java.lang.String[] objectType)
                   throws ADKException

Sends a SIF_Provide message to the ZIS. This method can be called by agents that have chosen to use Agent-managed provisioning. If ZIS-managed or ADK-managed provisioning is enabled for this zone, the method has no effect.

Throws:

ADKException

sifUnprovide

SIF_Ack sifUnprovide(java.lang.String[] objectType)
                     throws ADKException

Sends a SIF_Unprovide message to the ZIS. This method can be called by agents that have chosen to use Agent-managed provisioning. If ZIS-managed or ADK-managed provisioning is enabled for this zone, the method has no effect.

Throws:

ADKException

sifPing

SIF_Ack sifPing()
                throws ADKException

Sends a SIF_Ping message to the ZIS that manages this zone.

Throws:

ADKException

sifSend

SIF_Ack sifSend(java.lang.String xml)
                throws ADKException

Sends arbitrary SIF_Message content to the zone. This method does not alter the message or wrap it in an envelope prior to sending it.

Parameters:

xml - A valid SIF_Message complete with a SIF_Header header and a payload such as SIF_Register, SIF_Request, SIF_Event, etc.

Returns:

A SIF_Ack object encapsulating the SIF_Ack response that was returned from the Zone Integration Server

Throws:

ADKException

setUserData

void setUserData(java.lang.Object data)

Assigns an application-supplied object to this Zone

Parameters:

data - Any object the application wishes to attach to this Zone instance

getUserData

java.lang.Object getUserData()

Gets the application-supplied object for this Zone

Returns:

The object passed to the setUserData method

getLog

org.apache.log4j.Logger getLog()

Gets the Log4j Logger for this zone.

getServerLog

ServerLog getServerLog()

Gets the ServerLog for this zone.

Returns:

The ServerLog instance for the zone

Since:

ADK 1.5

toString

java.lang.String toString()

Returns the string representation of this zone as "zoneId@zoneUrl"

Overrides:

toString in class java.lang.Object