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.

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.

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).

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 (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

• Hostpad device interfaces

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

• CORBA over IIOP (in conjunction with the JInterpreter)

• CAPI

• X.25, X.29, and TL1

• SFTP

Refer to the ASAP Developer's Guide 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.

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. Sometimes (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.

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.

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.

In the current ASAP implementation login information for NEs is stored in tbl_comm_param in "clear" format. This makes it 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:username:1:0:Login name for Nokia HLR
   PASS_NOKIA:password:1:0:Password for Nokia HLR
   #

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

   asap_security_tool -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 being retrieved, this 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).

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.

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.");
    }