com.edustructures.sifworks
Interface Subscriber

public interface Subscriber

The Subscriber message handler interface is implemented by classes that wish to process SIF_Event messages received from a zone. Consult the ADK Developer Guide for more information about message handler interfaces.

About SIF Events

An Event is a notification to subscribing agents that a data object has been added, changed, or deleted in the reporting application's database. In the Schools Interoperability Framework, any agent may report SIF_Event messages for any object, even if that agent is not the authoritative publisher of the object.

Subscribing to SIF Events

Agents that wish to receive SIF_Event messages must register with the zone integration server as a Subscriber of one or more SIF Data Object types. To subscribe to events for a specific object type, register a Subscriber message handler with Zone or Topic instances. When registering Subscribers with zones, repeatedly call the com.edustructures.sifworks.Zone#setSubscriber(Subscriber, ElementDef, int) method for each SIF Data Object type you wish to subscribe to. When registering message handlers with Topics, call the com.edustructures.sifworks.Topic#setSubscriber(Subscriber, int) method once to register with all zones bound to the topic (your Subscriber implementation will be called whenever a SIF_Event is received on any of the zones bound to that topic.) Be sure to specify the ADKFlags.PROV_SUBSCRIBE flag as the last parameter to these methods if you wish the ADK to send a SIF_Subscribe message to the zone when it connects.

When a SIF_Event message is received, it is dispatched to the appropriate Subscriber message handler's onEvent method for processing. Obtain a DataObjectInputStream from the Event instance by calling the Event parameter's Event.getData() method, then repeatedly call the stream's DataObjectInputStream.readDataObject() method to get the next SIFDataObject in the event payload.

For example,

public void onEvent( Event event, Zone zone, MessageInfo info )
{
DataObjectInputStream payload = event.getData();
while( payload.available() ) {
StudentPersonal sp = (StudentPersonal)payload.readDataObject();
switch( event.getAction() ) {
case Event.ADD:
// Add student...
break;
case Event.CHANGE:
// Change student...
break;
case Event.DELETE:
// Delete student...
break;
}
}
}

If onEvent returns successfully, the ADK acknowledges the SIF_Event message with a success SIF_Ack. If a SIFException or other ADKException is thrown, the ADK acknowledges the SIF_Event with an error SIF_Ack using the error category, code, and description from the exception.

Since:

ADK 1.0

Method Summary

void	onEvent(Event event, Zone zone, MessageInfo info) Respond to a SIF_Event received from a zone.

Method Detail

onEvent

void onEvent(Event event,
             Zone zone,
             MessageInfo info)
             throws ADKException

Respond to a SIF_Event received from a zone.

Parameters:

event - Encapsulates the SIF_Event message and the SIFDataObjects contained within

zone - The zone from which this event originated

info - Information about the SIF_Event message envelope and header

Throws:

ADKException - may be thrown to return an error SIF_Ack to the zone. Throw a SIFException for control over the error category, code, description and detailed description. If no exception is raised and this method returns successfully, the ADK returns a success SIF_Ack to the zone.