javaapi for tellabs® 8000 network manager northbound interface

Tellabs 8000 Network Manager R17AJavaAPI for Tellabs 8000 Network Manager

Northbound Interface

70182_0130.09.09

Document Information

2009 Tellabs. All rights reserved.

This Tellabs manual is owned by Tellabs or its licensors and protected by U.S. and international copyright laws, conventions andtreaties. Your right to use this manual is subject to limitations and restrictions imposed by applicable licenses and copyright laws.Unauthorized reproduction, modification, distribution, display or other use of this manual may result in criminal and civil penalties.The following trademarks and service marks are owned by Tellabs Operations, Inc. or its affiliates in the United States and/or

other countries: TELLABS, TELLABS logo, TELLABS and T symbol, and T symbol.

Any other company or product names may be trademarks of their respective companies.

The specifications and information regarding the products in this manual are subject to change without notice. All statements,information, and recommendations in this manual are believed to be accurate but are presented without warranty of any kind,

express or implied. Users must take full responsibility for their application of any products.

Adobe Reader are registered trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Tellabs 8000 Network Manager R17A 70182_01JavaAPI for Tellabs 8000 Network Manager Northbound Interface 2009 Tellabs.

2

Document Information

Terms and Conventions

Term Explanation

API Application Programming Interface

DB Database

GPT General Problem Type

NBI Northbound Interface

NE Network Element

OSS Operations Support System. Includes e.g. EMS, NMS and SMS functionalities.

SPT Specific Problem Type

70182_01 Tellabs 8000 Network Manager R17A 2009 Tellabs. JavaAPI for Tellabs 8000 Network Manager Northbound Interface

3


4

Table of Contents

Table of Contents

About the Manual .............................................................................................................. 11

Objectives........................................................................................................................................................................11Audience..........................................................................................................................................................................11Related Documentation ...................................................................................................................................................11Document Conventions ...................................................................................................................................................11Documentation Feedback............................................................................................................................................... 12

1 Introduction to JavaAPI .............................................................................................. 13

2 Downward Compatibility of JavaAPI ......................................................................... 16

3 Clear Text Descriptions and Capacity Vectors of Attribute Values ........................ 17

4 Problem Type Descriptions and Probable Cause of Network Element Alarms.....18

5 How to Use JavaAPI.................................................................................................... 19

5.1 Java Runtime Environment ................................................................................................................................. 195.2 Create an Object of TolService Class ................................................................................................................. 195.3 Decide if You Want to See the Clear Text Descriptions of DB Values ............................................................... 19

5.3.1 Create an Object of NbifAttributeValueService Class ....................................................................... 195.4 Decide if You Want to See the Problem Type Descriptions and Probable Cause of NE Alarms........................ 20

5.4.1 Create an Object of NbifAttributeAlarmValueService Class .............................................................. 205.5 Decide the Datetime Format of JavaAPI............................................................................................................. 205.6 Open Communication (Socket) ........................................................................................................................... 215.7 Open Session ....................................................................................................................................................... 215.8 Running a Get Command .................................................................................................................................... 22

5.8.1 Creating Object TolResultSet .............................................................................................................. 225.8.2 Getting Inventory and Performance data............................................................................................. 225.8.3 Getting Alarm Data ............................................................................................................................. 235.8.4 Managing the Input Parameters of the Get Commands....................................................................... 23


5

Table of Contents

5.8.5 Retrieve the Result Data ...................................................................................................................... 265.8.6 Retrieve the Clear Text Descriptions for the Attribute Values ............................................................ 295.8.7 Retrieve the Problem Type Descriptions and Probable Cause of NE Alarms..................................... 295.8.8 Retrieve the Capacity Vector ............................................................................................................... 29

5.9 Provisioning with Macros.................................................................................................................................... 305.10 Subscribing to the Tellabs 8000 Manager NBI Inventory and NBI Alarm Notifications ................................... 31

5.10.1 Implement TolEventObserver Interface .............................................................................................. 325.10.2 Register as an Observer with addChangeListener Method ................................................................. 335.10.3 Check if Notifications Are Supported for the Entity ........................................................................... 335.10.4 Subscribe Commands for Subscribing to Inventory Entities............................................................... 335.10.5 Subscribe Commands for Subscribing to Alarm Entities and System Notifications........................... 345.10.6 Handle the Received Inventory Notifications...................................................................................... 345.10.7 Handle the Received Alarm Notifications ........................................................................................... 365.10.8 Handle the Received System Notifications ......................................................................................... 36

5.11 Acknowledging Alarms....................................................................................................................................... 375.12 Pinging the NBI Server to Verify that It Is Alive ................................................................................................ 375.13 Command Names and Codes............................................................................................................................... 375.14 Close Session....................................................................................................................................................... 385.15 Close Communication (Socket)........................................................................................................................... 38

6 TolService Class.......................................................................................................... 39

6.1 Establishing Connections to the Tellabs 8000 Manager NBI.............................................................................. 406.1.1 Method openCommunication for Opening Socket.............................................................................. 406.1.2 Method closeCommunication for Closing Socket............................................................................... 406.1.3 Method openSession............................................................................................................................ 406.1.4 Method closeSession ........................................................................................................................... 41

6.2 Requesting Inventory or Performance Data from the Tellabs 8000 Manager NBI ............................................. 416.2.1 Method getAllData .............................................................................................................................. 416.2.2 Method getFilteredAllData................................................................................................................. 426.2.3 Method getOneData............................................................................................................................. 446.2.4 Method getIntervalData (Deprecated) ................................................................................................. 456.2.5 Method pingNima................................................................................................................................ 466.2.6 Method pingNsa .................................................................................................................................. 46

6.3 Requesting Alarm Data from the Tellabs 8000 Manager NBI ............................................................................ 476.3.1 Method getActiveAlarmData .............................................................................................................. 476.3.2 Method getAllData for Getting Alarms............................................................................................... 47

6.4 Acknowledging Alarms....................................................................................................................................... 486.4.1 Method acknowledgeAlarm ................................................................................................................ 48

6.5 Executing the Tellabs 8000 Manager NBI Configuration Changes (Macros)..................................................... 496.6 Subscribing to the Tellabs 8000 Manager NBI Inventory and NBI Alarm Notifications ................................... 49

6.6.1 Method addChangeListener................................................................................................................. 506.6.2 Method removeChangeListener .......................................................................................................... 506.6.3 Method subscribeNotification.............................................................................................................. 506.6.4 Method unsubscribeNotification.......................................................................................................... 516.6.5 Method subscribeSystemNotification.................................................................................................. 516.6.6 Method unsubscribeSystemNotification.............................................................................................. 51

6.7 Settings of TolService.......................................................................................................................................... 526.7.1 Trace Level of JavaAPI ....................................................................................................................... 526.7.2 Datetime Pattern of JavaAPI ............................................................................................................... 53


6

Table of Contents

7 TolResultSet Class ...................................................................................................... 54

7.1 Scanning the Tellabs 8000 Manager NBI Response Records ............................................................................. 547.2 Extracting Attributes from a Record ................................................................................................................... 55

7.2.1 Method getValueAsString.................................................................................................................... 557.2.2 Method getValueByte .......................................................................................................................... 567.2.3 Method getValueShort ......................................................................................................................... 567.2.4 Method getValueInt ............................................................................................................................. 567.2.5 Method getValueDouble ...................................................................................................................... 567.2.6 Method getValueLong64 ..................................................................................................................... 577.2.7 Method getValueDate .......................................................................................................................... 577.2.8 Method getValueString ........................................................................................................................ 577.2.9 Method getValueBytes......................................................................................................................... 57

7.3 Datetime Pattern of TolResultSet ........................................................................................................................ 58

8 NbifAttributeInfo and NbifAttributeService Classes ................................................ 59

8.1 Entity IDs and Names.......................................................................................................................................... 598.2 Attribute IDs and Names ..................................................................................................................................... 598.3 Methods for Handling Entities ............................................................................................................................ 60

8.3.1 Methods that Return All Entities ......................................................................................................... 608.3.2 Methods that Return Inventory and Performance Entities .................................................................. 608.3.3 Methods that Return Alarm Entities.................................................................................................... 618.3.4 Method getEntityName........................................................................................................................ 628.3.5 Method getEntityIdForEntityName..................................................................................................... 628.3.6 Method getEntityObject ...................................................................................................................... 628.3.7 Method isAlarmEntity ......................................................................................................................... 628.3.8 Method isEclEntity .............................................................................................................................. 638.3.9 Method getEntityNotificationSupport ................................................................................................. 63

8.4 Methods for Handling Attributes......................................................................................................................... 638.4.1 Methods that Return Attributes ........................................................................................................... 638.4.2 Method getAttributeNamesInArrayList .............................................................................................. 648.4.3 Method getNumberOfKeyAttributes................................................................................................... 648.4.4 Methods that Return Key Attributes.................................................................................................... 648.4.5 Method getAttributeObject.................................................................................................................. 658.4.6 Method getAttributeIdForAttributeName............................................................................................ 668.4.7 Method getAttributeEntityId ............................................................................................................... 668.4.8 Method getAttributeName................................................................................................................... 668.4.9 Method getAttributeDataTypeCode .................................................................................................... 668.4.10 Method getAttributeDataTypeDesc ..................................................................................................... 678.4.11 Method getAttributeDataLength.......................................................................................................... 678.4.12 Method getAttributeIsKey................................................................................................................... 67

8.5 Methods for Parsing Strings ................................................................................................................................ 678.5.1 Method parseEntities ........................................................................................................................... 688.5.2 Method parseOneEntity....................................................................................................................... 688.5.3 Method parseAttributes ....................................................................................................................... 688.5.4 Method parseOneAttribute .................................................................................................................. 698.5.5 Method parseFilters ............................................................................................................................. 698.5.6 Method parseAttributeValueList.......................................................................................................... 708.5.7 Method parseOneValue........................................................................................................................ 708.5.8 Method parseIntegerParameterList...................................................................................................... 718.5.9 Method parseOneInteger ..................................................................................................................... 71


7

Table of Contents

8.5.10 Method parseOneLong ........................................................................................................................ 718.6 Methods for Getting Capacity Vectors ................................................................................................................ 72

8.6.1 Method convertBytesToCapacityVectorString .................................................................................... 728.6.2 Method convertBytesToCapacityVectorArrayList .............................................................................. 73

8.7 Attribute Data Type Definition ............................................................................................................................ 758.8 Methods for Getting Example Value Format for Attributes ................................................................................ 75

8.8.1 Method getExampleValueString.......................................................................................................... 758.8.2 Method getExampleTolDateTimeString.............................................................................................. 76

9 NbifAttributeValueService Class................................................................................ 77

9.1 Methods for Handling the Attribute Value Descriptions ..................................................................................... 779.1.1 Method NbifAttributeValueService..................................................................................................... 779.1.2 Method getService_data_is_ok............................................................................................................ 789.1.3 Method getDescriptionOfAttributeValue ............................................................................................ 789.1.4 Method getValueOfAttributeDescription ............................................................................................ 789.1.5 Method getAttributeValueObjectsOfAttribute .................................................................................... 79

10 NbifAttributeAlarmValueService Class ..................................................................... 80

10.1 NE Alarm Types .................................................................................................................................................. 8010.2 Methods for Handling the Alarm Values............................................................................................................. 80

10.2.1 Method NbifAttributeAlarmValueService........................................................................................... 8010.2.2 Method getService_data_is_ok............................................................................................................ 8110.2.3 Method getGptText.............................................................................................................................. 8110.2.4 Method getSptText .............................................................................................................................. 8110.2.5 Method getAlarmtypetext.................................................................................................................... 82

11 NbifAttributeSptValue Class....................................................................................... 83

11.1 Methods for Handling the Specific Problem Type Descriptions of an NE Alarm .............................................. 8311.1.1 Method getSpttext................................................................................................................................ 8311.1.2 Method getProbablecause.................................................................................................................... 8311.1.3 Method getSourcehw........................................................................................................................... 8311.1.4 Method getSptCode ............................................................................................................................. 8411.1.5 Method getAlarmtype.......................................................................................................................... 8411.1.6 Method getHwtype .............................................................................................................................. 84

12 TolType and TolTypeService Classes ........................................................................ 85

12.1 Values in TolType Class....................................................................................................................................... 8512.1.1 Codes of Commands for Accessing Data from NBI Server ................................................................ 8512.1.2 Codes for Received Notifications ........................................................................................................ 8512.1.3 Status Stored in the Header of the Reply Message.............................................................................. 8512.1.4 Error Codes Set in Case of Problems in Reading Reply Data............................................................. 8512.1.5 Codes and Names of Supported Capacity Vector Types ..................................................................... 8612.1.6 Codes of Supported Trunk Allocation Types ...................................................................................... 86


8

Table of Contents

12.1.7 Trace Level .......................................................................................................................................... 8712.1.8 Filter Types Available for GetFilteredAllData Command................................................................... 87

12.2 TolTypeService Methods for Handling Commands ............................................................................................ 8712.2.1 Method getCommandName................................................................................................................. 8712.2.2 Method getCommandCode.................................................................................................................. 8812.2.3 Methods that Return Commands for Managing Inventory and Performance Data............................. 8812.2.4 Methods that Return Commands for Managing Alarms ..................................................................... 88

12.3 TolTypeService Methods for Capacity Vector Types .......................................................................................... 8912.3.1 Method getCapacityVectorAlloctypeForTrunkAllocType .................................................................. 8912.3.2 Method getCapacityVectorTypeCode................................................................................................. 8912.3.3 Method getCapacityVectorTypeName................................................................................................. 9012.3.4 Method getCapacityVectorTypeCodes ................................................................................................ 9012.3.5 Method getCapacityVectorTypeNames ............................................................................................... 90

12.4 TolTypeService Methods for Handling Trace Log Levels .................................................................................. 9112.4.1 Methods getTraceLevelCodes and getTraceLevelNames ................................................................... 9112.4.2 Method getTraceLevelName ............................................................................................................... 9112.4.3 Method getTraceLevelCode ................................................................................................................ 91

12.5 TolTypeService Methods for Handling Filter Types of Command GetFilteredAllData ..................................... 92

13 OpenResultSet Class.................................................................................................. 93

13.1 Extracting the Tellabs 8000 Manager NBI Sessions Handle ID ....................................................................... 93

14 TolEventObserver Class ............................................................................................. 94

14.1 Processing the Tellabs 8000 Manager NBI Inventory Notifications ................................................................... 9414.1.1 Create Notifications ............................................................................................................................. 9414.1.2 Attribute Value Change Notifications.................................................................................................. 9514.1.3 Delete Notifications ............................................................................................................................. 95

14.2 Processing the Tellabs 8000 Manager NBI Alarm Notifications ........................................................................ 9614.2.1 TolAlarmEvent Methods ..................................................................................................................... 96

14.3 Processing the Tellabs 8000 Manager NBI System Notifications ....................................................................... 9614.3.1 TolSystemEvent Methods.................................................................................................................... 97

15 OSS Client Development and JavaAPI Use .............................................................. 98

15.1 Using JavaAPI to Simultaneously Integrate Inventory Data and Alarm Data ................................................... 9815.2 Entity IDs and Attribute IDs ............................................................................................................................... 9815.3 Required Setting at NIMA.INI ........................................................................................................................... 9915.4 Providing Key Attribute Values in getOneData and getIntervalData Requests ................................................. 9915.5 Other JavaAPI Specific Data Types..................................................................................................................... 99

15.5.1 TolDateTime Class .............................................................................................................................. 9915.6 JavaAPI Exceptions........................................................................................................................................... 102

15.6.1 TolCommunicationException............................................................................................................ 10215.6.2 TolAttributeException ....................................................................................................................... 104

15.7 Using the openCommunication() and openSession() Methods ........................................................................ 104


9

Table of Contents

16 Using NBI Test Client ................................................................................................ 105

16.1 Installing Java Runtime Environment ............................................................................................................... 10516.2 Files of the NBI Test Client ............................................................................................................................... 105

16.2.1 jar-files NBITestClient.jar and tol.jar ................................................................................................ 10516.2.2 Clear Text Description File................................................................................................................ 10516.2.3 Ini File for the Test Client.................................................................................................................. 106

16.3 Launching the Test Client.................................................................................................................................. 10716.4 NBI Inventory and Performance Services (Target NIMA)................................................................................ 108

16.4.1 Commands for Subscribing to Notifications ......................................................................................11016.4.2 Command GetAll...............................................................................................................................11116.4.3 Command GetFilteredAll ...................................................................................................................11216.4.4 Command GetOne ..............................................................................................................................114

16.5 NBI Fault and Provisioning Services (Target NSA)...........................................................................................11516.5.1 Commands for Subscribing to Notifications ......................................................................................11716.5.2 Command GetAll................................................................................................................................11716.5.3 Command Execute Macro ..................................................................................................................118

Appendix: JavaAPI Examples ....................................................................................... 119


10

About the Manual

About the Manual

Objectives

This manual gives information on JavaAPI, a Java based library that provides a high-levelprogramming interface for developers of third party OSS Client applications.

Audience

This information is aimed at the developers of third party OSS Client applications. With the help ofJavaAPI library, the developers do not need to know details about the underlying protocols used inthe Tellabs 8000 Network Manager Northbound Interface (Tellabs 8000 network manager NBI).

The developers of third party OSS Client applications must use the Java programming languageto be able to benefit from the JavaAPI library and must implement an adapter module at the OSSSystem that uses JavaAPI classes to integrate with the Tellabs 8000 network manager NBI.

Related Documentation

Document No Document Name

Tellabs 8000 Network Manager R17AInstallation and Configuration Guide forNorthbound Interface (70173_XX)

Provides instructions on installing and configuringthe Northbound Interface service of ManagementServer of theTellabs 8000 network manager.

Information on general Java classes, for example information on the Java class SimpleDateFormat,is available at SUNs web pages:

Document Conventions

This is a note symbol. It emphasizes or supplements information in the document.

This is a caution symbol. It indicates that damage to equipment is possible if the instructionsare not followed.

This is a warning symbol. It indicates that bodily injury is possible if the instructions are notfollowed.


11

About the Manual

Documentation Feedback

Please contact us to suggest improvements or to report errors in our documentation:

Email: [email protected]

Fax: +358.9.4131.2430


12

1 Introduction to JavaAPI


The figure below shows an overview of how JavaAPI and the Tellabs 8000 manager NBI are usedwhen integrated to a third party OSS system.

Fig. 1 JavaAPI and Tellabs 8000 Network Manager NBI Integrated to a Third Party OSS System

JavaAPI is composed of more than 20 Java classes and one interface, but only a selection of theclasses and methods are public for OSS Client development. For processing notifications messagessent by the Tellabs 8000 manager NBI, the OSS Client needs to implement one JavaAPI Interface.

The main public classes are:


13


TolService containing the Tellabs 8000 manager NBI communication methods

openCommunication

openSession

getAllData

getOneData

getFilteredData

getActiveAlarmData

acknowledgeAlarm

getIntervalData

subscribeNotification

and others.

OpenResultSet containing a method to obtain the HandleId that identifies a session to the Tellabs8000 manager NBI.

TolResultSet containing methods to read and parse data sent by Tellabs NBI in response togetAllData, getOneData and getIntervalData calls. Notification data is also han-dled by TolResultSet.

NbifAttributeService containing methods to handle data entities and attributes.

NbifAttributeValueService containing methods to get descriptions for the attribute values.

To process the notifications sent by the Tellabs 8000 manager NBI, the OSS Client application mustimplement the TolEventObserver interface.

JavaAPI is provided as a set of Java class files that should be installed at the computer/serverrunning the OSS Client application. JavaAPI requires J2SE release 1.5 or newer.

The figure below shows an example of the OSS Client application being implemented in theTellabsClient.java file and installed under directory \OSSApp. JavaAPI files should then beinstalled in the \OSSApp\ directory.


14


Fig. 2 An Example of JavaAPI Files Implemented

The JavaAPI can be used for two purposes:

1. NBI Inventory and Performance Services

2. NBI Fault and Provisioning Services

These services are provided in different ports of the NBI Server. The JavaAPI programmer mustcreate the connection to the wanted port to have access to the services.

For GET operations, there is a list of supported entities. Each entity supports a list of attributes.An entity can be a physical object (for example a node or a unit), a logical object (for example acircuit, an mplsvpn), a performance object (for example G821 performance data), an alarm object(network element alarm or service alarm), etc.


15

2 Downward Compatibility of JavaAPI

2 Downward Compatibility of JavaAPI

JavaAPI is downward compatible with previous releases of Tellabs 8000 network manager. OSSapplication can implement the most recent methods and performance enhancements of the latestJavaAPI even when it is integrating with an older release of Tellabs 8000 manager. OSS applicationcan start using the new commands and getting data for the new entities and attributes as soon asTellabs 8000 network manager is upgraded to a release which supports them.

JavaAPI is not compatible upward. When upgrading to a new release of Tellabs 8000 manager,the newest JavaAPI must be taken into use.


16

3 Clear Text Descriptions and Capacity Vectors of Attribute Values

3 Clear Text Descriptions and Capacity Vectorsof Attribute Values

JavaAPI provides Clear Text description texts for the attribute values (since R15A) and CapacityVectors (since R16).

For example, you can easily view the nodes hardware type. After you have received the data fromthe NBI Server to your client, you can pass the values over to Clear Text Description methods ofJavaAPI to get the Clear Text description, e.g. string 8630 in case of a Tellabs 8630 access switchnode (whose code value is 10017). For more information on using the Clear Text descriptions,see the information below.

The trunk capacity usage can also be clearly seen. After receiving the data from the NBI Server toyour client, you can pass the capacity data over to Capacity Vector methods of JavaAPI to get theCapacity usage in a clear format, e.g. the used capacity of a STM-1 trunk can been seen as a cleartext TU:100,211,212,310,370, which shows which TU-12s, TU-2s and TU-3s are used.


17

4 Problem Type Descriptions and Probable Cause of Network Element Alarms

4 Problem Type Descriptions and ProbableCause of Network Element Alarms

JavaAPI provides descriptions for alarms which is a useful feature for NBI alarm integration. Itprovides the following:

description of the Generic Problem Type (GPT) code

description of the Specific Problem Type (SPT) code

probable cause for alarms

the type of the alarm (NODE Alarm, NTU Alarm or NMS Alarm)

the hardware type of the faulty unit or the faulty NTU

After you have received the alarms from the NBI Server to your client, you can pass the alarm datato Alarm Description methods of JavaAPI to get the SPT and GPT problem type descriptions, theprobable cause of the alarm, the type of the alarm and the hardware type of the faulty unit or NTU.

E.g. for an alarm from Interface unit for Tellabs 8660 edge switch, the alarm might have GPTcode 10004 and SPT code 1769474. The Alarm Description methods of JavaAPI provide thefollowing descriptions:

GPT: "Alarm received from the Tellabs 8600 equipment"

SPT: "Tx circuit down"

probable cause: "Circuit is down in transmit direction. The reason may be that the LDP signallingis not successfully executed."

type of the alarm: "NODE Alarm"

hardware type of the unit: "8605 Interface Unit"

For more information on using the Alarm Description methods of JavaAPI, see the informationbelow.


18

5 How to Use JavaAPI


5.1 Java Runtime Environment

Use JavaAPI with Java Runtime Environment 5.0 or newer.

5.2 Create an Object of TolService Class

The class TolService provides methods for handling the commands of JavaAPI. The defaultconstructor is

TolService Srv = new TolService();An alternative constructor of TolService takes the trace level as a parameter.

TolService prints only those messages to JavaAPI trace which have a higher importance than theselected (or default) trace level. For more information on the constructors and the trace levelsettings, see 6 TolService Class.

5.3 Decide if You Want to See the Clear Text Descriptions of DBValues

If you want to use the Clear Text descriptions, create an object of class NbifAttributeValueService.With the methods of NbifAttributeValueService you can either get all Clear Text descriptionsor convert an attribute value to its description.

You can use NbifAttributeValueService to give the Clear Text descriptions for the result data of Getcommands or when you receive notifications.

There should be only one instance of NbifAttributeValueService since creating such an objectis a reasonably heavy task.

5.3.1 Create an Object of NbifAttributeValueService Class

Class NbifAttributeValueService provides methods for getting Clear Text descriptions for theattribute values.

When an instance of class NbifAttributeValueService is created, it loads the Clear Text descriptionsfrom files and maps them to those attributes which support the descriptions.


19


You can check that the NbifAttributeValueService was loaded properly by getting the status withmethod getService_data_is_ok(). This status contains the boolean value True if the Clear Textdescriptions exist.

For more information on NbifAttributeValueService, see 9 NbifAttributeValueService Class.

5.4 Decide if You Want to See the Problem Type Descriptions andProbable Cause of NE Alarms

If you are integrating to NBI Alarms and want to get the Problem type descriptions and probablecause of NE alarms, create an object of class NbifAttributeAlarmValueService. With the methods ofNbifAttributeAlarmValueService you can get the GPT and SPT descriptions, the probable cause ofthe alarm, the type of the alarm and the hardware type of the faulty unit or NTU.

You can use NbifAttributeAlarmValueService to get the descriptions for the result data when gettingall existing active alarms or when you receive alarm notifications. There should be only one instanceof NbifAttributeAlarmValueService since creating such an object is a reasonably heavy task.

Starting up the JavaAPI takes longer, when you use the feature to get the Problem typedescriptions and probable cause of alarms since the JavaAPI loads the problem typedescription and probable cause texts at startup.

5.4.1 Create an Object of NbifAttributeAlarmValueService Class

Class NbifAttributeAlarmValueService provides methods for getting the GPT and SPT descriptions,the probable cause of the alarm, the type of the alarm and the hardware type of the faulty unit orNTU.

When an instance of class NbifAttributeAlarmValueService is created, it loads the problem typedescriptions and probable cause texts from files.

You can check that the NbifAttributeAlarmValueService was loaded properly by getting the statuswith method getService_data_is_ok(). This status contains the boolean value True if the descriptionsexist.

For more information on NbifAttributeAlarmValueService, see 10 NbifAttributeAlarmValueServiceClass.

5.5 Decide the Datetime Format of JavaAPI

JavaAPI prints out datetimes and requires the datetimes to be inserted in a certain pattern. Thepattern is common (static) in JavaAPI.

The default datetime pattern is " dd.MM.yyyy HH:mm:ss:SSS". For example: 10.03.200519:30:25:55.

If you want to change the default datetime pattern, you can do it either


20


1. with set-methods of TolService (see 6.7.2 Datetime Pattern of JavaAPI)or

2. with set-methods of a TolDateTime object (see 15.5.1 TolDateTime Class).

Changing the pattern affects all the places where datetimes are used.

1. The datetime pattern is used when printing out results containing datetime attributes with meth-ods of TolResultSet class.

2. The datetime pattern is needed in class TolService when giving datetime values as input tocommands GetFilteredAllData (or GetIntervalData).

NBI Server applications return the TolDateTime values by default in the local normal time.There is an option to return the TolDateTime values in UTC time by adding the parameterUSE_UTC_TIME=YES to the nsa.ini and nima.ini files in the NBI Server.

5.6 Open Communication (Socket)

Define the hostname or the IP address of the Northbound Interface. Define the port where theNorthbound Interface provides the requested services:

Requested Services Service Name Service Port (ServerDefault)

NBI Inventory and Performanceservices

NIMA 2462

NBI Fault and Provisioningservices

NSA 2461

Open the socket using the method openCommunication of TolService class

public void openCommunication(String hostAddress, intportNumber) throws IOException

When using JavaAPI to communicate with NBI Fault and Provisioning services, the followingconfiguration changes have to be made:in %DXXDIR%\dat\nsa.ini, set the parameter BYTE_CONVERSION=OFF.

5.7 Open Session

Define an object of the class OpenResultSet:

OpenResultSet resultSet = new OpenResultSet();Define the username and the password.

Open the session using the method openSession of TolService class:


21


public void openSession(String userName, String passWord,OpenResultSet openResultSet)throws IOException, TolCommunicationException

Get the handleId using the method getHandleId of OpenResultSet class:

public long getHandleId()Store the handleId. You need it every time you send commands to the Northbound Interface:

long handleId = openResultSet.getHandleId();

5.8 Running a Get Command

The available commands depend on the port you have opened. However, there are common featuresin the different Get commands:

All Get commands return the data in TolResultSet. You can use the same methods of the classTolResultSet to evaluate the results.

All Get commands require the entityId as an input parameter.

Most Get commands require an ArrayList of selected attributes as an input parameter.

Some Get commands require specific input parameters.

5.8.1 Creating Object TolResultSet

First, define an instance of class TolResultSet to let the Get command fill it with data.

TolResultSet resultSet = new TolResultSet();

5.8.2 Getting Inventory and Performance data

The following methods are available for getting Inventory and Performance data (NIMA in port2462):

Method or TolService Description Parameters

getAllData Method to retrieve the selectedattributes for all existing rows ofthe selected entity.

long handleIdint entityIdArrayList selectedAttributesTolResultSet resultSet (Output)

getFilteredAllData Method to retrieve the selectedattributes for those rows of theselected entity which match thegiven filters.

long handleIdint entityIdArrayList selectedAttributesArrayList filterAttributesArrayList filterAttrValuesArrayList filterTypesTolResultSet resultSet (Output)


22


Method or TolService Description ParametersgetOneData Method to retrieve the selected

attributes for a single row of theselected entity, which matchesthe given key attribute values.

long handleIdint entityIdArrayList selectedAttributesArrayList keyAttributesArrayList keyAttrValuesTolResultSet resultSet (Output)

getIntervalData Note: A deprecated methodwhich works only for someperformance entities.Method to retrieve the selectedattributes for those rows of theselected entity which are inthe given time interval and, forsome of the entities, match thegiven Circuit ID/ NTU ID.It is recommendedto use the methodgetFilteredAllDatainstead!

Deprecated methodParameters are as in case ofgetOneData. However,the order of the keyIds doesmatter. Since this command isdeprecated, the details are notdescribed here.

5.8.3 Getting Alarm Data

The following method are available for getting alarm data (NSA in port 2461):

Command Description Parameters

getActiveAlarmData Returns all attributes for allexisting rows of the selected(alarm) entity.The method getActiveAlarm-Data does not require giving anyattributes as an input parameterbut it always returns all theattributes.

long handleIdint entityIdTolResultSet resultSet (Output)

getAllData Returns all attributes for allexisting rows of the selected(alarm) entity.The method getAllData requiresgiving all existing attributes ofthe select (alarm) entity in theprespecified order.

long handleIdint entityIdArrayList selectedAttributesTolResultSet resultSet (Output)

5.8.4 Managing the Input Parameters of the Get Commands

Commands require giving the supported entities, attributes, filter types etc. as input parameters.Commands allow giving ArrayLists containing either IDs/codes or names/symbols.

OSS client applications dealing with predefined supported entities and attributes can directly usethem from the NbifAttributeInfo class and in the TolType class.


23


A GUI application is more likely to play around with lists of supported entities, attribute, valuesetc. There are several methods available which format the parameters to the format expected by theGet command.

1. You can get a list of all possible supported entities.

2. You can get a list of all possible attributes of an entity.

3. You can get a list of possible values for an attribute.

4. You can convert the names into IDs and vice versa.

See also Appendix: JavaAPI Examples

The handleId Is Needed for Any Get Command

Input parameter handleId is the handle ID which you received from the OpenSession command.

The entityId is Needed for Any Get Command

The entityIds can be taken directly from the NbifAttributeInfo class (see 8.1 Entity IDs and Names).There are also methods in NbifAttributeService, which return (see 8.3 Methods for HandlingEntities):

1. All supported entities (either Inventory and Performance or Alarm entities).

2. Entity name for an entity ID and vice versa.

3. Information if the entity is the Tellabs 8000 manager Provisioning related entity (ECL entity).And methods which can be used for parsing the entity from a string (see 8.5 Methods forParsing Strings).

4. Methods for parsing entity IDs or NAMEs from a string.

Selected Attributes for Get Commands

The input parameter selectedAttributes is an ArrayList of attributes, which you want to get.ArrayList is allowed to contain either attribute IDs (as Integers) or attribute names (as Strings). Theattribute IDs and names can be taken directly from the NbifAttributeInfo class (see 8.1 EntityIDs and Names).

For Inventory and Performance entities you can select, that is, add to the ArrayList, as manyattributes as you like in any order. However, to make the getting of the data faster, it a recommendedto select only those attributes which are of importance to your OSS Client application.

For Alarm entities ALL attributes must be selected in the predefined order. So, instead of selectingthe attributes, it is recommended either to

use the command getActiveAlarmData(), where you do not have to give the selected at-tributesor

use the method ArrayList getAttrIdArrayList(int entityId) of NbifAttribute-Service to create the ArrayList. Give that ArrayList directly as an input parameter selectedAt-tributes to GetAllData()command.


24


For Get commands of Alarm entities, all attributes must be included in the selected attributesand they must be included in the order of the attribute IDs.

There are also methods in NbifAttributeService which return (see 8.4 Methods for HandlingAttributes):

1. All attributes of the given entity.

2. A number of key attributes and all key attributes of the given entity.

3. Properties of the given attribute (entity, data type, data length, if it is key).

4. Attribute name for an attribute ID and vice versa.And methods which can be used for parsing the attributes from a string (see 8.5 Methodsfor Parsing Strings):

5. Methods for parsing attribute IDs or NAMEs from a string.

Key Attributes and Key Values for GetOneData Command

For the GetOneData command you must give the key attributes of the entity in one ArrayListand the key values in another ArrayList. ArrayList of key attributes is allowed to contain eitherattribute IDs (as Integers) or attribute names (as Strings). ArrayList of key values must contain avalue for each key attribute in its own data type.

To be able to use the command GetOneData(), you must know which of the attributes are keyattributes and you must know their data types to give the key value in its own data type format.

Note that there are methods available in NbifAttributeService to find out which attributes are keyattributes and the methods to get the key attributes.

The key attributes can be added to the ArrayList in any order. However, you must insert the keyattribute values to their ArrayList in the same order as you inserted the key attributes.

The key attributes can be managed as the selected attributes (described above).

Additionally, there are methods in NbifAttributeService for parsing the values from a string (see8.5 Methods for Parsing Strings):

Methods for parsing attribute value(s) from a string to the data type(s) of the attribute.

Filter Attributes, Filter Types and Filter Values for GetFilteredAllData Command

For the GetFilteredAllData command you can give a filter which consists of one or morelogical conditions.

The logical condition is a condition on the values of one attribute. For example, you can have afilter for the NODE entity where the logical condition is that the node hardware type attributehas value 10017:

NODE_HWTYPE = 10017

If you give more logical conditions in a filter, the logical conditions are joint with AND.


25


(Attribute1 operator1 value1) AND (Attribute2 operator2 value2) AND ... AND (AttributeNoperatorN valueN)

AttributeX means attribute (ID or name)

operatorX means filter type ( =, < , > , = , LIKE)

where

valueX means value used in filtering

The maximum of ten logical conditions (AttributeX operatorX valueX) can be applied in a filter.

For example, you can have a filter for the NODE entity where the logical condition is that the nodehardware type attribute has value 10017 and the node ID is in the range of 100 and 199:

( NODE_NHWTYPE = 10017 ) AND ( NODE_NID >= 100 ) AND ( NODE_NID


Fig. 3 TolResultSet

By using the TolResultSet methods the OSS Client can scan all records contained in the TolResultSetobject. By using attribute IDs the OSS Client can extract the value of a specific attribute. To parsethe records and attributes in the TolResultSet, the OSS Client should use the getNext() andgetValueXX (attrId) methods. These methods are described in more detail in the sectionsbelow.

Fig. 4 getNext

The values can be replaced or extended by the Clear Text explanations if wanted. ClassNbifAttributeValueService provides methods for retrieving the Clear Texts.

In case of NBI Alarm integration, the class NbifAttributeAlarmValueService can be used forgetting the GPT and SPT descriptions, the probable cause and the type of an NE alarm and alsothe hardware type of the faulty unit or NTU.


27


Scan the Tellabs 8000 Manager NBI Response Records

TolResultSet class provides methods for Scanning the Tellabs 8000 manager NBI response records.See also 7.1 Scanning the Tellabs 8000 Manager NBI Response Records. Use the methodgetNext() to scan the records one by one (returns True as long as there are records). Afterusing the method getNext() you must use the methods for extracting the attributes from therecord as described below.

Get Attributes in the TolResultSet Object

Use the method ArrayList getAttrIdList() to get an ArrayList containing the IDs ofthe attributes which are contained in each record of the TolResultSet. Every record of the sameTolResultSet object contains the same attributes. You need to know the attributes to be able toretrieve the values using the proper data type.

Extract Attributes from a Record

TolResultSet class provides methods for extracting attributes from a record. See 7.2 ExtractingAttributes from a Record.

To extract attribute values, the OSS Client can use two approaches:

1. Extract all attributes as string values with the method string getValueAsString (intattrId).

2. Extract each attribute in its native data type (byte, short, int, double, long64, String, byte[], Tol-DateTime) with the method getValueXX(int attrId). For example, extract an attributeof data type short with method short getValueShort(int attrId).

Developers of the OSS Client can choose which one is more appropriate.

In both cases, the OSS Client must know the entity in a TolResultSet, and the IDs of the attributesto be extracted.

In case of extracting attributes in their native data type, OSS Client must also know the datatype of the attribute in order to call the correct method, otherwise the getValueXX()method will throw a TolAttributeException. To find out the data type of an attribute,use the method int getAttributeDataTypeCode (int attrId) of theclass NbifAttributeService, which returns the data type code of the given attribute, e.g.NbifAttributeService.NIMA_DT_SHORT.

For more methods giving information on the attribute, see 8.4 Methods for Handling Attributes.

For more information on possible data types, see 8.7 Attribute Data Type Definition.

Get General Information on the TolResultSet Object

There are also methods for

1. Getting the number of records in the TolResultSet object.

2. Getting the size of the whole TolResultSet object.

3. Getting the size of one record.


28


5.8.6 Retrieve the Clear Text Descriptions for the Attribute Values

To retrieve the Clear Text descriptions, create on object of class NbifAttributeValueSer-vice. With methods of the NbifAttributeValueService class you can:

Check that the service has been loaded properly.

Get the description for a given value of a given attribute.

Get the attribute value for a given description of a given attribute.

Get all possible values for a given attribute.

See also 9 NbifAttributeValueService Class

5.8.7 Retrieve the Problem Type Descriptions and Probable Cause of NE Alarms

To retrieve the GPT and SPT descriptions, the probable cause of the alarm, thetype of the alarm and the hardware type of the faulty unit or NTU, create onobject of class NbifAttributeAlarmValueService. With methods of theNbifAttributeAlarmValueService class you can do the following:

Check that the service has been loaded properly.

Get the description of a given GPT code.

Get the description of a given SPT code.

Get the probable cause for the alarm.

Get the type of the alarm (NODE Alarm, NTU Alarm or NMS Alarm).

Get the hardware type of the faulty unit or the faulty NTU.

See also 10 NbifAttributeAlarmValueService Class.

5.8.8 Retrieve the Capacity Vector

For a capacity vector attribute, you can see the capacity structure with methods provided in classNbifAttributeService.

There are methods for converting a byte array into a string or an ArrayList containing the TS, TU,AU-4 or bit capacity vector:

Method convertBytesToCapacityVectorString returns the capacity structure in a string

Method convertBytesToCapacityVectorArrayList returns the capacity structure as integer valuesin an ArrayList.

CapacityVectorType

Contents Example of CapacityStructure in a String

Example ofCapacityStructure asIntegers

TS: non-zero TS numbers TS:0,1,2 0,1,2


29


CapacityVectorType

Contents Example of CapacityStructure in a String

Example ofCapacityStructure asIntegers

TU: non-zero KLM values: TU-12s in format K*100+L*10+M

TU-2s in format K*100+L*10

TU-3s in format K*100

TU:100,211,212,310,370 100,211,212,310,370

AU-4 non-zero AU4s AU4:1,2 1,2

Bit capacity Non-zero bits. First all eight bits of TS0(TS0\b0, TS0\b1, TS0\b2, ..., TS0\b7),then all bits of TS1 (TS1\b0, TS2\b1,...TS2\b7), then bits of all followingtime slots. Zero-bits in the end of listare NOT included in the ArrayList.

TS0:B6\B7\,TS1:B1\B2 0,0,0,0,0,0,1,1,1,1

See also 8.6 Methods for Getting Capacity Vectors.

5.9 Provisioning with Macros

The following method is available for executing macros (NSA in port 2461):

Command Description ParametersexecuteMacro The macro file, whose name is

given as a parameter, is executedon the Northbound Interface.In case of success the methodreturns. In case of failure, themethod throws exception, whichcontains explanation on thefailure.

long handleIdString macroFileNameString macroArguments(optional) int timeout

Configuration changes, such as provisioning operations, are possible through the executeMacrofeature of the Tellabs 8000 manager NBI.

The executeMacro method allows the OSS to request the NBI Server to execute a Macro programwith given arguments. When calling the executeMacro method, the OSS must specify the nameof the Tellabs 8000 manager Macro program and the input parameters for the Macro program. TheMacro programs must be installed in the NBI Server, and will be executed by the Tellabs 8000manager NBI every time the OSS calls the executeMacro method with appropriate parameters.

The method executeMacro accepts the name of the macro program with or without the .macsuffix. For example, the macro program OSSMacro.mac can be given to method executeMacro asOSSMacro or OSSMacro.mac


30


Most of the Tellabs 8000 manager Macro programs expect input parameters. Input parametersare defined in the Macro program and are specific to each Macro. Input parameters can varyin type or quantity. Every input parameter in a Macro has a name. The OSS Client should usethe input parameter names when building the macroArguments String. The generic formatfor this string is:==...=For Macro parameters of STRING type, the must be enclosed in quotation marks ().For example, let us assume a Macro file named OSSMacro.mac that expects one INTparameter named NodeID and one STRING parameter named NodeName. When the OSSClient calls the executeMacro method for a node with ID=10 named New Node under asession with handleId = 100, the method should be called as follows:executeMacro(100, OSSMacro, NodeID=10 NodeName=\New Node\)

5.10 Subscribing to the Tellabs 8000 Manager NBI Inventory and NBIAlarm Notifications

Subscribe to notifications before using the getAll command to avoid loosing anynotifications.

The mechanism implemented in JavaAPI to send event notifications to the OSS Client is based onthe Observer Java Design Pattern (compare for example with the MouseListener interface inJava). The OSS Client takes the role of Observer, and JavaAPI takes the role of Subject.

In this scenario, the OSS Client first has to register as an Observer to JavaAPI. This is doneby calling the addChangeListener method. After that, the OSS Client can inform JavaAPIfrom which object entities it is interested in receiving the notifications. This is done by calling thesubscribeNotification method. As a summary, JavaAPI will start giving notifications tothe client, when the client:

1. Implements the interface TolEventObserver and overrides all of its event processing methods.

2. Registers as an observer with method addChangeListener.

3. Subscribes to the notifications.

After receiving the OSS Client registration and subscription, JavaAPI calls the appropriate eventprocessing methods implemented at the OSS Client application.


31


Fig. 5 Subscribing to NBI Inventory and NBI Alarm Notifications

5.10.1 Implement TolEventObserver Interface

Implement interface TolEventObserver in your client application and override all its eventprocessing methods:

public class MyClientService implements TolEventObserver {

...

// Method addNotification is called when a new change message of type "add" occurs.

public void addNotification(TolAddEvent addEvent) {

...

}

// Method updateNotification is called when a new change message of type "update"occurs.

public void updateNotification (TolUpdateEvent updateEvent) {

...

}

// Method delNotification is called when a new change message of type delete occurs.

public void delNotification(TolDelEvent delEvent) {

...

}

// Method systemNotification is called when a new system notification message occurs.

public void systemNotification(TolSystemEvent systemEvent) {


32


...

{

// Method alarmNotification is called when a new alarm notification message occurs.

public void alarmNotification(TolAlarmEvent alarmEvent) {

...

}

}

5.10.2 Register as an Observer with addChangeListener Method

Register the OSS Client application as a listener to notifications by calling the methodaddChangeListener:


addChangeListener Register the given Java classas an observer to notifications.Note: the given java classmust implement the interfaceTolEventObserver.

eventObserver

5.10.3 Check if Notifications Are Supported for the Entity

NbifAttributeService provides methods for checking if notifications are supported for an entity.Also, NbifAttributeService provides you with methods for getting all entities.

5.10.4 Subscribe Commands for Subscribing to Inventory Entities

The following methods are available for getting notifications on Inventory entities (NIMA in port2462). Note that the NBI server does not support notifications on Performance entities:


subscribeNotification Subscribe to those entities forwhich notifications are wanted.

int handleIdArrayList entityIds

unsubscribeNotifica-tion

Unsubscribe all notifications. int handleId

If you call the method subscribeNotification again, the old subscriptions are droppedand the new list of entities will be subscribed to.


33


5.10.5 Subscribe Commands for Subscribing to Alarm Entities and SystemNotifications

The following methods are available for getting Alarm and System notifications through the NBIFault and Provisioning adapter in port 2461:


subscribeNotification Subscribe to those entities forwhich notifications are wanted.

int handleIdArrayList entityIds

unsubscribeNotifica-tion

Unsubscribe all notifications int handleId

subscribeSystemNoti-fication

Subscribe to system notifications int handleId

unsubscribeSystemNo-tification

Unsubscribe systemnotifications

int handleId

5.10.6 Handle the Received Inventory Notifications

You have already implemented interface TolEventObserver in your client application andoverridden all of its event processing methods addNotification, updateNotification,delNotification, alarmNotification, and systemNotification (see5.10.1 Implement TolEventObserver Interface).

JavaAPI calls the event processing methods every time there is a new event coming from theNBI service. For each of the notification types (Create, Attribute Value Change, Delete, Alarm,System) there is a corresponding class (TolAddEvent, TolUpdateEvent, TolDelEvent,TolAlarmEvent, TolSystemEvent) containing the methods that can be used to extract thenotification-specific data. The actual record data should be extracted using the TolResultSetmethods.

Create Notifications

JavaAPI calls method addNotification (TolAddEvent addEvent) implemented in theOSS client application when a new inventory object has been created in the Tellabs 8000 managersystem.

There are methods available for retrieving data from the TolAddEvent object which the methodaddNotification gets as a parameter:

1. Method for getting the entity ID of the created object (int getEntityId()).2. Method for getting the number of attributes of the created object (int getNumberOfAt-

tributes()).3. Method for getting attribute IDs of the created object in an ArrayList (ArrayList getAt-

trIdList()).4. Method for the getting the TolResultSet object containing values for each of the attributes (Tol-

ResultSet getAttrValueSet()).


34


To retrieve the data from the TolResultSet object, use the methods of TolResultSet. TolResultSet isdescribed in 5.8.5 Retrieve the Result Data .

Attribute Value Change Notifications

JavaAPI calls method updateNotification (TolUpdateEvent updateEvent)implemented in the OSS client application, when there is a change in the Tellabs 8000 managersystem inventory data.

There are methods available for retrieving data from the TolUpdateEvent object which the methodupdateNotification gets as a parameter. The TolUpdateEvent object contains data on the keyattributes and data on the changed attributes.

1. Method for getting the entity ID of the object, whose values have been changed (int getEn-tityId()).

2. Method for getting the number of key attributes (int getNumberOfKeyAttributes()).3. Method for getting the number of changed attributes (int getNumberOfChangeAt-

tributes()).4. Method for getting key attribute IDs in an ArrayList (ArrayList getKeyAt-

trIdList()).5. Method for getting attribute IDs of the changed attributes in an ArrayList (ArrayList

getChangeAttrIdList()).6. Method for the getting the TolResultSet object containing key attribute values (TolResult-

Set getKeyAttrValueSet ()).7. Method for the getting the TolResultSet object containing attribute values for the changed at-

tributes (TolResultSet getChangeAttrValueSet()).To retrieve the data from the TolResultSet objects, use methods of TolResultSet. The use ofTolResultSet is described in 5.8.5 Retrieve the Result Data.

Delete Notifications

JavaAPI calls method delNotification (TolDelEvent delEvent) implemented in theOSS client application when an inventory object has been deleted from the Tellabs 8000 managersystem. There are methods available for retrieving data from the TolDelEvent object which themethod delNotification gets as a parameter.

1. Method for getting the entity ID of the deleted object (int getEntityId()).2. Method for getting the number of key attributes (int getNumberOfKeyAttributes()).3. Method for getting the key attribute IDs in an ArrayList (ArrayList getKeyAt-

trIdList()).4. Method for the getting the TolResultSet object containing values for each of the key attributes

(TolResultSet getKeyAttrValueSet()).To retrieve the data from the TolResultSet object, use methods of TolResultSet. The use ofTolResultSet is described in 5.8.5 Retrieve the Result Data.


35


5.10.7 Handle the Received Alarm Notifications

You have already implemented the interface TolEventObserver in your client application andoverridden all of its event processing methods addNotification, updateNotification,delNotification, alarmNotification, and systemNotification (see5.10.1 Implement TolEventObserver Interface). JavaAPI calls method alarmNotification(TolAlarmEvent alarmEvent) implemented in the OSS client application when there ischanged alarm data in the Tellabs 8000 manager system.

Notification handling of alarm notifications is different from handling inventory notifications. Forthe NBI Inventory data, Tellabs 8000 manager NBI provides separate event notification for Create,Attribute Value Change, and Delete events. For NBI alarm data, there is no concept of Create,Delete, and AVC events. Whenever there is a change in a alarm object instance (NE alarm, servicealarm), the NBI will send a complete updated object to the OSS Client. This update message doesnot contain information on what has happened to the object. Also, the update data can containinformation on more than one alarm record.

For example, in case of an existing NE Alarm whose status has turned from Active to Cleared, theNBI sends a complete NE Alarm record with the Alarm Status attribute set to Clear, and with theClear Date set with the time stamp when the NE Alarm was cleared. There are methods availablefor retrieving data from the TolAlarmEvent object which the method alarmNotificationgets as a parameter:

1. Method for getting the entity ID of the alarm object (int getEntityId()).2. Method for the getting the TolResultSet object containing values for each of the attributes of

the alarm object (TolResultSet getAttrValueSet()).To retrieve the data from the TolResultSet object, use methods of TolResultSet. The use ofTolResultSet is described in 5.8.5 Retrieve the Result Data.

Note that more than one alarm object can be included in the TolResultSet.

To get the attribute IDs of the alarm object, use the method ArrayList getAttrIdList() of theTolResultSet object.

5.10.8 Handle the Received System Notifications

You have already implement interface TolEventObserver in your client application andoverridden all of its event processing methods addNotification, updateNotification,delNotification, alarmNotification, and systemNotification (see5.10.1 Implement TolEventObserver Interface).


36


JavaAPI calls method systemNotification (TolSystemEvent systemEvent)implemented in the OSS client application when there is an error in the NBI service. Thereis a method available for retrieving data from the TolSystemEvent object which the methodsystemNotification gets as a parameter:

1. Method for getting the error code of the system notification (int getMessageType())1. error code 1:

The NBI Kernel shutting down. Sent when the NBI Server Supervisor stops NBI Kernelprocesses.

2. error code 2:Notifications lost. Internal processes of the NBI server are unexpectedly terminated, orthe server has lost connection to the database.

5.11 Acknowledging Alarms

The following method is available for acknowledging Network Element (NE) alarms through theNBI Fault and Provisioning adapter in port 2461:

Command Description Parameters

acknowledgeAlarm acknowledges an NE alarm inTellabs 8000 manager

long handleIdint faultID

Method acknowledgeAlarm acknowledges the NE alarm, which has the given alarm ID (givenas a parameter faultId). Give as input the ID of one Network Element alarm which you want toacknowledge.

5.12 Pinging the NBI Server to Verify that It Is Alive

Use ping commands to verify the status of the services on the NBI Server. Verify that the NBIServer Inventory and Performance service (NIMA) is alive using the method pingNima ofTolService class:

public void pingNima (long pingPacketSize) throws IOException,TolCommunicationException

Verify that the NBI Server Fault and Provisioning Service (NSA) is alive using the methodpingNsa of TolService class:

public void pingNsa () throws IOException, TolCommunicationExcep-tion

For more information on the ping commands, refer to 6.2.5 Method pingNima and 6.2.6 MethodpingNsa.

5.13 Command Names and Codes

You do not have to worry about the command names or codes if you call the TolService methodswhich carry out the commands.


37


If you want to create your own GUI for handling the commands by their names (or codes), you canuse JavaAPI classes TolType and TolTypeService.

The command codes and names are available in TolType class. You can use those variables directlyfrom TolType class (see 12.1 Values in TolType Class).

You can also use methods of TolTypeService class to get all command codes or names and to find aname for a command code and vice versa. For example, the methods listed below are available.There are also methods in TolTypeService, which return (see 12.2 TolTypeService Methods forHandling Commands):

1. All command names or codes (either Inventory and Performance or Alarm commands).

2. Command name for a command code and vice versa.

5.14 Close Session

After using the JavaAPI, release the threads and other resources by closing the socket using methodcloseCommunication of TolService class.

Method closeSession expects the handleId of your session as a parameter.

public voidcloseSession(long handleId)throws IOException, TolCommunicationException

5.15 Close Communication (Socket)

At the very end, close the socket using method openCommunication of TolService class

public void closeCommunication() throws IOException

JavaAPI commands allow managing the commands with names/symbols. However, thecorresponding IDs/codes are used in the communication between the Northbound Interfaceand the JavaAPI. So in the byte streams between your OSS clients and the NorthboundInterface you would see only the IDs/codes.


38

6 TolService Class

6 TolService Class

This class contains all methods needed to establish sessions to the Tellabs 8000 manager NBI and tosend request commands. Other classes (e.g. TolResultSet) should be used to process the Tellabs8000 manager NBI response data.

To initiate a session to the Tellabs 8000 manager NBI, the OSS Client application should first callthe openCommunication method to establish a communication path to the appropriate NBIServer and TCP port. Once the communication is established, the OSS Client should login to theNBI service by calling the openSession method.

Once the session is established, the OSS Client can subscribe to event notifications by calling thesubscribeNotification method, send get requests using the getXXXData methods, andsend provisioning requests by using the executeMacro method.

The default constructor of TolService takes no parameter and prints trace messages on defaulttrace level:

TolService ()Construct a new TolService object. Use default trace log level of JavaAPI.

Parameters

Exceptions

The alternative constructors of TolService take the trace level as a parameter.

TolService (int loglevel) TolService(String loglevelname)

Construct a new TolService object and define the trace log level of JavaAPI. Valid values for thetrace level are defined in class TolType (see 12.1.7 Trace Level.) If the given trace log level isinvalid, the default trace log level is used.

Parameters logLevel/loglevelName trace level for JavaAPI

Exceptions

For more information on the trace levels, see 6.7.1 Trace Level of JavaAPI.

The following sections describe all the methods available in the TolService class.


39

6 TolService Class

6.1 Establishing Connections to the Tellabs 8000 Manager NBI

6.1.1 Method openCommunication for Opening Socket

Open a communication path to the Tellabs 8000 manager NBI. This is the first method the OSSClient should call to establish a connection to the Tellabs 8000 manager NBI. This methodestablishes the TCP socket connection to the NBI server port.

void openCommunication (String hostAddress, int portNum-ber)throws IOException

Parameters hostAddress (Input)Specifies the IP address of the NBI servercomputer

portNumber (Input)Specifies the TCP port number of the NBIservice

Exceptions IOException is thrown if an I/O error occurs

6.1.2 Method closeCommunication for Closing Socket

Close communication path to the Tellabs 8000 manager NBI.

void closeCommunication () throws IOException

Exceptions IOException is thrown if an I/O error occurs

6.1.3 Method openSession

Opens an OSS Client session to the NBI service. This method should be called after a successfulexecution of the openCommunication method. While openCommunication establishes aconnection to the NBI Server socket port, the openSession establishes a client session to the NBIservice. The OSS Client should include a OpenResultSet object as a parameter which will be filledby JavaAPI with a Client HandleId that uniquely identifies the session to the NBI service.

void openSession(String userName, String passWord, OpenResultSetopenResult) throws IOException, TolCommunicationException


40

6 TolService Class

Parameters userName (Input)specifies the login name for the OSS Client session

passWord (Input)specifies the password for the OSS Client session

openResult (Output)OpenResultSet returned by Tellabs 8000 manager NBIcontaining the handleId.

Exceptions IOException is thrown if an I/O error occursTolCommunicationException is thrown if a communication exceptionoccurs

6.1.4 Method closeSession

Close an OSS Client session to the NBI service.

void closeSession (int handleId) throws IOException,TolCommuni-cationException

Parameters handleId (Input)Client specific handle that is used to identify asession

Exceptions IOException is thrown if an I/O error occursTolCommunicationException is thrown if a communicationexception occurs

6.2 Requesting Inventory or Performance Data from the Tellabs 8000Manager NBI

6.2.1 Method getAllData

Populate resultSet with all objects within the requested inventory or performance entity.

To parse the resultSet data, the OSS Client should use the methods available in the TolResultSetclass. See description of the TolResultSet object in 7 TolResultSet Class.

void getAllData (long handleId, int entityId, ArrayList se-lectedAttributes, TolResultSet resultSet) throws IOException,TolCommunicationExcep

javaapi for tellabs® 8000 network manager northbound interface

Documents

tellabs manual

tellabs operations

tellabs logo

network manager r17ajavaapi

following trademarks

t symbol

international copyright

document informationterms