systemic.sif.sifcommon.subscriber
Class BaseSubscriber

java.lang.Object
  extended by systemic.sif.sifcommon.BaseInfo
      extended by systemic.sif.sifcommon.subscriber.BaseSubscriber
All Implemented Interfaces:
java.lang.Runnable, openadk.library.QueryResults, openadk.library.Subscriber

public abstract class BaseSubscriber
extends BaseInfo
implements openadk.library.Subscriber, openadk.library.QueryResults, java.lang.Runnable

All subscribers should extend this class. It ensures that resources are dealt with correctly.

Author:
Joerg Huber

Constructor Summary
BaseSubscriber(java.lang.String subscriberID)
          This class is a basic initialiser of a subscriber.
 
Method Summary
 void debugOnEvent(openadk.library.Event event, openadk.library.Zone zone, openadk.library.MessageInfo messageinfo)
          Used for debugging purpose.
 void debugOnQueryResults(openadk.library.DataObjectInputStream dataobjectinputstream, openadk.library.infra.SIF_Error sif_error, openadk.library.Zone zone, openadk.library.MessageInfo messageinfo)
          Used for debugging purpose.
abstract  void finalise()
          This method should release all resources associated with the given subscriber.
 openadk.library.QueryResultsOptions getQueryResultsOptions()
           
 openadk.library.SubscriptionOptions getSubscriptionOptions()
           
 void onEvent(openadk.library.Event event, openadk.library.Zone zone, openadk.library.MessageInfo msgInfo)
          Default implementation of the SIFWorks ADK onEvent() method.
 void onQueryPending(openadk.library.MessageInfo msgInfo, openadk.library.Zone zone)
           
 void onQueryResults(openadk.library.DataObjectInputStream dataobjectinputstream, openadk.library.infra.SIF_Error sifError, openadk.library.Zone zone, openadk.library.MessageInfo msgInfo)
          Default implementation of the SIFWorks ADK onQueryResults() method.
abstract  void processEvent(SIFEvent sifEvent, openadk.library.Zone zone, MappingInfo mappingInfo, java.lang.String consumerID)
          This method will process the given event.
abstract  void processResponse(openadk.library.SIFDataObject sifObject, openadk.library.Zone zone, MappingInfo mappingInfo, java.lang.String consumerID)
          This method will process the given SIF Object.
 void provision(openadk.library.Zone zone)
          Allows this data handler class to provision itself with the zone.
 void reportSIFError(openadk.library.infra.SIF_Error sifError, openadk.library.Zone zone)
          This method deals with an error that has been received from the zone in relation to a SIF response.
 void run()
          This method is all that is needed to run the subscriber in its own thread.
 void setQueryResultsOptions(openadk.library.QueryResultsOptions queryResultsOptions)
           
 void setSubscriptionOptions(openadk.library.SubscriptionOptions subscriptionOptions)
           
 void shutdownSubscriber()
          This method shuts down this subscriber gracefully.
 void startConsumers()
          This method starts up all the consumers for this subscriber.
 
Methods inherited from class systemic.sif.sifcommon.BaseInfo
getAgentConfig, getAgentID, getAgentProperties, getAgentProperty, getApplicationID, getDtd, getFrameworkProperties, getId, getMappings, getZoneByID, getZones, isValidZone, setAgentConfig, setAgentID, setAgentProperties, setApplicationID, setDtd, setFrameworkProperties, setId, setMappings, setZones
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BaseSubscriber

public BaseSubscriber(java.lang.String subscriberID)
This class is a basic initialiser of a subscriber. No properties except the subscriberID and DTD for the applicable subscriber are expected to be set in this method. The BaseAgent will call this method first, then set appropriate properties of the BaseInfo class. Finally the BaseAgent will call the startConsumers() method to complete the initialisation process of a subscriber.

Parameters:
subscriberID - The unique ID of this subscriber. Ideally this is the class name but this is not necessary. This ID is used throughout the SIFCommon Framework classes to access properties in the SIFAgent.properties file. This ID must match the reference in this property file for the given subscriber.
Method Detail

processEvent

public abstract void processEvent(SIFEvent sifEvent,
                                  openadk.library.Zone zone,
                                  MappingInfo mappingInfo,
                                  java.lang.String consumerID)
                           throws openadk.library.ADKException
This method will process the given event. Mappings can be used of the mappingInfo.mappingCtx is not null. It is up to the implementor of this method to check that property before any mapping is attempted. The mappingCtx is an inbound mapping context as expected for subscribers.

This method is being called as part of the default implementation of the onEvent() method of the SIFworks ADK.

Parameters:
sifEvent - The SIF Event to be processed.
zone - The Zone that has received the event.
mappingInfo - The mapping info that can be used if mapping is available. Note that property mappingCtx of this parameter can be null if there is no mapping available for the given subscriber and its SIF Object it deals with (ie. No mapping for StudentPersonal).
consumerID - The ID of the consumer that processes this event. Because the subscriber uses a multi-threaded consumer model it can be useful to know which particular consumer is asked to process this event.
Throws:
openadk.library.ADKException - Any issues that arise with the processing of the event that need to be captured and logged.

processResponse

public abstract void processResponse(openadk.library.SIFDataObject sifObject,
                                     openadk.library.Zone zone,
                                     MappingInfo mappingInfo,
                                     java.lang.String consumerID)
                              throws openadk.library.ADKException
This method will process the given SIF Object. Mappings can be used of the mappingInfo.mappingCtx is not null. It is up to the implementor of this method to check that property before any mapping is attempted. The mappingCtx is an inbound mapping context as expected for subscribers.

This method is being called as part of the default implementation of the onRequest() method of the SIFworks ADK.

Parameters:
sifObject - The SIF Object to be processed.
zone - The Zone that has received the SIF Object.
mappingInfo - The mapping info that can be used if mapping is available. Note that property mappingCtx of this parameter can be null if there is no mapping available for the given subscriber and its SIF Object it deals with (ie. No mapping for StudentPersonal).
consumerID - The ID of the consumer that processes this SIF Message. Because the subscriber uses a multi-threaded consumer model it can be useful to know which particular consumer is asked to process this SIF Message.
Throws:
openadk.library.ADKException - Any issues that arise with the processing of the SIF Object that need to be captured and logged.

finalise

public abstract void finalise()
This method should release all resources associated with the given subscriber. It will be called as part of the shutdown process of the agent.


run

public final void run()
This method is all that is needed to run the subscriber in its own thread. The thread is executed at given intervals driven by a property in the SIFCommonFramework property file. The interval/frequency defined in there is used to determine how often this thread is run. If some other mechanism (ie. DB) drives the sync() method such as check if a sync really is required then this needs to be coded in each subscriber specifically by means of overriding the sync(zone) or syncAllZones() method. For example if no sync is needed at all, simply override the syncAllZones() and null it out. If a sync is not required for a specific zone the override the sync(zone) method so that no sync is called for a specific zone.

Specified by:
run in interface java.lang.Runnable

startConsumers

public final void startConsumers()
                          throws java.util.concurrent.ExecutionException
This method starts up all the consumers for this subscriber. This cannot be done as part of the constructor of this class because at that time not all properties of the BaseInfo class are populated and the startup of the consumers requires some of the properties.

This class requires the 'frameworkProperties' of the BaseInfo to be set, otherwise an ExecutionException will be thrown.

Throws:
java.util.concurrent.ExecutionException - Issue with starting the consumers of missing properties in the BaseInfo class.

provision

public void provision(openadk.library.Zone zone)
               throws openadk.library.ADKException
Allows this data handler class to provision itself with the zone.

Provisioning involves notifying the zone of any objects this class subscribes, or provides data for, or whether this class should be notified of SIF_Responses for a specific data type.

Parameters:
zone - The representation of a SIF Zone inside the ADK
Throws:
openadk.library.ADKException

onQueryPending

public void onQueryPending(openadk.library.MessageInfo msgInfo,
                           openadk.library.Zone zone)
                    throws openadk.library.ADKException
Specified by:
onQueryPending in interface openadk.library.QueryResults
Throws:
openadk.library.ADKException

onEvent

public final void onEvent(openadk.library.Event event,
                          openadk.library.Zone zone,
                          openadk.library.MessageInfo msgInfo)
                   throws openadk.library.ADKException
Default implementation of the SIFWorks ADK onEvent() method. Do not call this method from any sub-classes.

Specified by:
onEvent in interface openadk.library.Subscriber
Throws:
openadk.library.ADKException

onQueryResults

public final void onQueryResults(openadk.library.DataObjectInputStream dataobjectinputstream,
                                 openadk.library.infra.SIF_Error sifError,
                                 openadk.library.Zone zone,
                                 openadk.library.MessageInfo msgInfo)
                          throws openadk.library.ADKException
Default implementation of the SIFWorks ADK onQueryResults() method. Do not call this method from any sub-classes.

Specified by:
onQueryResults in interface openadk.library.QueryResults
Throws:
openadk.library.ADKException

reportSIFError

public void reportSIFError(openadk.library.infra.SIF_Error sifError,
                           openadk.library.Zone zone)
This method deals with an error that has been received from the zone in relation to a SIF response. This method is called as part of the SIFWorks ADK onQueryResults() method. The current implementation of the reportSIFError() is simply to log the error. If a different behaviour is required the the sub-class can override this method to meet its requirements.

Parameters:
sifError - The SIF Error that has been received. This value is not null.
zone - The zone for which the error has been received.

shutdownSubscriber

public final void shutdownSubscriber()
This method shuts down this subscriber gracefully. It is called by the Agent when a shutdown request has been issued to the agent. It is not expected that sub-classes of this class call this method. Specifics of the sub-class shutdowns must be handled in the finalise() method of the sub-class. The finalise() method is called as part of this method.


getSubscriptionOptions

public openadk.library.SubscriptionOptions getSubscriptionOptions()

setSubscriptionOptions

public void setSubscriptionOptions(openadk.library.SubscriptionOptions subscriptionOptions)

getQueryResultsOptions

public openadk.library.QueryResultsOptions getQueryResultsOptions()

setQueryResultsOptions

public void setQueryResultsOptions(openadk.library.QueryResultsOptions queryResultsOptions)

debugOnQueryResults

public void debugOnQueryResults(openadk.library.DataObjectInputStream dataobjectinputstream,
                                openadk.library.infra.SIF_Error sif_error,
                                openadk.library.Zone zone,
                                openadk.library.MessageInfo messageinfo)
                         throws openadk.library.ADKException
Used for debugging purpose. It simply writes the SIFObjects from the dataobjectinputstream to the log file.

Throws:
openadk.library.ADKException

debugOnEvent

public void debugOnEvent(openadk.library.Event event,
                         openadk.library.Zone zone,
                         openadk.library.MessageInfo messageinfo)
                  throws openadk.library.ADKException
Used for debugging purpose. It simply writes the SIFObjects from the event to the log file.

Throws:
openadk.library.ADKException