AdventNet CLI 2.0 API Specification

com.adventnet.cli.rmi
Interface CLISession


public interface CLISession
extends java.rmi.Remote

This is the RMI interface implemented by the CLISessionImpl class. The interface provides methods which are normally available in the non RMI CLISession class.


Method Summary
 void addCLIClient(CLIClient client)
          Registers the CLIClient for receiving the asynchronous Response for a asyn request.
 void addConnectionListener(com.adventnet.cli.rmi.ConnectionListener conListener)
          Registers the connectionListener, if not already registered as a listener.
 void close()
          Closes the CLISession and stops the asynch receiver thread.
 int getCLIClientsSize()
          Gets the count of clients that have registered for callback.
 java.lang.String getCLIPrompt()
          Gets the CLI Prompt for this session.
 java.util.Properties getCLIPromptAction()
          Gets the prompt list.
 CLIProtocolOptions getCLIProtocolOptions()
          Gets the CLIProtocolOptions for this session.
 int getDebugLevel()
          Gets the debug level.
 java.lang.String getInitialMessage()
          Gets the initial Message sent by the device after a successful connection establishment.
 java.lang.String getInterruptCmd()
          Gets the interrupt command.
 int getKeepAliveTimeout()
          Gets the keepAlive time-out in seconds.
 int getMaxConnections()
          Gets the maximum no of CLI Connections that can exist for this session.
 int getRequestTimeout()
          Gets the time-out in milliseconds for this request message.
 CLIResourceManager getResourceManager()
          Gets the CLIResourceManager which manages the System Resources.
 java.lang.String getTransportProviderClassName()
          Gets the Transport Provider Class name.
 boolean isSetDebug()
          Gets the debug flag.
 boolean isSetIgnoreSpecialCharacters()
          Returns whether the ignoring of special characters is enabled or not.
 boolean isSetPooling()
          Gets the pooling Flag of this Session.
 void open()
          Opens the CLI connection with the remote device based on the CLIProtocolOptions set.
 void removeCLIClient(CLIClient client)
          Unregisters or removes the CLIClient from the list of clients that have already registered for callback to receive asynchronous responses.
 void removeConnectionListener(com.adventnet.cli.rmi.ConnectionListener conListener)
          Unregisters the listener, if it is registered as a ConnectionListener.
 int send(CLIMessage cliMsg)
          Sends the CLIMessage asynchronously.
 void setCLIPrompt(java.lang.String cliPrompt)
          Sets the CLI Prompt for this session.
 void setCLIPromptAction(java.util.Properties prop)
          Sets the prompt list.
 void setCLIProtocolOptions(CLIProtocolOptions cliProtocolOptions)
          Sets the CLIProtocolOptions for this session.
 void setDebug(boolean debug)
          Sets the debug flag.
 void setDebugLevel(int level)
          Sets the debug level.
 void setIgnoreSpecialCharacters(boolean ignore)
          Enables stripping of special characters in the response message.
 void setInterruptCmd(java.lang.String cmd)
          Sets the interrupt command.
 void setKeepAliveTimeout(int timeout)
          Sets the keepAlive time-out in seconds.
 void setMaxConnections(int connections)
          Sets the maximum no of CLI Connections that can exist for this session.
 void setPooling(boolean poolFlag)
          Enables/Disables the pooling of CLITransport Sessions.
 void setRequestTimeout(int timeout)
          Sets the time-out for this request message.
 void setTransportProviderClassName(java.lang.String className)
          Sets the Transport Provider Class name.
 CLIMessage syncSend(CLIMessage cliMsg)
          Sends the CLIMessage synchronously.
 

Method Detail

open

public void open()
          throws java.rmi.RemoteException
Opens the CLI connection with the remote device based on the CLIProtocolOptions set.
Throws:
RemoteException - if error occurs while initializing the transport connection. The exception is an instance of LoginException if the login parameters (username, password, etc.) are incorrect and it is an instance of ConnectException if the host parameters (port, hostname, etc. are incorrect).

setTransportProviderClassName

public void setTransportProviderClassName(java.lang.String className)
                                   throws java.rmi.RemoteException
Sets the Transport Provider Class name. This class will be searched for in the classpath and will be used for the CLI communication with the Remote device. When this parameter is not set, the provider specified in the cliTransport.config file is used for the CLI communication.
Parameters:
className - The provider classname.

getTransportProviderClassName

public java.lang.String getTransportProviderClassName()
                                               throws java.rmi.RemoteException
Gets the Transport Provider Class name.
Returns:
the provider classname.

setCLIProtocolOptions

public void setCLIProtocolOptions(CLIProtocolOptions cliProtocolOptions)
                           throws java.rmi.RemoteException
Sets the CLIProtocolOptions for this session. This parameter contains the necessary information (typically host address and port ) about the remote device. It is used for sending the CLI command to the appropriate device.
Parameters:
cliProtocolOptions - the CLI protocol options.

getCLIProtocolOptions

public CLIProtocolOptions getCLIProtocolOptions()
                                         throws java.rmi.RemoteException
Gets the CLIProtocolOptions for this session.
Returns:
cliProtocolOptions the cli protocol options.

setCLIPrompt

public void setCLIPrompt(java.lang.String cliPrompt)
                  throws java.rmi.RemoteException
Sets the CLI Prompt for this session. The prompt is the string issued by the device after execution or completion of a CLI Command. If this parameter is not set or null the prompt in the CLIMessage will be used.
Parameters:
cliPrompt - the CLI prompt.

getCLIPrompt

public java.lang.String getCLIPrompt()
                              throws java.rmi.RemoteException
Gets the CLI Prompt for this session.
Returns:
the CLI prompt.

setPooling

public void setPooling(boolean poolFlag)
                throws java.rmi.RemoteException
Enables/Disables the pooling of CLITransport Sessions. When this flag is set, the Transport connection established with the device is shared among CLISessions. Note that this flag has to be set before a call to open() method. It has no effect after the session is opened.
Parameters:
poolFlag - the flag to enable pooling. If true, the sharing of the Transport Connections is enabled.

isSetPooling

public boolean isSetPooling()
                     throws java.rmi.RemoteException
Gets the pooling Flag of this Session.
Returns:
the pooling Flag.

setMaxConnections

public void setMaxConnections(int connections)
                       throws java.rmi.RemoteException
Sets the maximum no of CLI Connections that can exist for this session. Default is 2.
Parameters:
connection - count.

getMaxConnections

public int getMaxConnections()
                      throws java.rmi.RemoteException
Gets the maximum no of CLI Connections that can exist for this session.
Returns:
the maximum no of connections for this Session.

syncSend

public CLIMessage syncSend(CLIMessage cliMsg)
                    throws java.rmi.RemoteException
Sends the CLIMessage synchronously. Blocks until the response arrives.
Parameters:
cliMsg - the CLIMessage to be sent.
Returns:
the CLI response message as a String.

addCLIClient

public void addCLIClient(CLIClient client)
                  throws java.rmi.RemoteException
Registers the CLIClient for receiving the asynchronous Response for a asyn request.
Parameters:
client - the CLIClient.

send

public int send(CLIMessage cliMsg)
         throws java.rmi.RemoteException
Sends the CLIMessage asynchronously. When the response arrives, all the registered CLIClient's callback will be called.
Parameters:
cliMsg - the CLIMessage to be sent.
Returns:
the MessageID of the message sent.

close

public void close()
           throws java.rmi.RemoteException
Closes the CLISession and stops the asynch receiver thread.

setRequestTimeout

public void setRequestTimeout(int timeout)
                       throws java.rmi.RemoteException
Sets the time-out for this request message. If the response is not received within this time, a time-out occurs and an Exception is thrown.
Parameters:
timeout - The time-out value(in milliseconds).

getRequestTimeout

public int getRequestTimeout()
                      throws java.rmi.RemoteException
Gets the time-out in milliseconds for this request message.
Returns:
the time-out in milliseconds.

setKeepAliveTimeout

public void setKeepAliveTimeout(int timeout)
                         throws java.rmi.RemoteException
Sets the keepAlive time-out in seconds. This is the time for which a Particular CLI connection can remain idle. When the connection remains idle for this period, it is automatically closed provided it is not Dedicated. This parameter is common to a group of connections with the same device.
Parameters:
timeout - the time-out value (in seconds).

getKeepAliveTimeout

public int getKeepAliveTimeout()
                        throws java.rmi.RemoteException
Gets the keepAlive time-out in seconds. This is the time for which a Particular CLI connection can remain idle. This parameter is common to a group of connections with the same device.
Returns:
the time-out in seconds.

setDebug

public void setDebug(boolean debug)
              throws java.rmi.RemoteException
Sets the debug flag. This flag when set to true will enable or disable debug messages printed on the Standard Output.
Parameters:
debug - if true, enables debug messages. If false, disables it.

isSetDebug

public boolean isSetDebug()
                   throws java.rmi.RemoteException
Gets the debug flag.
Returns:
gets the debug flag.

setDebugLevel

public void setDebugLevel(int level)
                   throws java.rmi.RemoteException
Sets the debug level. When the debug level is set to 2, all the debug messages are output to the console. When set to 1, only the messages that are sent/received are printed on the Standard output.
 1 - Normal.
 2 - Critical.
 
Parameters:
level - the debug level.

getDebugLevel

public int getDebugLevel()
                  throws java.rmi.RemoteException
Gets the debug level.
Returns:
the debug level.

setIgnoreSpecialCharacters

public void setIgnoreSpecialCharacters(boolean ignore)
                                throws java.rmi.RemoteException
Enables stripping of special characters in the response message. When set to true, responses will have special characters removed. The following are the ASCII range in decimal for the characters that are Not removed:
 a) ASCII characters from 32 to 126 inclusive.
 b) 10 (New Line) and 9 (Horizontal Tab).
 
Parameters:
ignore - boolean to enable or disable ignoring of special characters.

isSetIgnoreSpecialCharacters

public boolean isSetIgnoreSpecialCharacters()
                                     throws java.rmi.RemoteException
Returns whether the ignoring of special characters is enabled or not.
Returns:
boolean to indicate enabling/disabling of stripping of Special characters.

getInitialMessage

public java.lang.String getInitialMessage()
                                   throws java.rmi.RemoteException
Gets the initial Message sent by the device after a successful connection establishment.
Returns:
The Initial Message.

removeCLIClient

public void removeCLIClient(CLIClient client)
                     throws java.rmi.RemoteException
Unregisters or removes the CLIClient from the list of clients that have already registered for callback to receive asynchronous responses.
Parameters:
client - the CLIClient.

getCLIClientsSize

public int getCLIClientsSize()
                      throws java.rmi.RemoteException
Gets the count of clients that have registered for callback.
Returns:
the no of clients that have registered for callback.

addConnectionListener

public void addConnectionListener(com.adventnet.cli.rmi.ConnectionListener conListener)
                           throws java.rmi.RemoteException
Registers the connectionListener, if not already registered as a listener. All the registered connection listeners will be notified when the the transport connection associated with the non-dedicated sessions times out.
Parameters:
conListener - the connectionListener to be registered. Registers only if it is a non null.
Since:
CLI2.0
See Also:
removeConnectionListener(ConnectionListener)

removeConnectionListener

public void removeConnectionListener(com.adventnet.cli.rmi.ConnectionListener conListener)
                              throws java.rmi.RemoteException
Unregisters the listener, if it is registered as a ConnectionListener. Hence it will cease to receive notification when the non-dedicated session times out.
Parameters:
conListener - the ConnectionListener to be unregistered.
Since:
CLI2.0
See Also:
addConnectionListener(ConnectionListener)

getCLIPromptAction

public java.util.Properties getCLIPromptAction()
                                        throws java.rmi.RemoteException
Gets the prompt list. This is the list of prompts, one of which will be returned by the device after execution of a command. In the properties, object returned, the prompts can also have a command/action defined for it. When one of the prompts is encountered, the command corresponding to the prompt is sent by the session. When no action or command is defined for a prompt, it will have an empty value.
   (i.e.) prop.setProperty(prompt,""); 
and this will be assumed as the command prompt.

This will be used when the CLIPromptAction in the message is not set.

Returns:
prompts and its command as a Properties object.
Since:
CLI2.0
See Also:
setCLIPromptAction(Properties), getInterruptCmd(), CLIMessage#getCLIPromptAction()

setCLIPromptAction

public void setCLIPromptAction(java.util.Properties prop)
                        throws java.rmi.RemoteException
Sets the prompt list. This method is used for setting the possible prompts the device can return after executing a command. The session will wait for one of the prompts to be returned by the device, for a command sent. If any command is to be sent for the prompt received, the command can be set as the value of the prompt.
        prop.setProperty(prompt, cmd);
 
When no action or command is defined for a prompt, it will be assumed as the command prompt. Note that the suffix, if any, should also be given in the command set for the prompt, as no suffix would be appended to the command, when it is sent.

An example for the use of CLIPromptAction can be, in the case of commands that returns a response, which runs for more than the screen size. For such commands (in case of the Cisco router), a "--More--" prompt appears, which requires further commands or key input. A sample code snippet would look like:

 
 Properties prop = new Properties();
 prop.setProperty(">",""); // the command prompt
 prop.setProperty("--More--"," ");
 cliSession.setCLIPromptAction(prop);
 CLIMessage climsg = new CLIMessage("show interfaces");
 CLIMessage response = cliSession.syncSend(climsg);
 System.out.println("response obtained "+response);
  
Here 'cliSession' is the CLISession instance. Whenever the "--More--" prompt appears, a " "(space) will be sent. Hence the 'response' obtained is the complete response for the command sent.

Parameters:
prompts - prompts and its command as a Properties object.
Since:
CLI2.0
See Also:
getCLIPromptAction(), setInterruptCmd(String), CLIMessage#setCLIPromptAction(Properties)

getInterruptCmd

public java.lang.String getInterruptCmd()
                                 throws java.rmi.RemoteException
Gets the interrupt command. This is the command which will be sent by the session, when the complete response for a message, is not obtained.

Normally the session waits for a time of requestTimeout for the response and throws an exception when the response is not obtained within the specified time interval. But when the interrupt command is set and response is not obtained, the message/command previously sent to the device is aborted by sending this command and the partial result for the message is returned to the user. The interrupt command can be any string (like the ascii value of 'Control C').

Returns:
the command as a String value
Since:
CLI2.0
See Also:
setInterruptCmd(String)

setInterruptCmd

public void setInterruptCmd(java.lang.String cmd)
                     throws java.rmi.RemoteException
Sets the interrupt command. Note that the set command should also contain the suffix, if any, as no suffix would be appended to it, when it is sent.

This is the command which will be sent by the session, when the complete response for the message sent, is not obtained. This happens when none of the prompts in the message or in the session, matches the prompt returned by the device or the response is not obtained. In this case, the session sends the interrupt command (thus aborting the message/command previously sent to the device) and returns the partial response for the message sent.

For instance, when a 'ls |more' command is sent to a unix machine, it prompts with a '--More--' for further key input. When a ' ' is typed it scrolls the next screen or when ^c is sent it exits. But when '--More--' is not specified as one of the prompts, the command is incomplete. So if the ascii value of '^c' is set using,

 
 cliSession.setInterruptCmd("\003") 
 
this will be sent when the request message timesout and the command will be aborted.

Parameters:
cmd - the interrupt command as a String value.
Since:
CLI2.0
See Also:
getInterruptCmd()

getResourceManager

public CLIResourceManager getResourceManager()
                                      throws java.rmi.RemoteException
Gets the CLIResourceManager which manages the System Resources. The CLIResourceManager has methods to set and get the maximum number of connections (System Wide) that can be opened at any given instant. The resource manager also manages the Pool of CLI connections established. It Monitors the Connections and closes them when not being used for a specific period of time (decided by the time-out parameter).

For instance, when you have finished using the CLI APIs, closed the session and would like to close all connections(non-dedicated) managed by the session,

 clisession.getResourceManager().closeAllConnections();
 
method can be invoked.

Returns:
the CLI Resource Manager.

AdventNet CLI 2.0 API Specification