CLISession

 

CLISession is the main class in the core API that can be used to establish CLI sessions with network devices. CLISession allows you to communicate with devices either in synchronous or asynchronous mode. The type of the connection opened is based on the underlying Transport provider used which can be Telnet, Serial port, or any custom protocol implementation. The Transport provider can be selected using APIs provided in CLISession.

 

The CLISession provides the following functions:

  Session Management

 

Session management involves establishing, keeping track of the number of connections, and closing the connections within a specific period that can be configured so that the device resources are utilized optimally.

 

The CLISession provides necessary methods to establish the following types of CLI sessions:

Following methods can be used for establishing both multiplexed and dedicated CLI session.

 

Method Purpose

setTransportProviderClassName(java.lang.String className)

This method can be used to set the Transport provider class name. This class will be instantiated and used by the CLISession for communicating with the device.

setCLIProtocolOptions(CLIProtocolOptions cliProtocolOptions)

This method can be used to set the parameters specific to a particular protocol. The protocol can be Telnet, Serial, or custom protocol implementation.

open()

This method opens a transport connection (such as Telnet, Serial) with the remote device based on the CLIProtocolOptions set on the CLISession.

setCLIPrompt(java.lang.String cliPrompt)

This method can be used to set the prompt that is issued by the device after the execution of a CLI command.

close()

 

This method closes the CLI session and the underlying transport connection (if the session is dedicated).

 

Dedicated Session

 

In a dedicated session, the opened transport connection is reserved to a single CLI session and it will remain open until the session is closed. Any other CLISession cannot acquire this connection. If another CLISession is opened, it will open a new transport connection. In general, there will be 1 : 1 relationship between the CLISession instance and the transport connection.

 

 

Following method can be used to establish a dedicated CLI session in which the session pooling is not required.

    Method Purpose

    setPooling(boolean poolFlag)

    This method can be used to set the poolFlag as false, so that a dedicated session is established.

The following code snippet explains how to establish a dedicated CLI session.

    TelnetProtocolOptionsImpl tpoi = new TelnetProtocolOptionsImpl();

    try {

    cliSess = new CLISession(tpoi);

    cliSess.setPooling(false);

    cliSess.open();

    } catch(Exception e) { }

Multiplexed Session

 

In a multiplexed session (non-dedicated), the transport connection, i.e., Telnet, SSH, or Serial (RS232) is shared among various CLI sessions. In this mode, the application can make the transport connections to be shared among the various CLISessions from the common connection pool. In general, there will be 1 : n relationship between the CLISession instance and the transport connection.

 

The multiplexed sessions are kept open based on a keep-alive timeout value. If a multiplexed transport connection is idle for more than this timeout value, then the connection is closed automatically. This is done primarily to restrict the number of open connections to the device that can block up the device resources.

 

 

The closing of multiplexed connection will be intimated to the listeners of the session. Hence, any application requiring the notification from the session must register as a listener to the multiplexed sessions using the addConnectionListener method of CLISession.

 

Following methods can be used to establish a multiplexed CLI session.

The following code snippet explains how to establish a multiplexed CLI session.

    TelnetProtocolOptionsImpl tpoi = new TelnetProtocolOptionsImpl();

    try {

    cliSess = new CLISession(tpoi);

    cliSess.setPooling(true);

    cliSess.open();

    } catch(Exception e) {  }

     

    Note:

    • The dedicated CLISession cannot be converted into multiplexed.

    • In a multiplexed session, when the request timeout expires the CLISession will not be closed. Hence, when the next command is sent, it does not return any error.

Communication with Devices

 

After establishing a successful connection with device, CLI messages can be sent in the following modes of communication:

Synchronous communication

 

Synchronous communication is achieved by using the method syncSend. The application calling this method blocks the CLISession until the response for the sent command is received. This type of communication can be used where there is a need for a devoted communication, typically in configuration of devices where the next command can be sent only when the response for the previous command is received.

 

You can receive the response in synchronous mode using the following method :

The following code snippet explains how to send messages using synchronous mode.

For more details, please refer to the CLI Synchronous communication example application that is available in Examples chapter.

 

Asynchronous Communication

 

In an asynchronous mode of communication, the application does not wait for the response. Asynchronous communications allow the application to send the command and do other processes before receiving the response instead of waiting for it as in the case of synchronous mode.

 

The method send can be used for sending commands asynchronously. This method returns the message ID of the command sent. This ID can be used for matching commands with corresponding responses that are received in the callback() method. The application can receive the response in the callback method by registering with CLISession using addCLIClient method.

 

The callback mechanism can also be used to receive Asynchronous messages. Typically, these are sent when some fault condition occurs on the device.

 

The following methods can be used for sending and receiving asynchronous messages:

    Method Purpose

    addCLIClient(CLIClient client)

    This method can be used to register a CLI Client to receive the response in an asynchronous mode.

    send(CLIMessage cliMsg) 

    This method can be used to send the CLI Command in an asynchronous mode.

    removeCLIClient(CLIClient client)

    This method can be used to remove the CLI Client from the list of clients that are registered to receive asynchronous responses.

The following code snippet explains how to send messages in asynchronous mode.

    TelnetProtocolOptionsImpl tpoi = new TelnetProtocolOptionsImpl();

    CLIMessage msg = new CLIMessage("CLICommand");

    CLISession cliSess = new CLISession(tpoi);

    cliSess.open();

    try{

    System.out.println(cliSess.Send(msg).getData());

    } catch(Exception e){ }

For more details, please refer to the CLI Asynchronous communication example application that is available in Examples chapter.

 

Response Processing

 

The response received from the device needs to be processed before analyzing, because the response may contain some special characters such as escape sequences, color codes, or it may require to send additional prompts to receive the full response, and etc. The core API provides following special methods for processing the response:

Multiple Prompt

 

Certain CLI commands might return the response only partially and will wait for intermediate action for continuing the command execution. In these cases, the device will issue some intermediate prompts. In such situations, the setCLIPromptAction method can be used for setting the possible prompts and corresponding actions.

 

The actions are basically commands that the device expects for the different prompts. A list of prompts and the corresponding commands or actions can be registered in CLISession using the setCLIPromptAction method. The command or action will be sent when device returns the respective prompt. When no action or command is defined for a prompt, it is assumed as the command prompt.

 

For example, if you send commands such as "show interface" to routers, you will get the response in the form of blocks. To receive the next block of response, you have to send "space" through keyboard when it encounters --More-- prompt. If this method is used, the handling of the --More-- prompt and the corresponding sending of 'space' are taken care of internally by the CLISession and therefore appears transparent to the application. The application receives the whole response with all the blocks combined together.

 

The following code snippet explains how to send a multiple prompt to receive the full response.

Ignore Special Characters

 

When device returns response that contains special characters such as ANSI escape sequences or some non-printable characters, setIgnoreSpecialCharacters method enables you to obtain the response without the special characters.

 

The following code snippet explains how to ignore special characters from the response.

Send Control Characters

 

Several commands under particular condition might keep executing and will not terminate. In such situations, it might be necessary to abort the execution so that the next command can be sent. The setInterruptCmd method can be used for this purpose. The character or ASCII value that is set using this method will be sent by the CLISession automatically to the device when this situation occurs.

 

The following code snippet explains how to send control characters to interrupt the response.

Please refer to Java documentation for complete details.