Core Classes and Interfaces

The following classes and interfaces are used most frequently in ADK programming. Each is described in greater detail throughout this Guide.

ADK

The com.edustructures.sifworks.ADK class represents the ADK library as a global resource of your agent. It is used to initialize the class framework and to define settings that affect the ADK’s behavior at runtime. You cannot create an instance of this class directly; rather, a global singleton is established when the ADK.initialize method is called. The initialize method is important because it informs the class framework of the version of SIF you will be using and the SIF Data Object – or SDO – libraries to load into memory. Call this method early in your agent startup code.

The ADK class is covered in The ADK Class

Agent

The com.edustructures.sifworks.Agent class represents your SIF Agent. It is the central “application” class of the ADK and generally houses the main program entry point. Agents derive a class from this one and call its methods to handle startup and shutdown tasks and to set global properties that are inherited by each zone the agent connects to.

The Agent class is covered in The Agent Class

Zones

The concept of a SIF Zone is central to the architecture of the Schools Interoperability Framework. A zone is a logical partition in which application integration takes place between two or more SIF Agents. Each zone is managed by a Zone Integration Server like the SIFWorks® Enterprise ZIS. The ADK has the ability to connect to more than one zone at the same time.

Common zone topologies include School Zones, which publish data from a single school; District Zones, which publish data from a single school district; and Aggregate Zones, which publish data from a combination of sources. The administrator of a zone integration server will want the flexibility to create as many zones as needed to model data in a school, district, or agency; the more flexible your agent is in terms of zone topologies the better chance it has of working in any SIF environment. If you restrict your agent to publishing data only to a single “district zone”, for example, it may not work well with other vendors’ agents that are restricted to consuming data from a single “school zone”.  Edustructures strongly encourages developers to support the three types of zones mentioned above for maximum flexibility and scalability.

Zones are represented in the ADK by the com.edustructures.sifworks.Zone inter-face. During agent initialization, agents obtain one or more Zone instances for each SIF Zone the agent will connect to by calling the methods of the ZoneFactory class. The “zone factory” is responsible for creating new Zone instances and keeping track of the zones the agent communicates with during a session. You can obtain a reference to the global ZoneFactory by calling the Agent.getZoneFactory method.

Since Zone is an interface implemented privately by the class framework, it cannot be subclassed. With version 1.1 and later of the ADK, you can associate your own “zone class” with a Zone instance by calling the Zone.setUserData method, and then later retrieve that class with the getUserData method and casting the return value to your class type. This is a common way of organizing your code by zone. 

Topics 

Depending on the requirements of your application, it may make sense to structure the design of the agent code such that SIF messages are processed in a data-centric versus zone-centric fashion. For example, you may wish to process messages related to StudentPersonal objects in the same way regardless of the zone from which those messages originate.

The ADK introduces a concept familiar to publish/subscribe frameworks but missing from the Schools Interoperability Framework infrastructure: the topic. Data-centric agents may perform all publish, subscribe, and query activity via topics, which serve to aggregate messaging activity across multiple zones. Topic instances are obtained from the agent’s TopicFactory. Each Topic represents a single type of SIF Data Object, such as StudentPersonal, LibraryPatronStatus, or BusInfo. By “joining” topics with one or more zones, SIF_Event and SIF_Request messages received from those zones are dispatched to the topic for processing. In this way, your agent’s message handling logic can be centralized and organized in a data-centric rather than a zone-centric way.

Zones and Topics are covered in Zones & Topics

Agent and Transport Properties

The ADK defines a rich set of operational properties that can be configured pro-grammatically or at runtime with the /D Java command-line option. Some properties are used to determine basic agent functionality—such as whether Push or Pull mode is used to communicate with the Zone Integration Server—while others let you fine-tune how the class framework implements the SIF standard. Properties may be set on a zone-by-zone basis; global properties inherited by all zones are defined by the agent class.

SIF Data Objects (SDO) Libraries

The ADK models all SIF Data Objects as object-oriented Java classes. These classes, collectively referred to as the SIF Data Objects libraries, or SDO, exist for top-level object types such as StudentPersonal, LibraryPatronStatus, and BusInfo; for common elements like Name, Address, and PhoneNumber; and for enumerated types, dates, and times. All approved objects from each version of SIF are represented, and in many cases unapproved draft objects are also implemented for early-adopter testing.

A major benefit to the SDO library is its support for parsing and rendering data objects using multiple versions of SIF. For example, an ADK agent can automatically parse and render a SIF 1.0r1 LibraryPatronStatus or SIF 1.1 LibraryPatronStatus object—which differs between the two versions of the specification—without any intervention on your part.

Publishers

A Publisher is a message handler class supplied by your agent to process SIF_Request messages. Publisher is a Java interface that can be implemented by any class of your choosing—typically from your application’s data layer.

By registering one or more Publishers with your agent’s zone and topic classes, you di-rect the ADK to dispatch incoming SIF_Request messages to your application code for processing. Agents typically respond to a SIF_Request by querying records in a local database, then converting those records to one or more SIF Data Objects. You can work with SIF Data Objects programmatically by constructing instances of SIFDataObject classes supplied for each object in SIF, or you can take a more data-driven approach by using static XPath-style mappings read from a configuration file and managed by the Mappings utility class. When responding to SIF_Requests, these objects are sent to an output stream supplied by the class framework, which then packages them into individual SIF_Response messages that are persisted to disk and ultimately delivered to the zone integration server.

ReportPublisher is a special form of the Publisher interface for working with SIF Vertical Reporting objects. Vertical Reporting is available in SIF 1.5 and later.

Publishing with the ADK is covered in Publishing

Subscribers

A Subscriber is a message handler class supplied by your agent to process SIF_Event messages. Subscriber is a Java interface that can be implemented by any class of your choosing—typically from your application’s data layer. 

By registering one or more Subscribers with your agent’s zone and topic classes, you direct the ADK to dispatch incoming SIF_Event messages to your application code for processing. Agents typically respond to SIF_Event messages by updating corres-ponding records in the local application database using the element and attribute val-ues in the SIF Data Object contained in the event payload. You can work with SIF Data Objects programmatically using the SIFDataObject classes supplied for each object in SIF, or you can take a more data-driven approach by using static XPath-style mappings read from a configuration file and managed by the Mappings utility class.

Subscribing with the ADK is covered in Subscribing

Queries and QueryResults

Zone and topic classes provide methods to send SIF_Request queries to a zone or a specific agent in a zone to request SIF Data Objects. The results of a query are received asynchronously as SIF_Response messages. The class framework dispatches these messages to a QueryResults message handler as they are received from the zone inte-gration server. 

Agents typically process SIF_Response messages by converting the SIF Data Objects in the response to database records and importing those records into a local application database. The class framework supplies your message handler a stream from which you can read an arbitrarily large number of SIFDataObject instances from the query response. You can work with SIF Data Objects programmatically using the SIFDataObject classes supplied for each object in SIF, or you can take a more data-driven approach by using static XPath-style mappings read from a configuration file and managed by the Mappings utility class.