Extending SAS

 

Three interfaces namely SAServerClient, SASessionClient, and SasLogInterface are implemented to add custom functionality. Only one class of SAServerClient or SASessionClient should be registered with SAServer. If both the interfaces are registered, the value returned from the methods common to both interfaces, such as requestPDU() and responsePDU(), are overwritten. In this case, the value returned from the implementation file of SASessionClient overwrites the value returned from that of SAServerClient. These two interfaces allow far more flexibility in implementing SAS enhancements. The classes implementing the interfaces can be specified by command line options while starting the SAServer.

 

Interface SAServerClient

 

This allows instantiation of a custom class when SAS is started. The methods in this interface are the following.

 

Method Purpose

public void init(String applet_dir, String webserver_rootDir);

This method is called when SAServer starts. This assigns the applet directory and the web-server root directory. The applet_dir is an applet directory in which the file SASPort.html is written. SASPort.html is the file which contains the port number where the SAServer is started.

public void initSession(InetAddress applet_addr, int applet_port, SASession session);

This method is called when a new SASession is opened. The applet_addr is the client's address and applet_port is the client's port where the SASession is started.

public int open(int port);

This method is called when the client opens a UDP port. Typically, the port is 0, which implies a system assigned UDP port. For listening traps or SNMP PDUs, a specific port can be specified. The return value is used for custom port assignment, if required.

public SnmpPDU requestPDU(SnmpPDU pdu);

This method is called before sending any request. The PDU is sent to the agent, which can be modified as required by the custom class.

For example, if the user wants to customize the request so that it is always sent to the "localhost" the following code should be used.

pdu.setRemoteHost("localhost")

public SnmpPDU responsePDU(SnmpPDU pdu);

This method is called after receiving a response on the server side. This is the response PDU from the agent, which can be modified as required.

public byte[] clientCall(byte data[]);

This method allows the applet client to invoke a method on the server. The corresponding method is provided in the SASClient class. Any arguments and return values need to be serialized. It returns response data to be sent to the client. This method is used when the user wishes to perform operations, such as reading the contents of a file, listing a directory, etc.

public void closeSession(InetAddress applet_addr, int applet_port);

This method is called while closing the applet session.

 

Interface SASessionClient

 

This class is instantiated for each session. This allows performing custom functions for each applet session, such as caching data for an applet. This corresponds to an instance for each SASClient instance on the client. Following are the methods available in this interface.

 

Method Purpose

public void init(InetAddress applet_addr, int applet_port, SASession session);

This is called when a new session is opened. This parameters applet_addr and applet_port correspond to client's address and client's port respectively.

public int open(int port);

This is called when the client opens a UDP port. Typically, the port is 0, the system assigned UDP port. For listening traps or SNMP PDUs, a specific port can be specified. The return value is used for custom port assignment if required.

public SnmpPDU requestPDU(SnmpPDU pdu);

This method is called before sending the request. The PDU is sent to the agent, which can be modified as required by the custom class.

public SnmpPDU responsePDU(SnmpPDU pdu);

This method is called after receiving the response. This is the response PDU from the agent, which can be modified as required.

public byte[] clientCall(byte data[]);

This method allows the applet client to invoke a method on the server. The corresponding method is provided in the SASClient class. Any arguments and return values need to be serialized.

public void closeSession();

This method is called when the session is closed. The object is de-referenced if all of its threads are stopped.

public byte[] userCall(int reqType, byte data[]);

This method allows the user to implement the request type. For example, if the user request type is REVERSE_DATA, the received data can be reversed and returned in this method.

 

Interface SasLogInterface

 

This class is instantiated once. This can be used to provide custom methods to redirect error and debug messages and log data.

 

Method Purpose

public void err(String err);

This method handles the error messages.

public void dbg(String dbg);

This method handles the debug messages that are generated.

public void out(String out);

This method handles all stdout messages.

 

In SAS and SASClient, the following methods are supported.

 

Method Purpose

createDir(String dir)

This method creates a directory with the specified relative or absolute path.

deleteDir(String dir)

This method deletes a directory with the specified relative or absolute path.

deleteFile(String file)

This method deletes a file with the specified relative or absolute path.

reqTraps(int port)

This method requests for traps arriving on the specified port at the SAServer.

getHostName(String address, int timeout)

This method queries the SAServer for the host name with the given IP Address.

getHostAddress(String hostname, int timeout)

This method queries the SAServer for the IP Address of the hostname supplied.

userSyncSend(int userType, byte bytes[])

This method enables users to send their own request type.

 

Interface RegisterClient

 

This interface can be used by the API users to receive the traps from different agents. The API users can write their own implementation for receiving traps and can notify the received traps to the SAS API. The following things need to be considered during implementation.

The various methods present in RegisterClient interface are: 

  1. registerForPort(int port, SocketListener tl) throws Exception

    Whenever the SASClient calls the method "reqTraps(int)" (Refer "Support through SAS ->Provides a mechanism to receive traps"), this method is called where "SocketListener" is equivalent to SASClient. The received traps can be notified to the API by calling the method receivedData(ProtocolDataUnit) of SocketListener interface. The API users should not implement the "SocketListener" interface. This is implemented by the SASession class.

  2. registerForPorts(int[] ports, SocketListener tl) throws Exception

    This method is used if the same client wants to listen for traps to a set of ports.

  3. deRegisterForPort(int port, SocketListener tl)

    This method is used if a client wants to deregister for a particular port.

  4. deRegisterForPorts(int[] ports, SocketListener tl)

    This method is used if a client wants to deregister for a set of ports.

  5. deRegister(SocketListener tl)

    This method is used if the client does not want to listen for traps. This method is called if the "close" method if SASClient is called.

Interface SocketListener

 

There is no need for the API users to implement this interface. While implementing the RegisterClient interface if a trap is received, it should be notified to the SAS API by calling the receivedData (ProtocolDataUnit) method of SocketListener. This is implemented by SASession and whenever the receivedData method is called, the received trap is notified to SASession which in turn is notified to the client.

 

The method in this interface is:

 

receivedData(ProtocolDataUnit).

 

API users can implement the RegisterClient interface so that they can follow their own way to receive traps. This implemented class can be specified as a command line argument while starting SAServer. Whenever a request for traps arrives at the SAServer, the method registerForPort(int portToListen, SocketListener whichListensForTraps) is called. Therefore whenever the users receive traps, they need to inform the listener by calling the method SocketListener's receivedData(ProtocolDataUnit). API users should not implement the SocketListener interface because it is implemented internally by SASession class. This receivedData(ProtocolDataUnit) method is called whenever a trap is received.

 

Note:

  • The SAServerClient and SASessionClient classes must support an empty constructor to allow instantiation by SAS.

  • For all callbacks in which methods from both the SAServerClient and SASessionClient implementations are invoked, the SAServerClient implementation is called first.

  • To allow controlling the number of SNMP clients, the return value of the open(int port) can be used. If the number returned is less than zero, a UDP port is not opened disabling SNMP communication from the applet.

  • To minimize overhead when no PDU processing is done in the client programs, the SnmpPDU pre-processing and post-processing methods must call pdu.decode() to view the PDU data and pdu.encode() to make effective changes in the PDU.

  • Multiple clients can request for the same trap port. Incoming traps at that port are delivered to all the clients. A client application can request for traps arriving at more than one port.

  • The methods of RegisterClient is called from the SASession instance.

  • Currently, only registerForPort(int SocketListener) and deRegister(SocketListener) methods are called from SASession because there is no equivalent methods in SASClient. However, these two methods are sufficient to fulfill the trap requirement. An implementation for remaining methods will be in the future releases of the API.

 

 


Copyright © 1996-2006, AdventNet Inc. All Rights Reserved.