The ADK is best characterized as a high-level Java class
framework as opposed to a set of programming APIs. As a class framework, it
places certain roles and responsibilities on your application and others on the
framework itself. In general, the ADK takes care of all of the details of the
SIF infrastructure, messaging, and data encapsulation while your agent handles
the business logic and data manipulation that is unique to your application.
Note the ADK does not contain any database or user interface
classes as these are outside the scope of a SIF class framework.
Agent Responsibilities
When writing an agent with the ADK, you're typically
responsible for the following:
- Implement
an Agent Class
Your agent should derive a class from the ADK's abstract Agent class. The Agent
class is usually where the main program entry point is found and where startup
and shutdown tasks are centralized.
- Implement
Message Handlers
The ADK interprets and dispatches incoming SIF messages to one or more message handler classes implemented by
your agent. A message handler is nothing more than a Java class that implements
the Subscriber, Publisher, or QueryResults interfaces (and ReportPublisher for Vertical Reporting
agents). Most of these interfaces have one or two methods, so it is easy to
think of message handlers as callback functions.
Because message handlers are interface-based, you have a tremendous amount of
flexibility in the way you organize your code. For example, you could design
message handler classes so that a single class handles SIF messaging for a variety
of object types and from many zones. Or, you could create individual message handlers
to encapsulate each object type supported by your agent, each zone your agent
is connected to, or a combination of both. Regardless of how you choose to
organize your code, the ADK will call your message handler when it receives an
incoming SIF_Event, SIF_Request, or SIF_Response message from the zone integration
server.
- Implement
one or more Subscriber message
handlers if your agent will respond to SIF_Event
messages. When connecting to SIF Zones, the ADK automatically sends a
SIF_Subscribe message for each SIF Data Object for which a Subscriber message handler exists.
- Implement
one or more Publisher message
handlers if your agent will respond to SIF_Request messages. When connecting to
SIF Zones, the ADK automatically sends a SIF_Provide message for each SIF Data
Object for which a Publisher message
handler exists.
- Implement
one or more QueryResults message
handlers if your agent sends SIF_Request messages for data and will process the
resulting SIF_Response query results.
- Implement
one or more ReportPublisher message
handlers if your agent will respond to SIF_Request messages for Vertical
Reporting objects.
- Connect
to SIF Zones
Most agents are designed to connect to one or more SIF Zones at startup, often
by reading a list of zone connection parameters from a configuration file.
(Tip: You can use the AgentConfig class in the com.edustructures.sifworks.tools.cfg
package to read from an XML-based configuration file.) Agents developed with
the ADK can connect to multiple zones concurrently. When connecting to a zone,
the class framework takes care of sending the appropriate SIF provisioning messages
(SIF_Register, SIF_Subscribe, and SIF_Provide) to the server based on the
message handlers you have implemented. For instance, if you've implemented a Subscriber message handler to respond to
StudentPersonal SIF_Events, the ADK will automatically send a SIF_Subscribe for
StudentPersonal each time it connects to a zone.
- Event
Reporting
Your agent is responsible for detecting changes in the application's database
(or working with the back-end application or its database to be notified when
changes occur) and reporting add, change, and delete events to zones via a
SIF_Event message. This is done by preparing an Event
object and passing it to the Zone.reportEvent
method on the zone to which the data is published.
- Managing
SIF RefIds
Your agent is responsible for keeping track of the SIF RefIds that it
receives for objects or that it creates for new objects. Although the ADK
provides a utility function to generate GUIDs, it does not provide a repository
for RefIds storage. This application-specific functionality is the responsibility
of your agent.