com.edustructures.sifworks
Class SIFResponseSender

java.lang.Object
  com.edustructures.sifworks.SIFResponseSender

public class SIFResponseSender
extends java.lang.Object

Helper class to send SIF_Response messages when an agent defers automatic sending of responses in its implementation of the Publisher.onRequest message handler. This class is designed to be used when the DataObjectOutputStream.deferResponse() method is called during SIF_Request processing, and must be used outside of the Publisher.onRequest message handler.

By design, the ADK automatically sends one or more SIF_Response messages to the zone when control is returned from the Publisher.onRequest message handler. SIF_Responses are sent in a background thread without any further intervention on the agent's part. The ADK takes care of proper data object rendering and packetizing based on the parameters of the SIF_Request message, and includes a SIF_Error element in the payload if an exception is thrown from the onRequest method.

Although this behavior is convenient and very appropriate for most agent implementations, there are cases when agents require greater control over SIF Request & Response messaging. Specifically, agents sometimes need the ability to decouple SIF_Response processing from SIF_Request processing. For example, implementing the SIF 1.5 StudentLocator message choreography may require that SIF_Response messages are sent hours or days after the initial SIF_Request is received. Or, an agent might queue requests in a database table and work on them later when it has available resources. Both of these scenarios can be achieved by calling the DataObjectOutputStream.deferResponse() method on the DataObjectOutputStream passed to the Publisher.onRequest message handler. This method signals the ADK to ignore any SIFDataObjects written to the stream and to defer the sending of SIF_Response messages. The agent must send its own SIF_Response messages at a later time by using this SIFResponseSender helper class

To use this class,

• When the agent is ready to send SIF_Response messages for a SIF_Request that was received at an earlier time, instantiate a SIFResponseSender.
• Call the open(com.edustructures.sifworks.Zone, java.lang.String, java.lang.String, com.edustructures.sifworks.SIFVersion, int, com.edustructures.sifworks.ElementDef[]) method and pass it the Zone you wish to send SIF_Response messages to. You must also pass the SIF_Version and SIF_MaxBufferSize value from the original SIF_Request message. (Be sure to obtain these values from the SIFMessageInfo parameter in your Publisher.onRequest implementation so you can pass them to the open(com.edustructures.sifworks.Zone, java.lang.String, java.lang.String, com.edustructures.sifworks.SIFVersion, int, com.edustructures.sifworks.ElementDef[]) method when using this class.)
• Repeatedly call the write(SIFDataObject) method, once for each SIFDataObject that should be included in the SIF_Response stream
• Call the write(SIF_Error) method to include a SIF_Error element in the SIF_Response stream
• When finished, call the close() method. The ADK will automatically package the objects into one or more SIF_Response packets in the same way it does for normal request/response processing via the Publisher.onRequest method.

Since:

ADK 1.5.1

Constructor Summary

SIFResponseSender()

Method Summary

void	close() Close the stream and send one or more SIF_Response packets to the zone.
void	open(Zone zone, java.lang.String sifRequestMsgId, java.lang.String sifRequestSourceId, SIFVersion sifVersion, int maxBufferSize, ElementDef[] fieldRestrictions) Open the SIFResponseSender to send SIF_Response messages to a specific zone.
void	write(SIF_Error error) Write a SIF_Error to the output stream
void	write(SIFDataObject sdo) Write a SIFDataObject to the output stream

Methods inherited from class java.lang.Object

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

Constructor Detail

SIFResponseSender

public SIFResponseSender()

Method Detail

open

public void open(Zone zone,
                 java.lang.String sifRequestMsgId,
                 java.lang.String sifRequestSourceId,
                 SIFVersion sifVersion,
                 int maxBufferSize,
                 ElementDef[] fieldRestrictions)
          throws ADKException

Open the SIFResponseSender to send SIF_Response messages to a specific zone.

Parameters:

zone - The zone to send messages to

sifRequestMsgId - The SIF_MsgId from the original SIF_Request message. You can obtain this by calling SIFMessageInfo.getMsgId() on the SIFMessageInfo parameter passed to the Publisher.onRequest method. NOTE: Do not call SIFMessageInfo.getSIFRequestMsgId() as it will return a null value and is only intended to be called on SIF_Response messages.

sifRequestSourceId - The SIF_SourceId from the original SIF_Request message. You can obtain this by calling SIFMessageInfo.getSourceId() on the SIFMessageInfo parameter passed to the Publisher.onRequest method.

sifVersion - The SIF_Version value from the original SIF_Request message. You can obtain this by calling com.edustructures.sifworks.SIFMessageInfo#getSIFRequestVersion on the SIFMessageInfo parameter passed to the Publisher.onRequest method.

maxBufSize - The SIF_MaxBufferSize value from the original SIF_Request message. You can obtain this by calling SIFMessageInfo.getMaxBufferSize() on the SIFMessageInfo parameter passed to the Publisher.onRequest method.

fieldRestrictions - An optional array of ElementDef constants, obtained or reconstructed from the Query.getFieldRestrictions() method from the original SIF_Request, that identify the subset of SIF elements to include in the data objects written to SIF_Response messages. If this array is provided, data objects will only have those elements specified; otherwise data objects contain all of their elements.

Throws:

java.lang.IllegalArgumentException - is thrown if any of the parameter are invalid

ADKException - is thrown if an error occurs preparing the output stream

write

public void write(SIFDataObject sdo)
           throws ADKException

Write a SIFDataObject to the output stream

Throws:

ADKException

write

public void write(SIF_Error error)
           throws ADKException

Write a SIF_Error to the output stream

Parameters:

error - A SIF_Error instance

Throws:

ADKException

close

public void close()
           throws ADKException

Close the stream and send one or more SIF_Response packets to the zone.

Throws:

ADKException