11 Creating Java Connection Handlers

This chapter describes how to create Java and State Table implementations for network element (NE) connections and atomic action scripts that implement MML commands for Oracle Communications ASAP.

The following sections provide information about the Java connection handler:

• About Java Network Element Connection Handlers

• Creating New Network Element Connection Handlers

• Generating a Telnet Network Element Connection Handler Implementation

• Generating a Custom NE Connection Handler Implementation

• About Communication Protocol Parameters

• Creating Connection Methods and Helper Classes

• Creating a Provisioning Prompt

• Enabling Loopback Mode

• Implementing Secure Login Functionality

• Connection Management Issues

• Creating a Java Telnet Connection Class

The NE Connection Handlers with Java implementation manage the connections with network elements based on the communication parameters in an NE Template.

About Java Network Element Connection Handlers

The Java implementation NE Connection Handler needs to implement the IConnectionHandler interface, which provides a common interface for interacting with connections and requires few methods to be written.

Different types of NE Connection Handlers can be created:

• Telnet: When you create a new telnet NE Connection Handler, it generates code for telnet connections. This extends the telnet connection to support the interface. The NE Connection Handler editor indicates where additional code is required.

• Custom: Create this NE Connection Handler if the connections are not telnet. Custom Connection Handlers generate a skeleton to implement the IconnectionHandler and extends the base NE connection class. The NE Connection Handler editor indicates where additional code is required.

Creating New Network Element Connection Handlers

You use the NE Connection Handler Wizard to create new NE Connection Handler entities.

To create a new NE Connection Handler entity:

1. Select Studio, select New, select Activation, then select NE Connection Handler.

   The NE Connection Handler Wizard appears.

2. Select the project for this element and enter a name for the entity.

3. (Optional) Select a location for the entity.

   By default, Design Studio saves the entity to your default workspace location. You can enter a folder name in the Folder field or select a location different from the system-provided default. To select a different location:

   1. Click the Folder field Browse button.

   2. Navigate to the directory in which to save the entity.

   3. Click OK.

4. Click Finish to create the NE Connection Handler.

Generating a Telnet Network Element Connection Handler Implementation

You need to generate a Telnet Network Element Connection Handler implementation if you want to extend a telnet connection to support the interface.

To generate a Telnet NE Connection Handler Implementation:

1. Create an NE Connection Handler with the NE Connection Handler Wizard.

   See "Creating New Network Element Connection Handlers" for more information.

2. In the Cartridge view, double-click the entity to open the NE Connection Handler editor.

3. In the editor, enter a description and select Java Connection Handler as the NE Connection Handler type.

4. Click Add.

   The Vendor, Technology, and Software Load fields are populated.

5. Click New.

   The Studio Activation Java Connection Handler Wizard appears.

6. Ensure that Telnet appears in the Connection Type field.

   
   

   Note: Ensure that a dot does not precede the package name. If a dot precedes the package name, remove it.

   
   

7. Click Finish.

   The code is generated ready for implementation.

   
   

   Note: The code is generated once but not synchronized (that is, it will not be rewritten and the developer owns the generated class).

   
   

Generating a Custom NE Connection Handler Implementation

Generate a custom NE Connection Handler implementation if you want to extend the base NE connection class of a connection other than telnet.

To generate a custom NE Connection Handler implementation:

1. Create an NE Connection Handler with the NE Connection Handler Wizard.

   See ""Creating New Network Element Connection Handlers"Creating New NE Connection Handlers" for more information.

2. In the Cartridge view, double-click the entity to open the NE Connection Handler editor.

3. In the editor, enter a description and select Java Connection Handler as the NE Connection Handler type.

4. Click Add.

   The vendor, technology, and software Load fields are populated.

5. Click New.

   The Studio Activation Java Connection Handler Wizard appears.

6. In the Connection Type field, select Custom.

   
   

   Note: Ensure that a dot does not precede the package name. If a dot precedes the package name, remove it.

   
   

7. Click Finish.

   The code is generated ready for implementation.

   
   

   Note: The code is generated once but not synchronized (that is, it will not be rewritten and the developer owns the generated class).

   
   

About Communication Protocol Parameters

Communication parameters enable you to configure the information required to communicate through one of the ASAP-supported device interfaces. When the NEP command processor connects to an NE, these parameters are loaded into memory and used in the connection process. When the NEs are connected, they are loaded as NE program (State Table or Java program) variables prior to the execution of each program. This method ensures that the program has access to any user-defined information through the communication parameters.

Communication parameters can also be defined on the work order. These parameters defined on the work order override the statically pre-configured values contained in an ASAP cartridge. This feature is used for dynamic NE routing (see "Configuring Dynamic Routing").

The NEP supports the following interfaces to the downstream network:

• Dedicated and dialup serial

• TCP/IP socket (standalone and in conjunction with the JInterpreter)

• Telnet

• SNMP interfaces with which EMSs and NEs can be configured.

• Hostpad device interfaces

• LDAP, as the standard for uniform access to directory services.

• CORBA over IIOP (in conjunction with the JInterpreter)

• C/C++

• CAPI

• X.25, X.29, and TL1

• SFTP

Refer to the ASAP Developer Reference for information on the action functions that support for these interfaces.

Interfaces using such technologies can be developed rapidly due to their script-driven nature, requiring little or no additional software development. These supported network interfaces allow telecommunications carriers to interface with external systems using simple scripts, thereby isolating end users from specific communication details.

Specifying Global or Local Communication Parameters

Using Design Studio, you can specify global communication parameters that apply to all connections to a particular NE. You can also customize a connection with local parameters that apply only to that connection.

Typically, a parameter is defined for a specific host NE and connection. If the various host NEs and connections share the same parameter values, however, the number of communication parameter entries can be reduced.

For example, you must define 33 mandatory X29 Pad interface-specific communication parameters for the X29 Pad interface. Most of these parameters have the same value. Defining each parameter separately for every X29 connection to each host NE results in the following:

• Considerable effort to configure these parameters one at a time.

• Additional memory resources required by the NEP to maintain these parameters in memory.

You can resolve these issues by defining one common set of parameters for all X29 connections to avoid repetition. Specifically, for a particular device interface, you can define parameters with the following groupings:

• All host NEs and all connections (common host, common device).

• All host NEs and a specific connection (common host, specific device).

• A specific NE and all connections to that NE (specific host, common device).

• A specific NE and a specific connection (specific host, specific device).

These parameters are processed in the order they are listed. They override any previous entries defined for the host NE and the device of a particular command processor in the NEP. Communication parameters defined on the work order override preconfigured values if the NEP is configured for dynamic NE routing.

User-defined Parameters

Communication parameters are available to every State Table or Java method that is executed. You can specify various parameters that can be host NE or device-specific on the State Table or the Java provisioning method, and then the State Tables or Java provisioning methods can employ host NE or device-specific processing. For example, if a dialup connection requires delay, a communication parameter can be defined for use by the DIALUP State Table.

Device-specific Interface Parameters

Typically, a parameter is defined for a specific host NE and connection. If the various host NEs and connections share the same parameter values, those values can be defined once to avoid repetition.

To communicate with the NE, ASAP opens a connection through the device interface, writes data to the device, and reads data from the device using I/O-related communication parameters.

The following communication parameters apply only to serial, telnet, and other terminal-based interfaces:

• Terminal-based interface communication parameters.

• Serial interface communication parameters.

• Telnet interface communication parameters.

• Socket interface communication parameters.

• Generic interface communication parameters.

The following sections describe device interface types which are associated with mandatory parameters.

Table 11-1 illustrates the device types associated with each interface type:

Table 11-1 Interface – Device Type Matrix

Interface	Device Types	Applies to
Terminal-based communication devices	G – Generic Port Terminal-Based	State Tables
Terminal-based communication devices	T – Telnet Port	State Tables and Java
Terminal-based communication devices	D – Serial Port Dialup	State Tables
Terminal-based communication devices	H – Serial Port Hardwired	State Tables
Message-based communication devices	S – Socket Port	State Tables and Java
Message-based communication devices	M – Generic Port Message-Based	State Tables
Message-based communication devices	F – FTP Port	State Tables
Message-based communication devices	F - FTP Port for SFTP	State Tables and Java
Message-based communication devices	W – LDAP Port	State Tables and Java
Message-based communication devices	P – SNMP Port	State Tables
Message-based communication devices	C – CORBA	Java

Table 11-2 describes the communication parameters that apply for terminal based interfaces.

Table 11-2 Common Terminal-based Communication Parameters

Parameter	Default	Description
VS_WIDTH	-	Virtual Screen width.
VS_LENGTH	-	Virtual Screen length.
VS_CRLF_MAP	-	A boolean flag that you can set to map LF to CR_LF automatically. The default is set not to map.
GR_WAIT_TIMEOUT	-	The wait timeout period, in seconds, that the thread reading from the Virtual Screen waits for the thread writing to the Virtual Screen to notify it of any new data. Increase this value if the State Table processing fails before data arrives from the NE.

Generic Port Terminal Based and Generic Port Message-Based are specific to EDDs. For information on the communication parameters for these device types, see the discussion about generic EDD API parameters in the ASAP Server Configuration Guide.

tbl_comm_param contains communication parameters required for the NEP to communicate with various external systems. You must populate this table to configure communication parameters.

Table 11-3 lists and describes the parameter settings in the ASAP.cfg file to enable State Table interfaces. For more information about these parameters, see the discussion about NE API parameters in the ASAP Server Configuration Guide.

Table 11-3 State Table Interface Configuration Parameters

Interface	Parameter	Required	Default	Description
Serial NE	SERIAL_IF_SUPPORTED	Mandatory	1	Boolean flag. Specifies whether the serial NE interface should be enabled.
Telnet NE	TELNET_IF_SUPPORTED	Mandatory	1	Boolean flag. Specifies whether the Telnet NE interface should be enabled.
Socket NE	SOCKET_IF_SUPPORTED	Mandatory	1	Boolean flag. Specifies whether the socket NE interface should be enabled.
FTP NE	FTP_IF_SUPPORTED	Mandatory	1	Boolean flag. Specifies whether the FTP NE interface should be enabled. To perform NEP FTP services, you must use the State Table NEP FTP action functions. Refer to the ASAP Developer Reference for more information.
LDAP	LDAP_IF_SUPPORTED	Mandatory	1	Indicates whether LDAP is enabled.

To set up a control connection to the appropriate server, you must also set up the communication parameters in the SARM database table tbl_comm_param.

The XXX_IF_SUPPORTED variables are only relevant for loading protocol libraries used by State Tables. CORBA support is offered for Java provisioning only. There is no CORBA_IF_SUPPORTED variable in ASAP.cfg.

The following sections describe the required parameters for each interface.

CORBA Interface Communication Parameters

The CORBAConnection class provides basic functionality to connect to NEs with CORBA interfaces. Custom classes should inherit from this class and implement the connect() and disconnect() methods to an old CORBA OCA server which, has been replaced with a non-CORBA Java OCA server since ASAP 7.0.0. For example, the OCAConnection custom class implements the connection and disconnection methods to a CORBA OCA server.

Sample code is located in ASAP_Home\ASAP\samples\JeNEP\jenep_demo\CORBA\OCAConnection.java

The CORBAConnection class provides a wrapper around an ORB. The initialization of the ORB can be customized by extending CORBAConnection and overriding the functions getInitialArguments and getInitialProperties. Both of these values are used in the ORB.init call implemented in the connect method. The default is to use null for both arguments and properties, which loads the ORB provided by the JRE.

The “C” device type is used in tbl_comm_param and tbl_resource_pool to relate communication parameters to a CORBA device type.

The “C” device type is not supported for State Table MPM libraries.

In situations where the NEP is configured for LOOPBACK, all of the operations on CORBAconnection return success.

For more information on Class CORBAConnection and com.mslv.activation.jinterpreter, refer to the ASAP Java Online Reference.

Serial Port Hardwired Communication Parameters

The NEP server provides built-in support for serial port hardwired communications interfaces.

Table 11-4 lists and describes the serial port hardwired communication parameters that are in addition to the parameters described in Table 11-2, "Common Terminal-based Communication Parameters".

Table 11-4 Serial Port Hardwired Communication Parameters

Parameter	Default	Description
TTY	N/A	UNIX or Linux port. For a hardwired interface, this value is specific to each host. For a dialup interface, this value remains the same for all host NEs.
DIALUP_NUM	N/A	Dialup number. This parameter is required only for a dialup interface and is different for every NE.
OPEN_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to open the device. The wait timeout parameter is only applicable to the serial interface.
WRITE_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to write to the device.
READ_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to read from the device. Currently, this is only applicable to the socket interface.
DISABLE_PORT_ON_LOGIN	N/A	Determines whether the port should be disabled if login to the NE fails. If the parameter is equal to zero, then the port is not disabled.
BAUD	N/A	Baud rate for transmission. The valid values are '300', '600', '1200', '2400', '4800', '9600', and '19200'.
PARITY	N/A	The parity, which can be either odd, even, or no parity. Enter 'O' for odd, 'E' for even, and 'N' for no parity.
STOP	N/A	Number of stop bits per character. The valid values are '1' and '2'.
SIZE	N/A	Number of bits per character. The valid values are '5', '6', '7', '8'.

Serial Port Dialup Communication Parameters

The NEP server provides built-in support for serial port dialup communications interfaces.

Table 11-5 lists and describes serial port dialup communication parameters, in addition to the parameters described in Table 11-2, "Common Terminal-based Communication Parameters".

Table 11-5 Serial Port Dialup Communication Parameters

Parameter	Default	Description
TTY	N/A	UNIX or Linux port. For a hardwired interface, this value is specific to each host. For a dialup interface, this value remains the same for all host NEs.
DIALUP_NUM	N/A	Dialup number. This parameter is required only for a dialup interface and is different for every NE.
OPEN_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to open the device. The wait timeout parameter is only applicable to the serial interface.
WRITE_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to write to the device.
READ_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to read from the device. Currently, this is only applicable to the socket interface.
DISABLE_PORT_ON_LOGIN	N/A	Determines whether the port should be disabled if login to the NE fails. If the parameter is equal to zero, then the port is not disabled.
BAUD	N/A	Baud rate for transmission. The valid values are '300', '600', '1200', '2400', '4800', '9600', and '19200'.
PARITY	N/A	The parity, which can be either odd, even, or no parity. Enter 'O' for odd, 'E' for even, and 'N' for no parity.
STOP	N/A	Number of stop bits per character. The valid values are '1' and '2'.
SIZE	N/A	Number of bits per character. The valid values are '5', '6', '7', '8'.

Telnet Port Communication Parameters

The NEP server provides built-in support for a TCP/IP Telnet communications interface. You can enable and configure the NEP Telnet driver to communicate with NEs using the standard Telnet terminal emulation. In conjunction with the standard action functions and terminal-based virtual screen manipulation action functions, commands and command arguments can be constructed, parsed, sent, and received by the NE-specific State Table programs over such Telnet connections.

Table 11-6 lists and describes the State Table telnet port communication parameters, in addition to parameters described in Table 11-2, "Common Terminal-based Communication Parameters".

Table 11-6 Telnet Port Communication Parameters for State Tables

Parameter	Default	Description
SOCKET_CLIENT	N/A	Socket server or client. The only valid value is 'C' because the communication is a Telnet client. Not valid for the Java Telnet Interface.
HOST_NAME	HOST_CLLI	Machine name for the host NE.
HOST_IPADDR	N/A	Network IP address for the host NE.
PORT	23	Telnet service port.

ASAP also contains a Java telnet library that is based on the publicly available library found at http://www.javatelnet.org. A virtual screen implementation is provided to simplify data manipulation.

NEConnection is an abstract class defined in package jinterpreter. All JInterpreter connection classes must extend this class in order to be evocable by the NEP. Oracle Communications provides the TelnetConnection class, which integrates the telnet and virtual screen implementations provided by the telnet library.

The TelnetConnection class also supports a piped stream interface, similar to the raw input stream available from the underlying TCP/IP connection. The read, write and waitfor operations defined on TelnetConnection act on the stream to retrieve and send data. This interface leaves the incoming data in a stream format for simple parsing scenarios. In simple parsing situations, a provisioning activity may only need to pick off a simple response string from the NE. In these situations, it can be simpler to use a waitfor call to track the response from the NE rather than use the structured format of the virtual screen.

By default, both the virtual screen and piped stream are enabled by the TelnetConnection class. The method TelnetConnection.setStreamEnabled (boolean enabled) can be used to enable or disable the stream.

In situations where the NEP is configured for LOOPBACK, the InputStream and OutputStream returned by the StreamConnection always return success for every read and write call. The InputStream.read methods return a size read integer of 1 with the value set to an empty character ' '. All of the TelnetConnection send and VirtualScreen get/read calls always return success.

For information on the JInterpreter API for the Telnet connection class, refer to the ASAP Java Online Reference.

Table 11-7 lists and describes the Java telnet port communication parameters for the JInterpreter, in addition to parameters described in Table 11-2, "Common Terminal-based Communication Parameters".

Table 11-7 Telnet Port Communication Parameters for the JInterpreter

Parameter	Default	Description
HOST_USERID	N/A	User name.
HOST_PASSWORD	N/A	Password.
OPEN_TIMEOUT	5 seconds	Connection establishment timeout (in seconds).
READ_TIMEOUT	1 second	Timeout for the telnet read functions (in seconds).
HOST_NAME	N/A	Machine name for the host NE.
HOST_IPADDR	N/A	Network IP address for the host NE.
PORT	23	Telnet service port.
LOGIN_PROMPT	login:	Reserved. The login prompt expected in the telnet session.
PASSWORD_PROMPT	Password >	Reserved. The password prompt expected in the telnet session.

Note: The default TelnetConnection class uses parameters defined in tbl_comm_param (VS_LENGTH, VS_WIDTH, HOST_USERID, HOST_PASSWORD, HOST_NAME, HOST_IPADDR, PORT) to initialize the telnet session. A solutions developer may use the provided TelnetConnection class as a connection handler as configured in tbl_nep_asdl_prog. It is also possible to extend the TelnetConnection class to override the provided functionality. For instance, a solutions developer may wish to override the connect, login or disconnect methods to implement custom functionality. Refer to the Common Terminal-based Communication Parameters table for more information on virtual screen-related parameters.

SSH Telnet Communication Parameters

Table 11-8 contains the communication parameters for the SSH protocol in addition to parameters described in Table 11-2, "Common Terminal-based Communication Parameters".

Table 11-8 SSH Communication Parameters

Parameter	Default	Description
HOST_NAME	N/A	The machine name of the NE
HOST_IPADDR	N/A	The IP address of the NE
SSH_SUPPORT	TRUE	SSH is supported or not
SSH_PORT	22	The SSH port number
SSH_VERSION	SSH2	The SSH version; either SSH1 or SSH2
SSH_AUTH_METHOD	PASSWORD	The authentication method; either PASSWORD or PUBLIC_KEY.
SSH_PREF_PUBLIC_KEY	PUBLIC_KEY_SSHRSA	The preferred public key; either PUBLIC_KEY_SSHRSA or PUBLIC_KEY_SSHDSS.
SSH_PREF_CIPHER_CS	CIPHER_BLOWFISH_CBC	The preferred CS cipher; either CIPHER_BLOWFISH_CBC, CIPHER_TRIPLEDES_CBC, TWOFISH128_CBC, TWOFISH192_CBC, TWOFISH256_CBC, TWOFISH_CBC, CAST128_CBC, AES128_CBC, AES192_CBC, AES256_CBC
SSH_PREF_CIPHER_SC	CIPHER_BLOWFISH_CBC	The preferred SC cipher: either CIPHER_BLOWFISH_CBC, CIPHER_TRIPLEDES_CBC, TWOFISH128_CBC, TWOFISH192_CBC, TWOFISH256_CBC, TWOFISH_CBC, CAST128_CBC, AES128_CBC, AES192_CBC, AES256_CBC
SSH_PREF_MAC_CS	HMAC_MD5	The preferred CS message authentication; either HMAC_MD5 or HMAC_SHA1.
SSH_PREF_MAC_SC	HMAC_MD5	The preferred SC message authentication HMAC_MD5 or HMAC_SHA1.
SSH_PREF_COMP_CS	COMPRESSION_NONE	The preferred CS compression COMPRESSION_NONE or COMPRESSION_ZLIB.
SSH_PREF_COMP_SC	COMPRESSION_NONE	The preferred SC compression COMPRESSION_NONE or COMPRESSION_ZLIB.
VS_TYPE	vt100	Virtual screen type.
VS_WIDTH	80	Virtual screen width.
VS_LENGTH	24	Virtual screen length.

Login information for the NE/device needs to be populated in the Control database (TBL_CLASSB_SECU) in order for SSH to work. Table 11-9 lists and describes the SSH security parameters for the SSH protocol that should be stored in the Control database. For more information about securely storing NE login information, see Implementing Secure Login Functionality.

Table 11-9 SSH Security Parameters

Parameter	Default	Description
HOST_USERID	-	User name to log in to the NE.
HOST_PASSWORD	-	For telnet: the password authentication: user password to login the NE. For SSH: Public key authentication: The passphrase used for the private key.
PRIV_KEY_FILE	-	The machine name of the NE

Socket Port Communication Parameters

The NEP server provides built-in support for a TCP/IP socket-based communications interface. You can enable and configure the NEP socket driver to communicate with NEs using message-based communication. In conjunction with the standard action functions, message building action functions, and message I/O action functions, NE-specific messages can be constructed and parsed, sent, and received by the NE-specific State Table programs over such socket connections.

A SocketConnection class is provided which wrappers a java.net.Socket instance. The SocketConnection class can be extended to provide custom functionality on top of the conventional socket interface. A SocketConnection implements the StreamConnection interface. The StreamConnection interface defines methods common to stream-based protocols.

By default, the connect method uses the communication parameters defined by HOST_NAME, HOST_IPADDR and PORT.

In situations where the NEP is configured for LOOPBACK, the InputStream and OutputStream returned by the StreamConnection always return success for every read and write call. The InputStream.read methods return a size read integer of 1 with the value set to an empty character ' '.

For information on the JInterpreter API for the Socket connection class, refer to the ASAP Java Online Reference.

Table 11-10 Socket Port Communication Parameters

Parameter	Default	Description
PORT	N/A	Port of the remote socket listener.
OPEN_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to open the device. The wait timeout parameter is only applicable to the serial interface.
WRITE_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to write to the device.
READ_TIMEOUT	1	The wait timeout period, in seconds, that ASAP waits to read from the device. Currently, this is only applicable to the socket interface.
DISABLE_PORT_ON_LOGIN	0	Determines whether the port should be disabled if login to the NE fails. If the parameter is equal to zero, then the port is not disabled.
SOCKET_CLIENT	N/A	Socket server or client. The only valid value is 'C' because the communication is a Socket client.
HOST_NAME	HOST_CLLI	Machine name for the host NE.
HOST_IPADDR	N/A	Network IP address for the host NE.
SOCKET_FAMILY	2	The only valid value is '2' because only the Internet address family is supported.

FTP Port Communication Parameters

The NEP server provides built-in support for a TCP/IP FTP client interface. This client interface allows for FTP and SFTP communication. You can enable and configure the NEP FTP driver to communicate with NEs for file transfer. In conjunction with the standard action functions, UNIX or Linux file management action functions, and FTP action functions, files, and contents of files can be constructed, managed, sent, and received by the NE-specific State Table programs over such FTP connections.

You can write a State Table Program using the FTP action functions provided by the NEP. The request is submitted to the NE and the NE FTP server analyzes the request and takes the proper FTP-related functions. The NE sends the correct responses back to the NEP through the FTP control and data connections. Response messages are stored in the appropriate diagnostic files.

Numerous FTP commands and choices are provided by the FTP protocol specification to control the way a file is transferred. Although the NEP FTP does not use all possible options, it does support the minimum requirements for a standard FTP client.

For more information on FTP action functions, see the ASAP Developer Reference.

FTP uses the following TCP connections to transfer files:

• Control Connection – Initiated by the client (NEP FTP) to a server (NE FTP server). Prior to this connection the server does a passive open on the port for FTP (port 21) and waits for a client to connect. The control connection stays alive during the entire communication session between client and server. This connection is used for sending and receiving FTP commands and replies (error codes, status information, etc.).

• Data Connection – Created each time a file (or directory listing, etc.) is transferred between the client and server. The client uses an ephemeral port, which is supplied by the system host, for each connection.

The following diagram shows the high level functional architecture of the NEP FTP and the NE FTP server based upon the RFC 959 FTP model. The diagram shows the two TCP connections and the respective components for interpreting FTP commands and transferring files. FTP users (State Table programs) do not deal with FTP commands and replies. These are handled by the protocol interpreters on both sides and whenever a file is about to be transferred, a data connection is established.

Figure 11-1 NEP FTP and NE FTP Server Functional Architecture

The NEP FTP is the FTP client component of the NEP which provides State Table programs the capability to send and receive files to and from an NE, and to also delete files.

The NEP Multi-Protocol Manager handles the initial FTP control connection to the NE. After the connection is successful, the FTP State Table commands are interpreted and the appropriate FTP commands are sent to the NE FTP server through the control connection.

Whenever a file is transferred, the NEP FTP creates a data connection and the file is transferred through that connection.

FTP communication is a core ASAP NE interface. The SARM database table tbl_comm_param must contain entries for the remote server address, port, host name, user ID, and password. You must also set up the device type and device value in the table which are F and COMMON_DEVICE_CFG respectively.

For information about tbl_comm_param, see tbl_comm_param in the ASAP Developer's Guide.

Table 11-11 FTP Port Communication Parameters

Parameter	Default	Description
HOST_USERID	None	User name.
OPEN_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to open the device. The wait timeout parameter is only applicable to the serial interface.
WRITE_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to write to the device.
READ_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to read from the device. Currently, this is only applicable to the socket interface.
DISABLE_PORT_ON_LOGIN	N/A	Determines whether the port should be disabled if login to the NE fails. If the parameter is equal to zero, then the port is not disabled.
HOST_NAME	HOST_CLLI	Machine name for the host NE.
HOST_IPADDR	N/A	Network IP address for the host NE.
PORT	21	Telnet service port.

Note: To complete a connection, either HOST_NAME or HOST_IPADDRESS must be provided, or both.

Table 11-12 lists the port parameters for SFTP communication.

Table 11-12 SFTP Port Communication Parameters

Parameter	Default
HOST_USERID	None	User name.
HOST_PASSWORD	None	Password associated with HOST_USERID.
HOST_NAME	HOST_CLLI	Machine name for the host NE.
HOST_IPADDR	N/A	Network IP address for the host NE.
PORT	22	Telnet service port.

Note: To complete a connection, either HOST_NAME or HOST_IPADDRESS must be provided, or both.

LDAP Port Communication Parameters

The NEP server enables ASAP to communicate with LDAP (Lightweight Directory Access Protocol) Directory Servers through the LDAP protocol using TCP/IP. Connectivity to LDAP Directory Servers (NEs) is provided by the Multi-Protocol Manager. The LDAP interface allows inquiries, additions, modifications, and deletions of records stored in LDAP-enabled directories. The LDAP interface is implemented using Version 3 of the LDAP protocol.

The LdapConnection class provides a wrapper around a netscape.ldap.LDAPConnection class. As with SocketConnection, it provides a simple interface for returning the underlying netscape.ldap.LDAPConnection class for manipulation. A solutions developer is free to extend the default LdapConnection class to implement custom functionality.

For more information on Class LdapConnection and com.mslv.activation.jinterpreter, refer to the ASAP Java Online Reference.

In situations where the NEP is configured for LOOPBACK, all operations on LdapConnection return success.

HOST_NAME or HOST_IPADDR represent a hostname to which to connect or a dotted string representing the IP address of this host.

Table 11-13 LDAP Port Communication Parameters

Parameter	Default	Description
HOST_USERID	None	User name.
OPEN_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to open the device. The wait timeout parameter is only applicable to the serial interface.
WRITE_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to write to the device.
READ_TIMEOUT	1.0	The wait timeout period, in seconds, that ASAP waits to read from the device. Currently, this is only applicable to the socket interface. 0 = no timeout.
DISABLE_PORT_ON_LOGIN	N/A	Determines whether the port should be disabled if login to the NE fails. If the parameter is equal to zero, then the port is not disabled.
HOST_NAME	HOST_CLLI	Machine name for the host NE.
HOST_IPADDR	N/A	Network IP address for the host NE.
PORT	389	the TCP or UDP port number to which to connect or contact.
LDAP_VERSION	2	LDAP version to use. If VERSION2, use 2. If VERSION3, use 3.
SIZELIMIT	2	The size of the search results set asked from the directory server. Minimum 1, Maximum 500.

TL1 Port Communication Parameters

TL1 is a communication standard for specifying information exchanges between Operations Support Systems (OSSs) and NEs. Several NEs and/or Element Management Systems use TL1 for communication with external systems. TL1 can be used in conjunction with Telnet or X.25 protocols.

TL1 support is provided in the NEP by writing C or C++ functions. These functions are typically written by the developer as part of the software customization.

Over Telnet, TL1 support refers to a number of ASAP State Table action functions that encapsulate much of the encoding and positional logic, required in the generation of TL1 messages. This simplifies the State Tables that generate TL1 command sequences.

To interface with NEs supporting TL1, the State Tables can do the following:

• Translate ASAP work orders and service actions, represented by atomic actions, into TL1 commands.

• Send the commands to the destination NE through various communication mechanisms supported by ASAP.

• Receive and retrieve TL1 acknowledgment and response.

• Transfer information back to the SARM and save it for later use.

For more information on the TL1 interface, see the ASAP Developer's Guide.

SNMP Port Communication Parameters

The SNMP option provides an interface to communicate with any SNMP NE through ASAP State Table programs.

You can write a State Table Program using SNMP action functions provided by the NEP. This request is submitted to the NE, and the SNMP agents can send traps back to the NEP and print to the ASAP diagnostic file.

The NEP SNMP manager provides SNMP agents with access to SNMP management operations through State Table action functions, and intercepts the management responses and SNMP traps. The NEP SNMP coexists with other interface types in the same NEP, including core interfaces such as TL1 and X.25/X.29.

ASAP processes each State Table program in an interactive mode by sending a command to an NE and waiting for a response. ASAP also processes more than one State Table program simultaneously with multiple connections to NEs.

Figure 11-2 illustrates the SNMP Manager interface.

Figure 11-2 SNMP Manager Interface

To interface with NEs supporting the SNMP, State Tables can do the following:

• Send requests to the agents.

• Receive traps from the agents.

• Receive trap messages from the agents, used to notify the NEP of errors and other significant events encountered during the process.

The NEP SNMP option supports SNMPv1, SNMPv2*, and SNMPv2c, including authentication, authorization, access control, and privacy.

For more information on the SNMP interface, see the ASAP Developer's Guide.

Table 11-14 SNMP Port Communication Parameters

Parameter	Default	Description
OPEN_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to open the device. The wait timeout parameter is only applicable to the serial interface.
WRITE_TIMEOUT	5	The wait timeout period, in seconds, that ASAP waits to write to the device.
READ_TIMEOUT	N/A	The wait timeout period, in seconds, that ASAP waits to read from the device. Currently, this is only applicable to the socket interface.
DISABLE_PORT_ON_LOGIN	N/A	Determines whether the port should be disabled if login to the NE fails. If the parameter is equal to zero, then the port is not disabled.

StreamConnection Interface

The StreamConnection interface allows a solutions developer to write JProcessor implementations independent of specific protocol APIs. This means that a single JProcessor implementation can reference only StreamConnection interface methods, and be able to switch underlying connection handler classes such as Socket and Telnet without having to modify the provisioning code.

All stream-based protocols such as socket and telnet implement the StreamConnection interface. See "Telnet Port Communication Parameters" and "Socket Port Communication Parameters" for more details.

For more information on the StreamConnection interface, refer to the ASAP Java Online Reference.

Creating Connection Methods and Helper Classes

Connection methods are used by ASAP core to establish a connection (also referred to as a device) and/or to login to an NE.

To implement a connection method and connection handler, you need to know:

• The NE activation interface and protocol

• The logic and parameters required for connecting and disconnecting to and from the NE

• Knowledge for implementing client protocols such as HTTP, Web Service, Corba, TCP/IP

• Knowledge about third party libraries or frameworks required to implement a non TCP/IP protocol. For example, Apache AXIS for WSDL defined Web Service, Apache Common HttpClient for HTTP, and so on.

• If any secure data must be stored in the ASAP database

In Design Studio, a Java class maps to a connection handler (see "Creating an Network Element Connection Handler"). This Java class must implement the IConnectionHandler interface that provides a common interface for the various protocols. It contains some standard methods such as connect () and disconnect (). The business logic depends on the NE interface protocol and connection/disconnection handshake sequence.

For non-telnet based cartridges the connection class should typically contain a connect() method and a disconnect() method. Helper methods are implemented to get at variables or objects that are stored by the connection class. For example the prompt is picked up from tbl_comm_param and when a provisioning method needs to get at it, it will invoke a method of the connection class to get the provisioning prompt. There may be helper methods for getting username, password, and so on. Sometimes a send() method may be implemented and called from the provisioning method after getting a reference to the connection object.

In case of a Telnet interface to the NE, Design Studio auto generates the skeleton code for the connection handler. The TelnetConnection class from the core framework is extended by the cartridge. The login() and disconnect() methods are implemented (the connect() method as supported in the core can be re-used as is). For telnet based cartridges there is also no need to implement send() and waitfor() methods because they are available in the core framework.

Other protocols, such as SOAP XML, TCP/IP, Web Services, Corba, and so on) depend much more on the server side implementation; therefore more code has to be written to handle connections to these NEs. Write a dummy client outside the ASAP environment to test connectivity. Many of the provisioning guides give sample code illustrating how to connect and provision a service. After that is tested in a standalone mode, it can be ported into an ASAP cartridge because Java is platform independent.

Other cartridges that use generic protocols need to implement their own send() and waitfor() methods. Some times (for example with Soap/XML protocols) establishing a connection on the URL to the remote server does not guarantee that the connection is usable. In this case an actual query message for a non-existing subscriber is made within the connection class itself to ensure that the connection is valid. If this query fails, then a ConnectionException() is thrown back so that the connection can be retried instead of all the provisioning orders failing.

Creating a Provisioning Prompt

Where possible (for example for certain TCP/IP based protocols such as telnet) checking that the correct prompt and level are present should be performed before each command is sent to the NE. This should be implemented as a separate callable method. In addition a method should be provided to be able to obtain the correct prompt and/or level in case an error has occurred.

Enabling Loopback Mode

When using the standard core ASAP send() and get() Java methods no additional loopback code should be required to be implemented in the cartridge because the standard loopback mechanism takes care of providing the exact responses requested.

Implementing Secure Login Functionality

In the current ASAP implementation login information for NEs is stored in tbl_comm_param in "clear" format. This makes that possible for sensitive data to be easily accessible by un-authorized persons (ASAP also automatically displays communication parameters in diagnostic files). It is very important to be able to store this type of data in a non-readable (encrypted) format.

There are two aspects to security: secure data storage and secure data encryption. The cartridge must be able to accommodate both:

1. Secure Data Storage - There are two types of data: ASAP secure data and custom secure data, which are identified by two class types (0- ASAP data, 1- custom data). ASAP secure data is stored in credential store factory (CSF) wallet located in ASAP_Home/install/cwallet.sso and custom secure data in tbl_classB_secu table in the control database. tbl_classB_secu allow entries in a name/value format with other fields for class type, security level, caching of data etc. The layout of this table is as follows:

   SQL> desc tbl_classB_secu;
   Name                                Null?          Type
   ----------------------------------------- -------- ----------------------------
   NAME                                NOT NULL       VARCHAR2(80)
   VALUE                               NOT NULL       VARCHAR2(255)
   CLASS                               NOT NULL       NUMBER(38)
   S_CACHE                             NOT NULL       NUMBER(38)
   C_DATE                              NOT NULL       DATE
   DESC1                                              VARCHAR2(255)
   

2. Secure Data Encryption – Custom secure data can be stored either in "clear" or in "encrypted" format. ASAP secure data is always encrypted.

To load the class B data, which contains NE access information, use the following steps:

1. Create an input file that contains the data to be stored in tbl_classB_secu. For example:

   #################################################
   #
   # This info is added to 'tbl_classB_secu' entries -
   # to be added using asap_security_tool
   #
   # Entries format: NAME:VALUE:CLASS:S_CACHE:DESCRIPTION
   #
   # Example: DMS_USER:user123:1:0:User name for DMS100 access
   #
   ###############################################
   #
   USER_NOKIA:user123:1:0:Login name for Nokia HLR
   PASS_NOKIA:pswd123:1:0:Password for Nokia HLR
   #
   

2. Load the content of this file into control database using asap_security_tool utility:

   asap_security_tool -u $CTRL_USER -p $CTRL_PASSWORD -r <secure data input file>
   

To retrieve the secure data from the tables within the cartridge Java code use the methods provided in the Security Java class (see Java Online Reference). The following sample code shows how the encrypted user ID and password are retrieved from the secure tables:

logger.logDebug("Getting access secure data");
Security sec = ASCAppl.getSecurity();
try {
     String secUsername = sec.getSecureData("USER_NOKIA", 1);
     logger.logDebug("Retrieved secure user name");
     String secPassword = sec .getSecureData("PASS_NOKIA", 1);
     logger.logDebug("Retrieved secure password");
} catch (SQLException e) {
     logger.logDebug("Exception caught while retrieving secure data: " + e);
}

After retrieved, data is automatically decrypted and ready to be sent to the NE. Make sure that this data is not written into the cartridge diagnostics. Display 10 asterisks instead (the number of asterisks should not match the actual length of the password).

Connection Management Issues

Never fail a work order due to connection failure in the case where connection management (for example corba connections) is supported within the cartridge code. Orders are only failed when the NE returns an error message indicating that data on the order is invalid.

Where possible avoid explicitly disabling connections from within the cartridge code. ASAP core handles the disabling of connections when the connection class exits with failure.

When communication parameters necessary to establish a connection are missing (as determined in the connection class for the cartridge) the cartridge must log a meaningful error message to the diagnostic files to indicate which parameter is missing and what the expected parameter is used for.

A new and improved Java SEND method has been implemented in ASAP core which will not force the calling cartridge code to handle exceptions (for example IOException or TelnetException), but will manage these exceptions internally. When connections go down atomic actions should be put back in the appropriate queue and rescheduled by ASAP automatically. The core should manage disabling and re-enabling the device accordingly.

In some cases (with certain TCP/IP-based cartridges and possibly others) certain delays are incurred when connecting and/or logging into NEs (reference the Ericsson MSS-C cartridge). In such cases implement a communication parameter (tbl_comm_param) that allows for a delay (thread.sleep()) interval to be configured in the field. It should be possible to set this to 0 so that no delay is incurred.

Creating a Java Telnet Connection Class

This section describes the steps to create a Java Telnet connection class. Use these steps as a guideline for constructing your own cartridge.

To create a Java Telnet connection class:

1. Create an NE as described in "Creating and Configuring Network Element and Network Element Connections" with the following exceptions:

   1. In the Protocol field, select the Telnet/SSH.

   2. When adding a connection, accept the autogenerated parameters.

   3. Select the All Communications Parameters tab.

   4. Modify the communication parameter values that your connection requires.

   5. Click Add Global to add any additional parameters that your connection requires.

   6. Edit the Label, Value and Description columns to specify the new parameter. For example:

      • In the Label field, enter PROMPT.

      • In the Value field, enter #.

      • In the Description field, enter This value defines the initial prompt symbol.

2. Create a Network Handler as described in "Creating an Network Element Connection Handler"with the following exceptions:

   1. From the Connection Type list, select the Telnet.

   2. In the Class field, click New.

      The Studio Activation Java Connection Handler wizard appears.

   3. In the Name field, enter a name for the connection handler.

   4. In the Connection Type list, select the Telnet.

   5. Click Finish.

      The connection_handler_name.java file opens in Design Studio (where connection_handler_name is the name of the connection handler).

3. In the connection_handler_name.java file, get the connection parameters for any parameters you added in addition to the autogenerated parameters. For example:

    try {
                String n_prompt = getCommParam("PROMPT");
                setPrompt(n_prompt);
   

   This sample uses the getCommParam method to retrieve data from the PROMPT parameter defined in addition to the autogenerated parameters.

   
   

   Note: The following method gets all autogenerated parameters: super.login();

   
   

4. Add code to wait for the login prompt. For example:

               -- Wait for the login prompt from the network element.
                if (login_prompt != null) 
                    waitfor(login_prompt);
                else 
                    waitfor("login:");
          
   

5. Add code to send the username. For example:

                this.sendln(userid);
   

6. Add code to wait for the password prompt. For example:

                -- Wait for the password prompt. --
                if (password_prompt != null)
                    waitfor(password_prompt);
                else 
                    waitfor("Password:");
   

7. Add code to send the password. For example:

                this.sendln(password);  
   

8. Add code to wait for the unix prompt. For example:

                 -- Wait for the normal network element prompt. --
                if (n_prompt != null) 
                    waitfor(n_prompt);
                else 
                    waitfor(">");     
   

   In this example, the prompt was defined using the PROMPT parameter with the = value. Had this value not been defined, it would have used the default > value.

9. Add code to specify an error diagnostic message. For example:

            } catch (Exception e) {
                Diagnostic.diag(Diagnostic.SANE, this, "Login failed: " + 
                e.getMessage());
                throw new TelnetException("Login failed: " + e.getMessage());
            }
   

10. Add code to specify a success diagnostic message. For example:

             Diagnostic.diag(Diagnostic.SANE, this, "Successfully logged in to the " + "network element.");
    }