com.adventnet.tl1
Class TL1Session

java.lang.Object
  |
  +--com.adventnet.tl1.TL1Session

All Implemented Interfaces:

java.io.Serializable

public class TL1Session

extends java.lang.Object

implements java.io.Serializable

This class must be used for establishing connection with TL1Devices. It provides a transport independent interface for sending and receiving of TL1 messages between the manager and TL1Device. By default, the transport protocol used is TCP.

Each TL1Session is managed by the TL1API which provides configurable threads to receive and process TL1 Messages.

To associate a TL1Session with the TL1API,

    TL1API api = new TL1API();
    TL1Session session = new TL1Session(api);

Communication modes

There are two modes in TL1Session,

i) Normal mode : This mode supports synchronous and asynchronous mechanisms for sending messages. The messages sent and received through this mode are parsed using the message parser(TL1MessageParser by default).

    session = new TL1Session(api);
      -or-
    session = new TL1Session(api, false);
      -or-
    session = new TL1Session(api, new com.adventnet.tl1.parser.TL1MessageParser());

ii) Craft mode : This is TL1 Cut-through. You can use this mode to send and receive any messages. This mode supports only asynchronous mechanism to send and receive messages and it does not includes any parsing of messages.

    session = new TL1Session(api, true); 

If the TL1Session is in the agent mode then the queueing of the messages is not taken place. So the timeout, retries, setAppendFront and setAppendFront also have no effect.

    session.isSetToAgentMode(); 

Opening a Connection

You must use the open method for establishing a connection with a TL1Device. Before opening the connection, you must first set the transport protocol on this TL1Session. By default the transport protocol is set to TcpTransportImpl.

    session.setTransportProvider(new com.adventnet.tl1.telnet.TelnetTransportImpl()); 

In the case of TCP, you can use the open(host, port) method for opening a connection.

    session.open("192.168.9.85", 30002);

If you want to use a transport protocol other than TCP, you must use the open(Hashtable) method where Hashtable contains the connection parameters.

    Hashtable params = new Hashtable();
    params.put("REMOTE_HOST", "192.168.9.85");
    params.put("REMOTE_PORT", "30002");
    session.open(params); 

To notify the application of the connection failure with the TL1 Agent, you must implement the ConnectionListener and register it with this session.

    session.setConnectionListener(connectionListenerImpl); 

Parsing Messages

By default, the TL1MessageParser is used for parsing the messages. You can also plug-in your own parser for parsing the messages by implementing the TL1parser interface. This parser implementation should be registered with this TL1Session in the following way,

    session.setParser(parserImpl); 

To parse the messages, you need to do this.

    String str = "ACT-USER::ROOT:::FACTORY1%;";
    TL1Message mesg = session.getParser().createTL1Message(str); 

Sending Messages

You can send messages to the TL1 Agent in two ways.

i) Synchronous Communication (Applicable only for Normal mode).

    session.syncSend(str.getBytes());
       -or-
    session.syncSend(mesg); 

ii) Asynchronous Communication

    String tcid = session.addTL1Client(tl1clientImpl);
    session.send(str.getBytes());        // Normal mode.
       -or-
    session.send(mesg);                  // Normal mode.
       -or-
    session.send(mesg, tcid);            // Normal mode.
       -or-
    session.send(str.getBytes(), true);  // Normal mode.
       -or-
    session.send(str.getBytes(), false); // Craft mode.

To get the responses from the device without implementing the TL1Client interface,

    Vector mtagV = session.checkRequests();

    for(int i = 0; i < mtagV.size(); i++)
    {
       TL1Message input = session.getRequest(mtag);
       responseV = session.getResponses(mtag);
    }
 

To get notifications from the device,

    Vector mtagV = session.checkNotifications();

    for(int i = 0; i < mtagV.size(); i++)
    {
        notificationV = session.getNotifications(mtag);
    }
 

To close the connection with the agent, use the close method.

    session.close();
 

This method stops the TL1RECEIVE_N_PROCESS_TASK, TL1MONITOR_TASK and TL1LOGGER_THREAD. But the TL1CALLBACK_N_TIMEOUT_TASK is not stopped.

To cleanup all the session properties ,use the cleanup method. This method stops all the tasks, and set all the session variables to it's default value. This method should be called only if the session is in TL1Session.CLOSED or TL1Session.CONNECTION_DOWN state.

    session.cleanup();
 

See Also:

TL1API, TL1Client, ConnectionHandler, ConnectionListener, MessageFormatter, MessageRationalizer, IdleTimeMonitor, TL1Parser, TL1Message, TL1TransportProvider, Serialized Form

Field Summary

static java.lang.String	ALIVE Static constant represents the Alive state of the session.
static java.lang.String	CLOSED Static constant represents the Closed state of the session.
static java.lang.String	CONNECTION_DOWN Static constant represents the ConnectionDown state because the TL1Device snaps the Connection of this session.
static byte	INVALID_TL1_MESSAGE Static constant for invalid TL1Message in the callback.
static java.lang.String	NASCENT Static constant represents the Nascent state of the session.
static byte	PARSER_EXCEPTION Static constant for parser exception in the callback.
static byte	TIMEOUT Static constant for timeout in the callback.

Constructor Summary

TL1Session(TL1API api)
Constructs a TL1Session with TL1API instance.

TL1Session(TL1API api, boolean mode)
Constructs a TL1Session with TL1API instance.

TL1Session(TL1API api, TL1Parser parser)
Constructor a TL1Session with TL1API instance.

Method Summary

void	addLog(LogRecord record) Adds the logrecord in the queue associated with this TL1Session.
void	addLogger(java.lang.String loggerId, Logger logger) Register the logger implementation with this TL1Session to receive TL1Session all events and transaction between the manager and the agent.
java.lang.String	addTL1Client(TL1Client client) Register the client implementation with this TL1Session to receive messages using callbacks.
java.util.Vector	checkNotifications() Gets the autonomous tag of all the notifications received from the agent which exists in the queue.
java.util.Vector	checkRequests() Gets the correlation tag of all the pending requests in this Session.
void	cleanup() This method is used to cleanup the threads associated with this session like (TL1API.RECEIVE_N_PROCESS, TL1API.CALLBACK_N_TIMEOUT etc..) , close the logstream if any associated with this session and all the TL1Session properties will get thier default values.
void	close() Closes the tcp connection to the device but the (TL1API.Callback_N_Timeout ) thread associated with this session will not be dequed.
void	dropInputMsgInCallback(boolean flag) Drop the TL1InputMessages in callback.
java.lang.String	getAppendEnd() Gets the string appended to the end of each Input Message.
java.lang.String	getAppendFront() Gets the string appended to the front of each Input Message.
ConnectionEvent	getConnectionEvent() Gets the connection event of the Session at present.
ConnectionHandler	getConnectionHandler() Gets the ConnectionHandler instance registered with this session.
ConnectionListener	getConnectionListener() Gets the ConnectionListener instance registered with this session.
java.util.Hashtable	getConnectionProperties() Gets the connection parameters as a Hashtable.
IdleTimeMonitor	getIdleTimeMonitor() Gets the registered IdleTimeMonitor implementation.
long	getInputInterval() Gets the input interval set for this session.
Logger	getLogger(java.lang.String loggerId) Gets the Logger for the given loggerId.
java.lang.String[]	getLoggerIdList() Gets the LoggerId lists associated with this Session.
int	getLogQueueSize(java.lang.String logrecordtype) Gets the size of the logrecord queue associated with this session for the particular type.
MessageFormatter	getMessageFormatter() Gets the MessageFormatter implementation registered with this Session.
MessageRationalizer	getMessageRationalizer() Gets the MessageRationalizer implementation registered with this Session.
int	getNotificationQueueSize() Gets the size of the notification queue associated with this Session.
java.util.Vector	getNotifications(java.lang.String mtag) Gets all the notifications for the given autonomous tag.
long	getOutputInterval() Gets the output interval set for this session.
TL1Parser	getParser() Gets the TL1 parser instance registered with this Session.
TL1Message	getRequest(java.lang.String mtag) Gets the request message for the given correlation tag.
int	getRequestQueueSize() Gets the size of the request queue associated with this session.
java.util.Vector	getResponses(java.lang.String mtag) Gets all the responses for the given correlation tag.
int	getRetries() Gets the number of retries before the timeout period.
java.lang.String	getServerSessionId() Gets the serversession id for this Session to which it connects.
java.lang.Object	getSessionClassifier() Gets the details set on this Session using the setSessionClassifier method.
java.lang.String	getSessionId() Gets the session id for this Session.
java.util.Hashtable	getSessionProperties() Gets the properties associated with this Session as a Hashtable.
java.lang.String	getState() Gets the Session state of this Session.
int	getTimeout() Gets the timeout value.
TL1Client	getTL1Client(java.lang.String clientId) Gets the TL1Client for the given clientId.
java.lang.String	getTL1ClientId(java.lang.String mtag) Gets the clientId for the given Message tag.
java.lang.String[]	getTL1ClientIdList() Gets the TL1ClientId lists associated with this Session.
java.util.Vector	getTL1Clients() Deprecated. Since WebNMS TL1 API 4. Use getTL1Client(String clientId).
TL1TransportProvider	getTransportProvider() Gets the TL1TransportProvider implementation registered with this session.
boolean	isAccruePartial() To get the mode of processing the partial messages.
boolean	isConnected() Check the status of this Session.
boolean	isDroppedInputMsgInCallback() Method to get the status of the flag which indicates whether or not the echo of TL1InputMessage is dropped in the callback(..)
boolean	isSetToAgentMode() To get the mode (Manager/Agent) of session.
java.lang.String	open(java.util.Hashtable params) Establishes a connection with the TL1 device using the parameters specified in the Hashtable.
java.lang.String	open(java.lang.String remoteHost, int remotePort) Establishes a socket(TCP) connection with the TL1 device.
void	removeConnectionHandler() Unsubscribe the ConnectionHandler implementation from this Session.
void	removeConnectionListener() Unsubscribe the ConnectionListener implementation from this Session.
void	removeIdleTimeMonitor() Unregisters the IdleTimeMonitor with this session.
void	removeLogger(java.lang.String loggerId) Unsubscribe the Logger implementation from the session.
void	removeMessageFormatter() Unsubscribes the MessageFormatter implementation from this Session.
void	removeMessageRationalizer() Unsubscribes the MessageRationalizer implementation from this Session.
boolean	removeTL1Client(java.lang.String clientId) Unsubscribe the client implementation from receiving callbacks.
java.lang.String	send(byte[] tl1Message) Sends a non-blocking request to the TL1 device.
java.lang.String	send(byte[] tl1Message, boolean parseFlag) Sends a non-blocking message to the TL1 entity (manager or agent).
java.lang.String	send(TL1Message msg) Sends a non-blocking request to the TL1 device.
java.lang.String	send(TL1Message msg, java.lang.String tcid) Sends a non-blocking request to the TL1 device.
void	setAccruePartial(boolean accruePartial) This method is used to specify how the message is to be handled, if the message is recieved in parts(that is the whole message is not received at the same time,but rather the message is received only in several pieces before the terminating semi-colon is received).
void	setAppendEnd(java.lang.String suffix) Appends the given String to the end of each Input Message before it sends to the TL1Device.
void	setAppendFront(java.lang.String prefix) Appends the given String to the front of each Input Message before it sends to the TL1Device.
void	setConnectionHandler(ConnectionHandler connHandler) Register the ConnectionHandler implementation with this Session.
void	setConnectionListener(ConnectionListener connListener) Register the ConnectionListener implementation with this Session.
void	setIdleTimeMonitor(long inputInvl, long outputInvl, IdleTimeMonitor idleTmMon) Registers the IdleTimeMonitor with this session for idle time monitoring of both Input and Output Messages.
boolean	setKeepAlive(TL1Message tl1message, int freq) Maintain connection with the device when messages are not sent by the application for a long time.
void	setLog(boolean log) Provides a mechanism for logging messages.
void	setLogQueueSize(int queueSize) Sets the size of the info and raw logrecord queue, associated with this session.
void	setLogQueueSize(int queueSize, java.lang.String logrecordtype) Sets the size of the info or raw logrecord queue, associated with this session depends on the LogRecord type.
void	setMessageFormatter(MessageFormatter mesgFormatter) Register the MessageFormatter implementation with this Session for modifying the messages sent to the device and also received from the device.
void	setMessageRationalizer(MessageRationalizer rationalizer) Register the MessageRationalizer implementation with this Session for rationalizing the messages sent to the device and also received from the device.
void	setNotificationQueueSize(int size) Set the size of the notification queue in non-blocking mode which stores all the autonomous messages.
void	setParser(TL1Parser par) Set the parser instance with this Session for parsing the messages.
void	setRequestQueueSize(int size) Set the size of the request queue in the case of non-blocking mode.
void	setRetries(int retries) Set the number of retries to be performed before timeout.
void	setSessionClassifier(java.lang.Object obj) Stores application specific details.
void	setTimeout(int timeout) Set the timeout value.
void	setToAgentMode(boolean flag) Setting the flag to true will function the session as an Agent, helping the user to send any TL1Message.
void	setTransportProvider(TL1TransportProvider provider) Register the transport protocol implementation with this Session for communication between the manage and the agent.
void	startKeepAlive() Starts the keep alive process after setting the necessary parameters like TL1Message and keepalive interval.
void	stopKeepAlive() Stops the keep alive process.
TL1Message	syncSend(byte[] msg) Sends a request to the TL1 device in blocking mode.
TL1Message	syncSend(TL1Message msg) Sends a request to the TL1 device in blocking mode.

Methods inherited from class java.lang.Object

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

Field Detail

TIMEOUT

public static final byte TIMEOUT

Static constant for timeout in the callback.

PARSER_EXCEPTION

public static final byte PARSER_EXCEPTION

Static constant for parser exception in the callback.

INVALID_TL1_MESSAGE

public static final byte INVALID_TL1_MESSAGE

Static constant for invalid TL1Message in the callback. If the message type couldn't be identified, it will be given in the callback as an INVALID_TL1_MESSAGE.

NASCENT

public static final java.lang.String NASCENT

Static constant represents the Nascent state of the session.

ALIVE

public static final java.lang.String ALIVE

Static constant represents the Alive state of the session.

CONNECTION_DOWN

public static final java.lang.String CONNECTION_DOWN

Static constant represents the ConnectionDown state because the TL1Device snaps the Connection of this session.

CLOSED

public static final java.lang.String CLOSED

Static constant represents the Closed state of the session.

Constructor Detail

TL1Session

public TL1Session(TL1API api)

Constructs a TL1Session with TL1API instance. In this case, the mode is set to Normal and the default message parser is used.

Parameters:

api - instance of TL1API.If it is null, then new default TL1API() is instantiated.

TL1Session

public TL1Session(TL1API api,
                  boolean mode)

Constructs a TL1Session with TL1API instance. If the mode flag is set to true, the session works in Craft mode. Otherwise, it works in Normal mode. In the case of Normal mode, the default message parser is used.

Parameters:

api - instance of TL1API.If it is null, then by default new TL1API() is instantiated.

mode - true to set it in Craft mode or false to set it in Normal mode.

TL1Session

public TL1Session(TL1API api,
                  TL1Parser parser)

Constructor a TL1Session with TL1API instance. The session works in Normal mode with the specified message parser. The parser instance is plugged on this TL1Session instead of the default parser.

Parameters:

api - instance of TL1API.If it is null, then new default TL1API() is instantiated.

parser - instance of TL1Parser.

Method Detail

getState

public java.lang.String getState()

Gets the Session state of this Session. It may be any of the following NASCENT/ ALIVE/ CONNECTION_DOWN/ CLOSE. Intially the session is in NASCENT state then it becomes ALIVE state after opening the session, then it becomes CONNECTION_DOWN state if the agent quits the connection and it becomes CLOSE state after closing the session.

Returns:

sessionstate as a String.

Since:

TL1 API 4

setToAgentMode

public void setToAgentMode(boolean flag)

Setting the flag to true will function the session as an Agent, helping the user to send any TL1Message. This flag has to be set before calling the open method. Default mode of session is in Manager.

Parameters:

flag - - true means session will function as Agent, false means session will function as Manager.

isSetToAgentMode

public boolean isSetToAgentMode()

To get the mode (Manager/Agent) of session.

Returns:

Returns true, if the session functions as an Agent; otherwise false, if the session functions as a Manager.

See Also:

setToAgentMode(boolean)

getServerSessionId

public java.lang.String getServerSessionId()

Gets the serversession id for this Session to which it connects. You must call this method after establishing a connection with the TL1Device. Otherwise, it returns null.

Returns:

serversession id as a String. Returns Null, if connection is not established.

Since:

TL1 API 4

setLog

public void setLog(boolean log)

Provides a mechanism for logging messages. It registers one default logger implementation(FileLogger) in the name of LogId and it creates two log files,rawlog_date_count.log and infolog_date_count.log wher date is current date and count is from 1 to n. You can get this implementation by using this LogId.

If the log file already exists with the same name, the session creates a new file with a different count. These log files will be generated in the logs directory from where the application runs.

Upon creating a log file for a particular session, you can start/stop writing in the log file as and when needed by enabling or disabling the boolean value.

Parameters:

log - flag to enable and disable the logging mechanism.

addLogger

public void addLogger(java.lang.String loggerId,
                      Logger logger)

Register the logger implementation with this TL1Session to receive TL1Session all events and transaction between the manager and the agent. This can be used to track session very closely. The interface provides log methods to get the session events and transactions.

Parameters:

logger - Logger implementation.

logerId - String value. It updates the Logger implementation if the same loggerId is already presents in this session.

Since:

TL1 API 4

See Also:

getLoggerIdList

public java.lang.String[] getLoggerIdList()

Gets the LoggerId lists associated with this Session.

Returns:

String array containing Logger Ids.

Since:

TL1 API 4

getLogger

public Logger getLogger(java.lang.String loggerId)

Gets the Logger for the given loggerId. If the Logger for the given loggerId was not added in this session, it will return null.

Parameters:

loggerId - String, represents the loggerId.

Returns:

Logger corresponding to this loggerId.

Since:

TL1 API 4

removeLogger

public void removeLogger(java.lang.String loggerId)

Unsubscribe the Logger implementation from the session. However, other loggers registered with the TL1Session will continue to receive the log messages occured in this session.

Parameters:

clientId - Unique id that has been given during the addLogger method.

Since:

TL1 API 4

setLogQueueSize

public void setLogQueueSize(int queueSize)

Sets the size of the info and raw logrecord queue, associated with this session. The default size of the request queue is 1000.

Parameters:

queueSize - int value greater than zero.

Since:

TL1 API 4

See Also:

setLogQueueSize

public void setLogQueueSize(int queueSize,
                            java.lang.String logrecordtype)

Sets the size of the info or raw logrecord queue, associated with this session depends on the LogRecord type. The default size of the request queue is 1000.

Parameters:

queueSize - int value greater than zero.

logrecordtype - Type of the LogRecord, either LogRecord.INFO or LogRecord.RAW.

Since:

TL1 API 4

See Also:

getLogQueueSize

public int getLogQueueSize(java.lang.String logrecordtype)

Gets the size of the logrecord queue associated with this session for the particular type. The default size of the queue is 1000.

Parameters:

logrecordtype - Type of the LogRecord, either LogRecord.INFO or LogRecord.RAW.

Returns:

logrecord queue size as an int value for the particular type, Otherwise return -1 if the type is invalid.

Since:

TL1 API 4

See Also:

addLog

public void addLog(LogRecord record)

Adds the logrecord in the queue associated with this TL1Session. It sets the logrecord count internaly, user no need to set the count. If you set already it will be overided by the TL1Session.

Parameters:

record - LogRecord to be added in the queue.

Since:

TL1 API 4

See Also:

getTL1Clients

public java.util.Vector getTL1Clients()

Deprecated. Since WebNMS TL1 API 4. Use getTL1Client(String clientId).

Gets the TL1Clients associated with this Session.

Returns:

Vector containing TL1Clients.

addTL1Client

public java.lang.String addTL1Client(TL1Client client)
                              throws TL1Exception

Register the client implementation with this TL1Session to receive messages using callbacks. The TL1Client interface must be implemented by all applications that wish to send and receive messages asynchronously. The interface provides callback methods which avoids pooling of the responses. The callback methods are invoked automatically when a response is received.

This method should be called only after the open method since it expects a valid session id.

Parameters:

client - TL1Client implementation.

Returns:

Unique client id value as a String.

Throws:

If - the TL1Client is already registered or if connection is not established with any TL1 device.

See Also:

TL1Client

getTL1Client

public TL1Client getTL1Client(java.lang.String clientId)

Gets the TL1Client for the given clientId. If the TL1Client for the given clientId was not added in this session, this method returns null.

Parameters:

clientId - String, represents the TL1ClientId.

Returns:

TL1Client corresponding to this clientId.

Since:

TL1 API 4

getTL1ClientIdList

public java.lang.String[] getTL1ClientIdList()

Gets the TL1ClientId lists associated with this Session.

Returns:

String array containing TL1ClientIds.

Since:

TL1 API 4

getTL1ClientId

public java.lang.String getTL1ClientId(java.lang.String mtag)

Gets the clientId for the given Message tag. If the message is send with the particular cliendId, then you can retrieve the clientId by using the message tag return during the send() method.

If the messsage is sent with the particular valid clientId then it will return the same clientId. If the message is sent without clientId then this method will return the clientId as "ALL". If it is invalid message tag then this method will return null.

Parameters:

mtag - Message tag as a String, whose clientId is needed.

Returns:

String represents clientId of the respective mtag.

Since:

TL1 API 4

See Also:

removeTL1Client

public boolean removeTL1Client(java.lang.String clientId)

Unsubscribe the client implementation from receiving callbacks. This removes the TL1Client implementation from the session list. However, other TL1Clients registered with the TL1Session will continue to receive the messages passed by the TL1Session.

Parameters:

clientId - Unique id obtained using the addTL1Client method.

Returns:

true, if the TL1Client is unsubscribed or false otherwise.

setMessageFormatter

public void setMessageFormatter(MessageFormatter mesgFormatter)

Register the MessageFormatter implementation with this Session for modifying the messages sent to the device and also received from the device.

Parameters:

mesgFormatter - MessageFormatter instance.

See Also:

MessageFormatter

setAccruePartial

public void setAccruePartial(boolean accruePartial)

This method is used to specify how the message is to be handled, if the message is recieved in parts(that is the whole message is not received at the same time,but rather the message is received only in several pieces before the terminating semi-colon is received). This happens when the Textblock of the response message is very big. In this case,the message will be broken into several chunks,and hence will not be passed as a single unit. If the 'flag' is set to false, it will cause the application to receive partial messages as and when the chunks of the same message arrive. Otherwise if the flag is true,the TL1Session will accumulate all the partial messages till it receives the complete message with the terminator character,that is,the semicolon (";"). This method does not applicable for SyncSend method.

Parameters:

flag - true if partial message is to be accumulated till the end of the message,else false which means that the partial messages will be sent to the application immediately,without waiting for the end of the message.

isAccruePartial

public boolean isAccruePartial()

To get the mode of processing the partial messages. (that is to determine whether or not,the partial messages are being accumulated by the TL1Session,till the terminator character of the message is received,or to pass on the pieces of the output message to the application,as and when the different pieces of the same message arrive.)

True - Partial messages get accumulated till the terminating character, that is,the semicolon is received,otherwise false. By default this flag will be true.

Returns:

true if partial messages are accumulated till the end of the message(the terminator semicolon ";") is reached, otherwise false.

removeMessageFormatter

public void removeMessageFormatter()

Unsubscribes the MessageFormatter implementation from this Session.

getMessageFormatter

public MessageFormatter getMessageFormatter()

Gets the MessageFormatter implementation registered with this Session.

Returns:

MessageFormatter instance registered with this session.

See Also:

MessageFormatter

setMessageRationalizer

public void setMessageRationalizer(MessageRationalizer rationalizer)

Register the MessageRationalizer implementation with this Session for rationalizing the messages sent to the device and also received from the device.

Parameters:

rationalizer - MessageRationlizer instance.

Since:

TL1 API 4

See Also:

getMessageRationalizer

public MessageRationalizer getMessageRationalizer()

Gets the MessageRationalizer implementation registered with this Session.

Returns:

MessageRationalizer instance registered with this session.

Since:

TL1 API 4

See Also:

removeMessageRationalizer

public void removeMessageRationalizer()

Unsubscribes the MessageRationalizer implementation from this Session.

Since:

TL1 API 4

setConnectionHandler

public void setConnectionHandler(ConnectionHandler connHandler)

Register the ConnectionHandler implementation with this Session. The implementation will be invoked while opening and closing the connection with the device.

Parameters:

connHandler - ConnectionHandler instance.

See Also:

ConnectionHandler

removeConnectionHandler

public void removeConnectionHandler()

Unsubscribe the ConnectionHandler implementation from this Session.

getConnectionHandler

public ConnectionHandler getConnectionHandler()

Gets the ConnectionHandler instance registered with this session.

Returns:

ConnectionHandler instance registered with this session.

See Also:

ConnectionHandler

setConnectionListener

public void setConnectionListener(ConnectionListener connListener)

Register the ConnectionListener implementation with this Session. This will enable you to take necessary action when the connection between the manager and the device goes down.

Parameters:

connListener - ConnectionListener instance.

See Also:

ConnectionListener

removeConnectionListener

public void removeConnectionListener()

Unsubscribe the ConnectionListener implementation from this Session.

getConnectionListener

public ConnectionListener getConnectionListener()

Gets the ConnectionListener instance registered with this session.

Returns:

ConnectionListener instance registered with this session.

getTransportProvider

public TL1TransportProvider getTransportProvider()

Gets the TL1TransportProvider implementation registered with this session.

Returns:

TL1TransportProvider instance registered with this session.

setTransportProvider

public void setTransportProvider(TL1TransportProvider provider)

Register the transport protocol implementation with this Session for communication between the manage and the agent. This implementation must be set on the Session before calling the open method. Otherwise, the default transport protocol (TCP) is used.

Parameters:

provider - TL1TransportProvider implementation.

See Also:

TL1TransportProvider, TcpTransportImpl

getSessionId

public java.lang.String getSessionId()

Gets the session id for this Session. You must call this method after establishing a connection with the TL1Device. Otherwise, it returns null.

Returns:

session id as a String. Returns Null, if the session is in the TL1Session.NASCENT, otherwise the sessionid.

getSessionProperties

public java.util.Hashtable getSessionProperties()

Gets the properties associated with this Session as a Hashtable. The property list contains the following items.

mode

sessionId

tl1TransportProvider

keepAlive

keepAliveMessage

keepAliveInterval

timeout

retries

requestQueueSize

notificationQueueSize

sessionClassifier

messageFormatter

connectionHandler

connectionListener

tl1Parser

tl1Clients

Returns:

Hashtable containing session properties.

getConnectionProperties

public java.util.Hashtable getConnectionProperties()

Gets the connection parameters as a Hashtable. The connection parameters include the parameters passed to the open method.

Returns:

Hashtable containing connection parameters associated with this Session.

open

public java.lang.String open(java.util.Hashtable params)
                      throws TL1Exception

Establishes a connection with the TL1 device using the parameters specified in the Hashtable.

This method must be called after registering the transport protocol implementation with this Session if the transport protocol used is different from TCP. Upon establishing the connection, this method returns a unique session id. Calling this open method again in the preconnect of the ConnectionHandler, will make the loop infinite.

Once the connection is successfully established, the receive and process tasks are started based on the settings made in the TL1API.

Parameters:

params - Hashtable containing parameters needed for establishing a connection with the TL1 device.

Returns:

Session id as a String.

Throws:

TL1Exception - If the given parameters is invalid.(i.e. null or Invalid Host etc). It throws even if you open already open TL1Session.

ConnectionDownException - If error occurs while establishing a connection

open

public java.lang.String open(java.lang.String remoteHost,
                             int remotePort)
                      throws TL1Exception

Establishes a socket(TCP) connection with the TL1 device. The parameters remoteHost and remotePort are put in a Hashtable and passed to the open(Hashtable) method to open a TCP connection. Upon successfully establishing a connection, this method returns a unique session id.

Once the connection is successfully established, the receive and process tasks are started based on the settings made in the TL1API.

Parameters:

remoteHost - Host name of the device as a String.

remotePort - Port number as an int.

Returns:

session id as a String.

Throws:

TL1Exception - If the given parameters is invalid.(i.e. null or Invalid Host etc). It throws even if you open already open TL1Session.

ConnectionDownException - If error occurs while establishing a connection

setKeepAlive

public boolean setKeepAlive(TL1Message tl1message,
                            int freq)

Maintain connection with the device when messages are not sent by the application for a long time. This is done since most TL1 devices close their connection if there is no interaction between the manager and agent. To avoid such circumstances, the application must use this method to send messages periodically when there is no such interaction.

Parameters:

tl1message - Keep Alive message.

freq - Keep Alive interval as int value.

Returns:

true, If the mode is Normal and the keep alive message is an instance of TL1InputMessage and interval is greater than zero. false otherwise.

Since:

TL1 API 3

See Also:

startKeepAlive(), stopKeepAlive()

startKeepAlive

public void startKeepAlive()

Starts the keep alive process after setting the necessary parameters like TL1Message and keepalive interval. This process can be stopped using the stopKeepAlive method.

Since:

TL1 API 3

See Also:

stopKeepAlive()

stopKeepAlive

public void stopKeepAlive()

Stops the keep alive process. This process can be resumed using the startKeepAlive method.

Since:

TL1 API 3

See Also:

startKeepAlive()

setIdleTimeMonitor

public void setIdleTimeMonitor(long inputInvl,
                               long outputInvl,
                               IdleTimeMonitor idleTmMon)

Registers the IdleTimeMonitor with this session for idle time monitoring of both Input and Output Messages. Here inputmessage refers to the message being sent out from this session and outputmessage refers to the message being received through this session.

Parameters:

inputInvl - idle time allowed between two Input messages.

outputInvl - idle time allowed between two Output messages.

idleTmMon - IdleTimeMonitor implementation.

Since:

TL1 API 4

getIdleTimeMonitor

public IdleTimeMonitor getIdleTimeMonitor()

Gets the registered IdleTimeMonitor implementation.

Returns:

IdleTimeMonitor implementation.

Since:

TL1 API 4

removeIdleTimeMonitor

public void removeIdleTimeMonitor()

Unregisters the IdleTimeMonitor with this session.

Since:

TL1 API 4

getInputInterval

public long getInputInterval()

Gets the input interval set for this session.

Returns:

long value that gives the idle input interval allowed for this session.

Since:

TL1 API 4

getOutputInterval

public long getOutputInterval()

Gets the output interval set for this session.

Returns:

long value that gives the idle output interval allowed for this session.

Since:

TL1 API 4

dropInputMsgInCallback

public void dropInputMsgInCallback(boolean flag)

Drop the TL1InputMessages in callback. Some TL1 devices will echo back input messages that are sent. By default, the TL1Session drops these echoed input messages. But if the application wishes to see the echoed input messages, they can use this method and set the flag to false.

Parameters:

flag - If flag is set to false, echoed TL1InputMessages will be given to the application's callback method registered. If the flag is set to true, input messages are dropped.

isDroppedInputMsgInCallback

public boolean isDroppedInputMsgInCallback()

Method to get the status of the flag which indicates whether or not the echo of TL1InputMessage is dropped in the callback(..)

Returns:

boolean value that indicates whether input messages are dropped in callback or not.

true indicates that echo of TL1InputMessage is dropped. false indicates that echo of TL1InputMessage is not dropped.

setParser

public void setParser(TL1Parser par)

Set the parser instance with this Session for parsing the messages.

You can write your own TL1 parser implementing the TL1Parser interface and set it in this Session for parsing the messages. By default, Session uses the default message parser (com.adventnet.tl1.parser.TL1MessageParser).

Parameters:

par - Implementation of TL1Parser.

See Also:

TL1Parser, TL1MessageParser

getParser

public TL1Parser getParser()

Gets the TL1 parser instance registered with this Session.

Returns:

TL1Parser instance associated with this session.

See Also:

TL1Parser

checkRequests

public java.util.Vector checkRequests()

Gets the correlation tag of all the pending requests in this Session. If the TL1Client is registered with the Session, this method returns a empty vector.

Returns:

Vector containing message tags as String.

See Also:

getResponses(java.lang.String), setRequestQueueSize(int)

checkNotifications

public java.util.Vector checkNotifications()

Gets the autonomous tag of all the notifications received from the agent which exists in the queue. If the TL1Client is registered with the Session, this method returns a empty vector.

Returns:

Vector containing notification message tags as String.

Since:

TL1 API 3

getRequest

public TL1Message getRequest(java.lang.String mtag)

Gets the request message for the given correlation tag.

Parameters:

mtag - message tag for which request message is needed.

Returns:

TL1Message if the request message exists in the queue for the given message tag, otherwise returns null.

Since:

TL1 API 3

getResponses

public java.util.Vector getResponses(java.lang.String mtag)

Gets all the responses for the given correlation tag. If the TL1Client is registered with the Session, this method returns a empty vector.

Parameters:

mtag - Message tag as a String, whose response is needed.

Returns:

Vector of TL1Messages arrived for the given correlation tag If response is not received for the given correlation tag or if the given correlation tag is not in the queue, this method returns a empty vector.

Since:

TL1 API 3

getNotifications

public java.util.Vector getNotifications(java.lang.String mtag)

Gets all the notifications for the given autonomous tag. If TL1Client is registered with the Session, this method returns a empty vector.

Parameters:

mtag - Message tag as a String whose notification is needed.

Returns:

Vector of TL1Messages arrived for the given autonomous tag. If notification is not received for the given tag or if the given tag is not in the queue, then this method returns a empty vector.

Since:

TL1 API 3

send

public java.lang.String send(TL1Message msg)
                      throws TL1Exception

Sends a non-blocking request to the TL1 device. This method returns the correlation tag of the request sent. The responses from the TL1 device will be given to all the clients registered with this Session.

In the case of Agent mode, this method sends any TL1Message (except INVALID_TL1_MESSAGE) without queuing.

Parameters:

msg - request message as an instance of TL1Message.

Returns:

message tag of the request sent.

Throws:

TL1Exception - If the message is not a TL1InputMessage or if TL1Message is null or invalid and if it in craftmode.

ConnectionDownException - if there is a problem while sending the message to the peer.

send

public java.lang.String send(TL1Message msg,
                             java.lang.String tcid)
                      throws TL1Exception

Sends a non-blocking request to the TL1 device. This method returns the correlation tag of the request sent. The responses are given only to the client specified by the tcid string in the case of Manager mode.

In the case of Agent mode, this method sends any TL1Message (except INVALID_TL1_MESSAGE) without queuing.

Parameters:

msg - request message as an instance of TL1Message.

tcid - TL1Client ID as a String.

Returns:

Returns correlation tag of the request sent in case of Manager mode and -1 in case of Agent mode.

Throws:

TL1Exception - If the message is not a TL1InputMessage or if TL1Message/client is null or if the client id is invalid.

ConnectionDownException - if there is a problem while sending the message to the peer.

send

public java.lang.String send(byte[] tl1Message)
                      throws TL1ParserException,
                             TL1Exception

Sends a non-blocking request to the TL1 device. The given byte array is parsed by the parser registered with this Session and the parsed message is sent to the device. This method returns the correlation tag of the request sent. In this case, the responses are given to all the clients registered with the Session.

Parameters:

tl1Message - request message as a byte[].

Returns:

correlation tag of the request sent.

Throws:

TL1Exception - If the message is not a TL1InputMessage or if TL1Message is null or invalid and if it in craftmode.

TL1ParserException - if the message is not compliant with the bellcore standards.

ConnectionDownException - if there is a problem while sending the message to the peer.

send

public java.lang.String send(byte[] tl1Message,
                             boolean parseFlag)
                      throws TL1ParserException,
                             TL1Exception

Sends a non-blocking message to the TL1 entity (manager or agent). This method can be used both in Normal and Craft mode.

If the parseFlag is set to true, this method parses the given byte array before sending it to the device. If the parseFlag is set to false, this method sends the byte array as a raw data.

The method returns the correlation tag of the request sent if the if the parseFlag is set to true. It returns -1 if the flag is not set (craft mode).

In all cases, the responses are given to all the clients registered with this Session.

Parameters:

tl1Message - request message as a byte[].

parseFlag - boolean value which indicates whether the message has to be parsed or not.

true indicates message has to be parsed (normal mode). false indicates message not to be parser(normal mode as well as craft mode).

Returns:

message tag as a String.

Throws:

TL1Exception - If the message is not a TL1InputMessage or if TL1Message is null or invalid and if it in craftmode.

TL1ParserException - if the message is not compliant with the bellcore standards.

ConnectionDownException - if there is a problem while sending the message to the peer.

syncSend

public TL1Message syncSend(byte[] msg)
                    throws TL1ParserException,
                           TL1Exception

Sends a request to the TL1 device in blocking mode. This method parses the given byte array using the parser associated with this session. It then sends the request to the device and waits for a response till the session timeout period. If the response arrives before the timeout period, the response is returned as a TL1Message object. Otherwise, it returns null.

Parameters:

msg - request message as a byte[].

Returns:

TL1Message if it comes before the session timeout. Otherwise returns null.

Throws:

TL1Exception - If the message is not a TL1InputMessage or if TL1Message is null or invalid and if it in craftmode.

TL1ParserException - if the message is not compliant with the bellcore standards.

ConnectionDownException - if there is a problem while sending the message to the peer.

Since:

TL1 API 3

syncSend

public TL1Message syncSend(TL1Message msg)
                    throws TL1Exception

Sends a request to the TL1 device in blocking mode. This method sends the given message to the device and waits for a response till the session timeout period. If the response is received before the timeout period, the response is returned as a TL1Message object. Otherwise, it returns null.

Parameters:

msg - Request message to be sent to the device as an instance of TL1Message.

Returns:

TL1Message if it comes before the session timeout. Otherwise returns null.

Throws:

TL1Exception - If the message is not a TL1InputMessage or if TL1Message is null or invalid and if it is in craftmode.

ConnectionDownException - if there is a problem while sending the message to the peer.

isConnected

public boolean isConnected()

Check the status of this Session. This method is called to check if the connection with the device exists or not.

Returns:

true if connection exists. false otherwise.

close

public void close()
           throws TL1Exception

Closes the tcp connection to the device but the (TL1API.Callback_N_Timeout ) thread associated with this session will not be dequed.

Throws:

TL1Exception - if there is a problem while closing the connection with the device or if the Session is in TL1Session.CLOSED state.

cleanup

public void cleanup()

This method is used to cleanup the threads associated with this session like (TL1API.RECEIVE_N_PROCESS, TL1API.CALLBACK_N_TIMEOUT etc..) , close the logstream if any associated with this session and all the TL1Session properties will get thier default values. This method should be called called after closing the TL1Session or the session is in TL1Session.CONNECTION_DOWN state and finally the sessionstate is changed to TL1Session.NASCENT.

Since:

TL1 API 4

getRetries

public int getRetries()

Gets the number of retries before the timeout period. The default number of retries is 0.

Returns:

retries value used by the session.

setRetries

public void setRetries(int retries)

Set the number of retries to be performed before timeout. The default number of retries is 0.

Parameters:

retries - The retries value(greater than zero) to be used by the session.

getTimeout

public int getTimeout()

Gets the timeout value. The timeout value is the time to wait for the first response in milli seconds before attempting a re-transmission. The default value of timeout is 5000 milliseconds.

Returns:

The timeout value (greater than zero) in milli seconds used for monitoring the request.

setTimeout

public void setTimeout(int timeout)

Set the timeout value. The default value of timeout is 5000 milliseconds. The timeout in the TL1InputMessage overrides the timeout value in session.

Note : The timeout value in the application should be greater than the timeout set in the Session.

Parameters:

timeout - The timeout value to be used for monitoring the request.

See Also:

TL1InputMessage.setTimeout(int)

setAppendFront

public void setAppendFront(java.lang.String prefix)

Appends the given String to the front of each Input Message before it sends to the TL1Device. AppendFront String in the TL1InputMessage overrides the AppendFront value in session. This method is not effective if the session is in agent mode.

Parameters:

prefix - String to be appended at the front of each Input Message.

See Also:

TL1InputMessage.setAppendFront(java.lang.String), isSetToAgentMode()

getAppendFront

public java.lang.String getAppendFront()

Gets the string appended to the front of each Input Message.

Returns:

String appended to the front.

See Also:

TL1InputMessage.getAppendFront()

setAppendEnd

public void setAppendEnd(java.lang.String suffix)

Appends the given String to the end of each Input Message before it sends to the TL1Device. AppendEnd String in the TL1InputMessage overrides the AppendEnd value in session. This method is not effective if the session is in agent mode.

Parameters:

suffix - String to be appended at the end of each Input Message.

See Also:

TL1InputMessage.setAppendEnd(java.lang.String), isSetToAgentMode()

getAppendEnd

public java.lang.String getAppendEnd()

Gets the string appended to the end of each Input Message.

Returns:

String appended to the end.

See Also:

TL1InputMessage.getAppendEnd()

setSessionClassifier

public void setSessionClassifier(java.lang.Object obj)

Stores application specific details. This value is not used by the API.

Parameters:

obj - Object instance.

getSessionClassifier

public java.lang.Object getSessionClassifier()

Gets the details set on this Session using the setSessionClassifier method.

Returns:

Returns an Object instance.

getConnectionEvent

public ConnectionEvent getConnectionEvent()

Gets the connection event of the Session at present.

Returns:

Returns an ConnectionEvent instance.

Since:

TL1 API 4

See Also:

setRequestQueueSize

public void setRequestQueueSize(int size)

Set the size of the request queue in the case of non-blocking mode. The default size of the request queue is 1000.

Parameters:

size - int value greater than zero.

getRequestQueueSize

public int getRequestQueueSize()

Gets the size of the request queue associated with this session. The default size of the queue is 1000.

Returns:

queue size as an int value.

setNotificationQueueSize

public void setNotificationQueueSize(int size)

Set the size of the notification queue in non-blocking mode which stores all the autonomous messages. The default size of the notification queue is 1000.

Parameters:

size - int value greater than zero

getNotificationQueueSize

public int getNotificationQueueSize()

Gets the size of the notification queue associated with this Session. The default size of the notification queue is 1000.

Returns:

queue size as an int value.