com.edustructures.sifworks
Class Agent

java.lang.Object
  com.edustructures.sifworks.Agent

public class Agent
extends java.lang.Object

The base class for a SIF Agent.

Derive your own class from this one and pass the SourceId to the superclass constructor. Call the initialize method to initialize the agent prior to use.

Version:

ADK 1.0

Field Summary

static java.lang.String

LOG_IDENTIFIER

Constructor Summary

Agent(java.lang.String agentId)
Constructor

Method Summary

void	addMessagingListener(MessagingListener listener) Register a MessagingListener to listen to messages received by the message handlers of this class.
HttpProperties	getDefaultHttpProperties() Convenience method to get the default HTTP transport properties
HttpsProperties	getDefaultHttpsProperties() Convenience method to get the default HTTPS transport properties
TransportProperties	getDefaultTransportProperties(java.lang.String protocol) Gets the default properties for a transport protocol.
AgentProperties	getDefaultZoneProperties() Gets the default properties for Zones created by the ZoneFactory.
UndeliverableMessageHandler	getErrorHandler() Gets the UndeliverableMessageHandler for this agent.
java.lang.String	getHomeDir() Gets the agent's home directory.
java.lang.String	getId() Gets the agent's SourceId
static org.apache.log4j.Logger	getLog() Gets the root Log4j Category for this agent.
static org.apache.log4j.Logger	getLog(Zone zone) Gets the Log4j Category for a specific zone.
java.util.List<MessagingListener>	getMessagingListeners() Return a list of all MessagingListeners registered with the agent
java.lang.String	getName() Gets the descriptive name of the SIF Agent.
AgentProperties	getProperties() Gets the properties for this agent.
Publisher	getPublisher(SIFContext context, ElementDef objectType) Gets the global Publisher message handler registered with the Agent for the specified SIF object type
QueryResults	getQueryResults(SIFContext context, ElementDef objectType) Gets the global QueryResults message handler registered with the Agent for the specified SIF object type.
ReportPublisher	getReportPublisher(SIFContext context) Gets the global ReportPublisher message handler registered with the Agent.
static ServerLog	getServerLog() Gets the agent-global ServerLog instance.
static ServerLog	getServerLog(Zone zone) Gets the ServerLog for a specific zone.
Subscriber	getSubscriber(SIFContext context, ElementDef objectType) Gets the global Subscriber message handler registered with the Agent for the specified SIF object type.
TopicFactory	getTopicFactory() Gets the TopicFactory for this agent.
ZoneFactory	getZoneFactory() Gets the ZoneFactory for this agent.
void	initialize() Initialize the agent.
boolean	isInitialized() Determines if the agent has been initialized
boolean	isShutdown() Determines if the agent has been shutdown.
static java.lang.String	makeGUID() Utility method to generate a GUID for SIF Data Objects and messages
void	purgeQueue(boolean incoming, boolean outgoing) Purge all pending incoming and/or outgoing messages from this agent's queue.
void	removeMessagingListener(MessagingListener listener) Remove a MessagingListener previously registered with the addMessagingListener method.
void	setErrorHandler(UndeliverableMessageHandler handler) Sets the UndeliverableMessageHandler to be called when a dispatching error occurs on a zone but no handler is registered with that zone.
void	setId(java.lang.String sourceId) Sets the agent's SourceId
void	setName(java.lang.String name) Sets the descriptive name of the SIF Agent.
void	setPublisher(Publisher publisher) Register a global Publisher message handler with this agent for all SIF object types.
void	setPublisher(Publisher publisher, ElementDef objectType) Register a global Publisher message handler with the agent for the specified SIF object type.
void	setQueryResults(QueryResults queryResults) Register a global QueryResults message handler with this agent for all SIF object types and only for the default SIF Context
void	setQueryResults(QueryResults queryResults, ElementDef objectType) Register a global QueryResults message handler object with this agent for the specified SIF object type and only for the default SIF Context
void	setReportPublisher(ReportPublisher publisher) Register a global ReportPublisher message handler with the agent.
void	setSubscriber(Subscriber subscriber) Register a global Subscriber message handler with the agent for all SIF object types.
void	setSubscriber(Subscriber subscriber, ElementDef objectType) Register a global Subscriber message handler with this agent for the specified SIF object type and only for the default SIF Context
void	shutdown() Shutdown the agent.
void	shutdown(int provisioningOptions) Shutdown the agent.
void	sleep() Puts all connected zones into sleep mode.
void	wakeup() Wakes up all connected zones if currently in sleep mode.

Methods inherited from class java.lang.Object

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

Field Detail

LOG_IDENTIFIER

public static final java.lang.String LOG_IDENTIFIER

See Also:

Constant Field Values

Constructor Detail

Agent

public Agent(java.lang.String agentId)

Constructor

Parameters:

sourceId - The string name that uniquely identifies this agent in SIF Zones. This string is used as the SourceId in all SIF message headers created by the agent.

Method Detail

getZoneFactory

public ZoneFactory getZoneFactory()

Gets the ZoneFactory for this agent. The ZoneFactory is used to create Zone instances to represent logical SIF zones. An application can also call ZoneFactory methods to enumerate the Zones that have been created.

Returns:

The agent's ZoneFactory

getTopicFactory

public TopicFactory getTopicFactory()

Gets the TopicFactory for this agent. The TopicFactory is used to create Topic instances to aggregate publish and subscribe activity for a given type of SIF data object across one or more zones. An application can also call TopicFactory methods to enumerate the Topics that have been created.

Returns:

The agent's TopicFactory

getProperties

public AgentProperties getProperties()

Gets the properties for this agent.

The agent properties serve as defaults for new Zone objects created by the ZoneFactory. Properties may be customized on a zone-by-zone basis. If a property is not specified for a given zone, its value is inherited from the AgentProperties object returned by this method. Note this method returns the same object as getDefaultZoneProperties.

Agent properties should be set prior to calling the Agent.initialize method.

Returns:

The agent properties

getDefaultTransportProperties

public TransportProperties getDefaultTransportProperties(java.lang.String protocol)
                                                  throws ADKTransportException

Gets the default properties for a transport protocol.

Each transport protocol supported by the ADK is represented by a class that implements the Transport interface. Transports are identified by a string such as "http" or "https". Like Zones, each Transport instance is associated with a set of properties specific to the transport protocol. Such properties may include IP address, port, SSL security attributes, and so on. The default properties for a given transport protocol may be obtained by calling this method.

Returns:

The default properties for the specified protocol

Throws:

ADKTransportException - is thrown if the protocol is not supported by the ADK

getDefaultHttpProperties

public HttpProperties getDefaultHttpProperties()

Convenience method to get the default HTTP transport properties

getDefaultHttpsProperties

public HttpsProperties getDefaultHttpsProperties()

Convenience method to get the default HTTPS transport properties

getDefaultZoneProperties

public AgentProperties getDefaultZoneProperties()

Gets the default properties for Zones created by the ZoneFactory.

Returns:

The default zone properties

getHomeDir

public java.lang.String getHomeDir()

Gets the agent's home directory. By default, the home directory is the directory the agent was started from (if defined, the "adk.home" System property overrides this value.) You may override this method to return a home directory specific to your product's installation directory structure.

The Agent Runtime creates all work directories and files relative to the home directory. In some cases the Class Framework creates workspaces even when the Agent Runtime is not enabled.

Returns:

The agent's home directory

getId

public java.lang.String getId()

Gets the agent's SourceId

Returns:

The string name that uniquely identifies this agent in a SIF Zone.

setId

public void setId(java.lang.String sourceId)

Sets the agent's SourceId

Parameters:

sourceId - A string name that uniquely identifies this agent in a SIF Zone. SIF does not specify any restrictions on the length or characters that may appear in the SourceId.

getName

public java.lang.String getName()

Gets the descriptive name of the SIF Agent.

This string is used to identify the agent whenever a descriptive name is preferred over the agent ID. If the @link #getAgentInfo() method is not overrident, The class framework uses this string for the value of the <SIF_Name> element during agent registration.

By default, the agent ID is returned.

Returns:

A descriptive name for the agent

See Also:

getId(), setName(String)

setName

public void setName(java.lang.String name)

Sets the descriptive name of the SIF Agent.

This string is used to identify the agent whenever a descriptive name is preferred over the agent ID. The class framework uses this string for the value of the <SIF_Name> element during agent registration.

By default, the agent ID is used as the descriptive name. This method must be called at agent initialization time prior to connecting to zones.

Parameters:

name - A descriptive name for the agent

See Also:

getName()

initialize

public void initialize()
                throws java.lang.Exception

Initialize the agent.

An application must call this method to initialize the class framework and runtime. No other methods can be called until the agent has been successfully initialized. When the agent exits it is important that the shutdown method be called to safely release the resources allocated by the runtime.

If an application overrides this method, it should call the superclass implementation after performing its own initialization.

Throws:

InitializerException - is thrown if the agent has already been initialized

java.lang.Exception

See Also:

shutdown()

shutdown

public void shutdown()
              throws ADKException

Shutdown the agent.

This method should always be called before the application ends. It closes resources held by the class framework and runtime.

Calling this form of shutdown does not send any provisioning messages.

Throws:

ADKException

shutdown

public void shutdown(int provisioningOptions)
              throws ADKException

Shutdown the agent.

This method should always be called before the application ends. It closes resources held by the ADK Class Framework and ADK Agent Runtime.

Provisioning messages are sent as follows:

• If the agent is using ADK-managed provisioning, a < SIF_Unregister> message is sent to each zone to which the agent is connected if the ADKFlags.PROV_UNREGISTER flag is specified. <SIF_Unsubscribe> and <SIF_Unprovide> messages are sent to each zone joined to a Topic when the ADKFlags.PROV_UNSUBSCRIBE and ADKFlags.PROV_UNPROVIDE flags are specified, respectively. When ADK-managed provisioning is disabled, no provisioning messages are sent to zones.
• If Agent-managed provisioning is enabled, the ProvisioningOptions flags have no affect. The agent must explicitly call the Zone.sifUnregister, Zone.sifUnsubscribe, and Zone.sifUnprovide methods to manually send those messages to each zone.
• If ZIS-managed provisioning is enabled, no provisioning messages are sent by the agent regardless of the ProvisioningOptions used and the methods are called.

Throws:

ADKException

See Also:

initialize()

isInitialized

public boolean isInitialized()

Determines if the agent has been initialized

Returns:

true if the initialize method was called successfully; false if that method has not been called successfully or the agent has since been shut down.

isShutdown

public boolean isShutdown()

Determines if the agent has been shutdown.

Returns:

true if the shutdown method was called and the agent is either in the process of shutting down or has finished shutting down. Note the agent is considered to be shutdown even if the shutdown method fails.

sleep

public void sleep()
           throws ADKException

Puts all connected zones into sleep mode.

For each zone in the connected state, a SIF_Sleep message is sent to the Zone Integration Server to request that this agent's queue be put into sleep mode for that zone. 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.

Throws:

ADKException - thrown if the SIF_Sleep message is unsuccessful. The ADK will attempt to send a SIF_Sleep to all connected zones; the exception describes the zone or zones that failed

wakeup

public void wakeup()
            throws ADKException

Wakes up all connected zones if currently in sleep mode.

For each connected zone, a SIF_Wakeup message is sent to the Zone Integration Server to request that sleep mode be removed from this agent's queue for that zone. 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.

Throws:

ADKException - thrown if the SIF_Wakeup message is unsuccessful. The ADK will attempt to send a SIF_Wakeup to all connected zones; the exception describes the zone or zones that failed

setPublisher

public void setPublisher(Publisher publisher)

Register a global Publisher message handler with this agent for all SIF object types.

Note agents typically register message handlers with Topics or with Zones instead of with the Agent. The message dispatcher first delivers messages to Topics, then to Zones, and finally to the Agent itself.

In order to receive SIF_Request messages, the agent is expected to be registered as a Provider of one or more object types in at least one zone. This method does not send SIF_Provide messages to any zones.

Parameters:

publisher - An object that implements the Publisher interface to respond to SIF_Request queries received by the agent. This object will be called whenever a SIF_Request is received by and no other object in the message dispatching chain has processed the message.

setPublisher

public void setPublisher(Publisher publisher,
                         ElementDef objectType)

Register a global Publisher message handler with the agent for the specified SIF object type.

Note agents typically register message handlers with Topics or with Zones instead of with the Agent. The message dispatcher first delivers messages to Topics, then to Zones, and finally to the Agent itself.

In order to receive SIF_Request messages, the agent is expected to be registered as a Provider of one or more object types in at least one zone. This method does not send SIF_Provide messages to any zones.

Parameters:

publisher - An object that implements the Publisher interface to respond to SIF_Request queries received by the agent, where the SIF object type referenced by the request matches the specified objectType. This Publisher will be called whenever a SIF_Request is received and no other object in the message dispatching chain has processed the message.

objectType - A constant from the SIFDTD class that identifies the type of SIF Data Object this Publisher will respond to.

setReportPublisher

public void setReportPublisher(ReportPublisher publisher)

Register a global ReportPublisher message handler with the agent.

Note agents typically register message handlers with Topics or with Zones instead of with the Agent. The message dispatcher first delivers messages to Topics, then to Zones, and finally to the Agent itself. In order to receive SIF_Request messages, the agent is expected to be registered as a Provider of one or more object types in at least one zone. This method does not send SIF_Provide messages to any zones.

Parameters:

publisher - An object that implements the ReportPublisher interface to respond to SIF_Request queries received for SIF_ReportObject objects. This Publisher will be called whenever a request is received and no other object in the message dispatching chain has processed the message.

Since:

ADK 1.5

setSubscriber

public void setSubscriber(Subscriber subscriber)

Register a global Subscriber message handler with the agent for all SIF object types.

Note agents typically register message handlers with Topics or with Zones instead of with the Agent. The message dispatcher first delivers messages to Topics, then to Zones, and finally to the Agent itself.

In order to receive SIF_Event messages, the agent is expected to be registered as a Subscriber of one or more object types in at least one zone. This method does not send SIF_Subscribe messages to any zones.

Parameters:

subscriber - An object that implements the Subscriber interface to respond to SIF_Event notifications received by the agent. This object will be called whenever a SIF_Event is received and no other object in the message dispatching chain has processed the message.

setSubscriber

public void setSubscriber(Subscriber subscriber,
                          ElementDef objectType)

Register a global Subscriber message handler with this agent for the specified SIF object type and only for the default SIF Context

Note agents typically register message handlers with Topics or with Zones instead of with the Agent. The message dispatcher first delivers messages to Topics, then to Zones, and finally to the Agent itself.

In order to receive SIF_Event messages, the agent is expected to be registered as a Subscriber of one or more object types in at least one zone. This method does not send SIF_Subscribe messages to any zones.

Parameters:

subscriber - An object that implements the Subscriber interface to respond to SIF_Event notifications received by the agent, where the SIF object type referenced by the request matches the specified objectType. This Subscriber will be called whenever a SIF_Event is received and no other object in the message dispatching chain has processed the message.

objectType - A constant from the SIFDTD class that identifies the type of SIF Data Object this Subscriber will respond to.

See Also:

Provisioner.setSubscriber(Subscriber, ElementDef, SubscriptionOptions), Topic.setSubscriber(Subscriber, SubscriptionOptions)

setQueryResults

public void setQueryResults(QueryResults queryResults)

Register a global QueryResults message handler with this agent for all SIF object types and only for the default SIF Context

Note agents typically register message handlers with Topics or with Zones instead of with the Agent. The message dispatcher first delivers messages to Topics, then to Zones, and finally to the Agent itself.

Parameters:

queryResults - An object that implements the QueryResults interface to respond to SIF_Response query results received by the agent. This object will be called whenever a SIF_Response is received and no other object in the message dispatching chain has processed the message.

See Also:

Provisioner.setQueryResults(QueryResults), Topic.setQueryResults(QueryResults, QueryResultsOptions)

setQueryResults

public void setQueryResults(QueryResults queryResults,
                            ElementDef objectType)

Register a global QueryResults message handler object with this agent for the specified SIF object type and only for the default SIF Context

Note agents typically register message handlers with Topics or with Zones instead of with the Agent. The message dispatcher first delivers messages to Topics, then to Zones, and finally to the Agent itself.

Parameters:

queryResults - An object that implements the QueryResults interface to respond to SIF_Response query results received by the agent, where the SIF object type referenced by the request matches the specified objectType. This QueryResults object will be called whenever a SIF_Response is received and no other object in the message dispatching chain has processed the message.

objectType - A constant from the SIFDTD class that identifies the type of SIF Data Object this QueryResults message handler will respond to.

See Also:

Provisioner.setQueryResults(QueryResults, ElementDef, QueryResultsOptions), Topic.setQueryResults(QueryResults, QueryResultsOptions)

getPublisher

public Publisher getPublisher(SIFContext context,
                              ElementDef objectType)

Gets the global Publisher message handler registered with the Agent for the specified SIF object type

Parameters:

context - The SIF context to look up the Publisher handler for. The default implementation of Agent only returns handlers for SIFContext.DEFAULT

objectType - A SIFDTD constant identifying a SIF Data Object type (e.g. SIFDTD.STUDENTPERSONAL)

Returns:

The Publisher message handler registered for this object type by the agent when it called the setPublisher method, or null if no Publisher has been registered for the specified object type.

getReportPublisher

public ReportPublisher getReportPublisher(SIFContext context)

Gets the global ReportPublisher message handler registered with the Agent.

Parameters:

context - The SIF context to look up the ReportPublisher handler for. The default implementation of Agent only returns handlers for SIFContext.DEFAULT

Returns:

The ReportPublisher message handler registered by the agent when it called the setReportPublisher method, or null if no ReportPublisher has been registered

Since:

ADK 1.5

getSubscriber

public Subscriber getSubscriber(SIFContext context,
                                ElementDef objectType)

Gets the global Subscriber message handler registered with the Agent for the specified SIF object type.

Parameters:

context - The SIF context to look up the Subscriber handler for. The default implementation of Agent only returns handlers for SIFContext.DEFAULT

objectType - A SIFDTD constant identifying a SIF Data Object type (e.g. SIFDTD.STUDENTPERSONAL)

Returns:

The Subscriber registered for this object type by the agent when it called the setSubscriber method, or null if no Subscriber has been registered for the specified object type.

getQueryResults

public QueryResults getQueryResults(SIFContext context,
                                    ElementDef objectType)

Gets the global QueryResults message handler registered with the Agent for the specified SIF object type.

Parameters:

context - The SIF context to look up the QueryResults handler for. The default implementation of Agent only returns handlers for SIFContext.DEFAULT

objectType - A SIFDTD constant identifying a SIF Data Object type (e.g. SIFDTD.STUDENTPERSONAL)

Returns:

The QueryResults object registered for this object type by the agent when it called the setQueryResults method, or null if no QueryResults object has been registered for the specified object type.

addMessagingListener

public 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

public void removeMessagingListener(MessagingListener listener)

Remove a MessagingListener previously registered with the addMessagingListener method.

Parameters:

listener - a MessagingListener implementation

getMessagingListeners

public java.util.List<MessagingListener> getMessagingListeners()

Return a list of all MessagingListeners registered with the agent

purgeQueue

public void purgeQueue(boolean incoming,
                       boolean outgoing)
                throws ADKException

Purge all pending incoming and/or outgoing messages from this agent's queue. Affects all zones with which the agent is currently connected. See also the Topic.purgeQueue and Zone.purgeQueue methods to purge all zones associated with a topic 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

makeGUID

public static java.lang.String makeGUID()

Utility method to generate a GUID for SIF Data Objects and messages

Returns:

A GUID

See Also:

GUIDGenerator

setErrorHandler

public void setErrorHandler(UndeliverableMessageHandler handler)

Sets the UndeliverableMessageHandler to be called when a dispatching error occurs on a zone but no handler is registered with that 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

public UndeliverableMessageHandler getErrorHandler()

Gets the UndeliverableMessageHandler for this agent.

See Also:

setErrorHandler(com.edustructures.sifworks.UndeliverableMessageHandler)

getLog

public static org.apache.log4j.Logger getLog()

Gets the root Log4j Category for this agent.

getLog

public static org.apache.log4j.Logger getLog(Zone zone)

Gets the Log4j Category for a specific zone.

getServerLog

public static ServerLog getServerLog()

Gets the agent-global ServerLog instance.

Agents that wish to customize server-side logging may call this method to obtain the global Agent ServerLog instance. Call any of the following methods to set up the chain of loggers that will be inherited by all Zones:

• addLogger
• removeLogger
• clearLoggers
• getLoggers

Unlike client-side logging, server logging requires a connection to a Zone Integration Server. Because the current SIF 1.x infrastructure does not allow connections to servers independent of a zone, the logging methods of ServerLog are useful only when called within the context of a zone. Therefore, calling any of the logging methods on the ServerLog instance returned by this method will result in an IllegalStateException. This method is provided only to set up the ServerLog logger chain at the global Agent level.

Returns:

The agent's ServerLog instance

Since:

ADK 1.5

getServerLog

public static ServerLog getServerLog(Zone zone)

Gets the ServerLog for a specific zone.

This form of getServerLog is provided for consistency with the getLog method. Note you may also call the Zone.getServerLog method directly to obtain a ServerLog for for a zone.

Parameters:

zone - The zone to obtain a ServerLog instance for

Returns:

The ServerLog instance for the zone