com.adventnet.management
Interface ProtocolProvider

public interface ProtocolProvider

This is the interface which must be implemented by the ProtocolProvider(s) for plugging a particular protocol into the ManagementServer . The Protocol Provider implementation is basically a wrapper around the Protocol API's which can communicate with the respective device agents.

Field Summary

static int	ASYNC_COMM This is the constant used to specify asynchronous communication mode between ProtocolProvider and Device agent .
static int	SYNC_COMM This is the constant used to specify synchronous communication mode between ProtocolProvider and Device agent .

Method Summary

void	addMSCallbackListener(MSCallbackListener msCBlistener) This method is used by the ManagemntServer implementing MSCallbackListener to register for being notified each time the ProtocolProvider gets a response.
void	addMSConnectionListener(MSConnectionListener msConListener) This method is used by the ManagemntServer implementing MSConnectionListener to register for being notified each time the connection between the device and ManagementServer goes DOWN .
void	addMSNotifyListener(MSNotifyListener l) This method is used by the ManagemntServer implementing MSNotifyListener to register for being notified each time the ProtocolProvider gets an Event PDU.
int[]	checkResponses() This will return the array of request ids of the responses received by the Protocol Provider from the device agent.
void	close() Close all the resources used by the ProtocolProvider .
void	combineSend(Property[] request) This method should convert the list of generic request Property(s) into a single PDU for the corresponding protocol and send it to the device agent via the Protocol API .
java.lang.String	establishSession(Property p) Establish session for communication with device based on the parameters in the request Property .
java.util.Vector	filterProperties(java.lang.Object pdu, java.util.Vector props) This method will be called by the ManagementServer to filter only the event request Property(s) which match the event PDU recieved by the ProtocolProvider.
int	genReqID() This will generate a unique request id for the request to be sent through this provider.
int	getCommunicationMode() Gets the the request response transaction mode between ProtocolProvider and device agent (asynchronous or synchronous) .
java.lang.String	getErrorString(byte errstat) This method should convert protocol specific error status to a readable string message.
boolean	getShareSessions() This method gets the mode whether the sessions towards the same devices are shared among Management clients for connection oriented protocols.
ManagementServerResultEvent	receive(int reqid) Gets the result for send() as ManagementServerResultEvent for the given reqid returned for send().
void	registerForNotification(Property p) The Provider should register for recieving notifications based on the parameters in Property .
void	removeMSCallbackListener(MSCallbackListener msCBListener) Unregister from being notified when the Provider recieves responses.
void	removeMSConnectionListener(MSConnectionListener l) Unregister from being notified when the Provider recieves connection notifications.
void	removeMSNotifyListener(MSNotifyListener l) Unregister from being notified when the Provider recieves notifications.
int	send(Property request) This method should convert the generic request Property to a PDU for the corresponding protocol and send it to the device agent via the Protocol API.
void	sendAction(Property prop) This method sends a generic request Property after converting it into a PDU for the corresponding protocol and send it to the device agent via the Protocol API .
void	setCommunicationMode(int mode) Sets the the request response transaction mode between ProtocolProvider and device agent (asynchronous or synchronous) .
void	setDebug(boolean debug) The provider should print debug messages and the PDU(s) on the console when this option is enabled.
void	setShareSessions(boolean shareDeviceSessionMode) This method sets the mode whether the sessions towards the same devices can be shared among Management clients for connection oriented protocols.
ManagementServerResultEvent	syncSend(Property request) This method should convert the generic request Property to a PDU for the corresponding protocol and send it to the device agent via the Protocol API .
void	terminateSession(Property p) Disconnect session from communication with device based on the parameters in the request Property .
void	unregisterForNotification(Property p) Unregister From Recieving Notifications based on the parameters in the request Property .

Field Detail

ASYNC_COMM

public static final int ASYNC_COMM

This is the constant used to specify asynchronous communication mode between ProtocolProvider and Device agent .

SYNC_COMM

public static final int SYNC_COMM

This is the constant used to specify synchronous communication mode between ProtocolProvider and Device agent .

Method Detail

receive

public ManagementServerResultEvent receive(int reqid)

Gets the result for send() as ManagementServerResultEvent for the given reqid returned for send(). To be deprecated shortly. Provider implementations can have a dummy implementation for this method.

Parameters:

reqid - - integer representing the request id.

Returns:

ManagementServerResultEvent object.

send

public int send(Property request)
         throws java.lang.Exception

This method should convert the generic request Property to a PDU for the corresponding protocol and send it to the device agent via the Protocol API. If the request is send successfully to the device agent the Protocol Provider(s) should return the requestId set in the Property request passed as argument. Otherwise the ProtocolProvider can return a negative value. The provider implementation should convert the response received into a generic ManagementServerResultEvent and set the RequestId in the result. This RequestId should be the same as the requestId set in Property.getRequestId() submitted by the ManagementServer using ProtocolProvider.send(Property). The result is then given asynchronously through the registered MSCallbackListener interface.

Parameters:

request - - The request to be sent to the device agent.

Returns:

- An integer for identifying the request.

syncSend

public ManagementServerResultEvent syncSend(Property request)
                                     throws java.lang.Exception

This method should convert the generic request Property to a PDU for the corresponding protocol and send it to the device agent via the Protocol API . The provider blocks until the response is recieved and the responses are given to the ManagementServer synchronously.

Parameters:

request - - The request to be sent to the protocol agent.

Returns:

ManagementServerResultEvent object - Generic result .

getCommunicationMode

public int getCommunicationMode()

Gets the the request response transaction mode between ProtocolProvider and device agent (asynchronous or synchronous) . To be deprecated shortly. Provider implementations can have a dummy implementation for this method.

Returns:

- SYNC_COMM / ASYNC_COMM.

setCommunicationMode

public void setCommunicationMode(int mode)
                          throws java.lang.Exception

Sets the the request response transaction mode between ProtocolProvider and device agent (asynchronous or synchronous) . To be deprecated shortly. Provider implementations can have a dummy implementation for this method.

Parameters:

- - SYNC_COMM / ASYNC_COMM.

checkResponses

public int[] checkResponses()

This will return the array of request ids of the responses received by the Protocol Provider from the device agent. This method will be used in a case when the request response transactions between ManagementServer and ProtocolProvider is asynchronous. The response for particular request id can be recieved using receive(). To be deprecated shortly. Provider implementations can have a dummy implementation for this method.

Returns:

an array of request ids corresponding to the responses received.

See Also:

receive(int)

addMSCallbackListener

public void addMSCallbackListener(MSCallbackListener msCBlistener)
                           throws java.lang.Exception

This method is used by the ManagemntServer implementing MSCallbackListener to register for being notified each time the ProtocolProvider gets a response.

Parameters:

msCBlistener - - MSCallbackListener object for which the responses are given in asynchronous mode.

addMSNotifyListener

public void addMSNotifyListener(MSNotifyListener l)
                         throws java.lang.Exception

This method is used by the ManagemntServer implementing MSNotifyListener to register for being notified each time the ProtocolProvider gets an Event PDU.

Parameters:

l - - MSNotifyListener object for which the notifications are given.

removeMSNotifyListener

public void removeMSNotifyListener(MSNotifyListener l)

Unregister from being notified when the Provider recieves notifications.

Parameters:

l - - MSNotifyListener object.

addMSConnectionListener

public void addMSConnectionListener(MSConnectionListener msConListener)
                             throws java.lang.Exception

This method is used by the ManagemntServer implementing MSConnectionListener to register for being notified each time the connection between the device and ManagementServer goes DOWN .

Parameters:

msConListener - - MSConnectionListener object for which the connection notifications are given.

removeMSConnectionListener

public void removeMSConnectionListener(MSConnectionListener l)

Unregister from being notified when the Provider recieves connection notifications.

Parameters:

l - - MSNotifyListener object.

removeMSCallbackListener

public void removeMSCallbackListener(MSCallbackListener msCBListener)

Unregister from being notified when the Provider recieves responses.

Parameters:

msCBlistener - - MSCallbackListener object.

genReqID

public int genReqID()

This will generate a unique request id for the request to be sent through this provider.

Returns:

unique request id which will be used to set the request id for the request to be sent. To be deprecated as request Id's are now being generated by ManagementServer itself. Provider implementations can have a dummy implementation for this method.

setDebug

public void setDebug(boolean debug)

The provider should print debug messages and the PDU(s) on the console when this option is enabled.

Parameters:

debug - - boolean representing the debug mode as true/false.

getErrorString

public java.lang.String getErrorString(byte errstat)

This method should convert protocol specific error status to a readable string message. Returns the Error in string format from the byte errorStatus , which is returned as part of response . To be deprecated shortly. Provider implementations can have a dummy implementation for this method.

Parameters:

errstat - - byte representing the Error Status.

Returns:

Error message as String.

close

public void close()
           throws java.lang.Exception

Close all the resources used by the ProtocolProvider .

registerForNotification

public void registerForNotification(Property p)

The Provider should register for recieving notifications based on the parameters in Property . The provider implementation should convert the event notification from the device to a MSNotification object and set the RequestId in the MSNotification object (This RequestId should be the same requestId in Property.getRequestId() submitted by the ManagementServer using ProtocolProvider.registerForNotification(Property)). The MSNotification object should then be given thru the registered MSNotifyListener

Parameters:

p - - Property containing the necessary attributes for recieving notifications.

unregisterForNotification

public void unregisterForNotification(Property p)

Unregister From Recieving Notifications based on the parameters in the request Property .

Parameters:

p - - Property instance used for Notification registeration.

establishSession

public java.lang.String establishSession(Property p)

Establish session for communication with device based on the parameters in the request Property . This is only for connection oriented protocols. It returns the sessionKey to the Management Server. Protocol Provider maintains the mapping between the session key and the device session object.

Parameters:

p - - Property containing the necessary attributes for establishing the device session.

Returns:

String identifier for the session.

terminateSession

public void terminateSession(Property p)

Disconnect session from communication with device based on the parameters in the request Property . This is only for connection oriented protocols.

Parameters:

p - - Property instance used for establishing the session.

getShareSessions

public boolean getShareSessions()

This method gets the mode whether the sessions towards the same devices are shared among Management clients for connection oriented protocols.

Returns:

true or false

setShareSessions

public void setShareSessions(boolean shareDeviceSessionMode)
                      throws java.lang.Exception

This method sets the mode whether the sessions towards the same devices can be shared among Management clients for connection oriented protocols.

Parameters:

shareDeviceSessionMode - - Share device sessions mode. (true/false) .

combineSend

public void combineSend(Property[] request)
                 throws java.lang.Exception

This method should convert the list of generic request Property(s) into a single PDU for the corresponding protocol and send it to the device agent via the Protocol API . The responses for all the requests are given individually to the ManagementServer asynchronously through MSCallbackListener interface.

Parameters:

requests - - Property Array.

sendAction

public void sendAction(Property prop)
                throws java.lang.Exception

This method sends a generic request Property after converting it into a PDU for the corresponding protocol and send it to the device agent via the Protocol API . No responses are to be given to the ManagementServer .

Parameters:

prop - - Property instance.

filterProperties

public java.util.Vector filterProperties(java.lang.Object pdu,
                                         java.util.Vector props)
                                  throws java.lang.Exception

This method will be called by the ManagementServer to filter only the event request Property(s) which match the event PDU recieved by the ProtocolProvider. The Managment Server allows the Protocol Provider to perform any matching of event registration requests with the recieved device PDU by calling this method with Vector of registered Property(s). The Provider returns only the notification register requests which match this device notification. If the Protocol Provider does not need this request based filtering support it can returns the same vector of Property(s) to the ManagementServer .

Parameters:

pdu - - The event PDU recieved and the Property(s) to be filtered .

props - - The vector of properties registered for this particular event.

Returns:

- The Property(s) matching the event PDU .