ADK Developer Guide

Odyssey 3

Device Adapter Development Kit (ADK) Developer’s Guide

Issue 1.0 Draft May 2006 ADK Release 4.4

Notice

Management Integration Platform (MIP) Developer Guide

© 2001–2006 Nortel Networks All rights reserved.

The information contained herein is the property of Nortel Networks and is strictly confidential. Except as expressly authorized in writing by Nortel Networks, the holder shall keep all information contained herein confidential, shall disclose the information only to its employees with a need to know, and shall protect the information, in whole or in part, from disclosure and dissemination to third parties with the same degree of care it uses to protect its own confidential information, but with no less than reasonable care. Except as expressly authorized in writing by Nortel Networks, the holder is granted no rights to use the information contained herein.

Nortel Networks, the Nortel Networks logo, the Globemark are trademarks of Nortel Networks.

Sun, Solaris, Java, JDK, and iPLANET are trademarks of Sun Microsystems, Inc.

JBOSS is a trademark of Marc Fleury.

Microsoft, Windows, and Internet Explorer are trademarks of Microsoft Corporation.

Netscape Directory Server, and Netscape Navigator are trademarks of Netscape Communications Corporation.

RADIUS is a trademark of Radius, Inc.

UNIX is a trademark of X/Open Company Limited.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

This product includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/ .

2

Management Integration Platform Device Adapter Development Kit

Publication History

May 2006

Draft for Odyssey 3 DP3.

October 2005

Standard version for Odyssey 2. Updated information on new NE types.

February 2004

Reissue of standard release for ADK 4.3 for Framework Release 3.2. Contents have not changed, but issue number and date have been updated to reflect the corresponding software version.

July 2003

Standard release for ADK 4.3. Updates include:

■ “Starting and stopping the background processes” on page 54

■ “Required attributes” on page 100

May 2003

Preliminary release for ADK 4.3. Updates include:

■ “Installing a lightweight ADK” on page 41 (without the IONA Orbix trader)

■ “Configuring multiple sub-domains” on page 61

■ “Library behavior during loss of connection to Model Service” on page 96

3


About this guide

This guide introduces the Device Adapter Development Kit (ADK) to those developers who need to integrate a new type of network element into Framework.

This guide will enable you to understand the development efforts that are required to integrate a network element into NSP by using the ADK.

The Device Adapter Development Kit (ADK) Developer’s Guide is divided into the following chapters:

Chapter 1, Introduction—describes the Device Adapter architecture, the characteristics of a Device Adapter developed using the ADK, the required capabilities of a network element or element management system, the requirements of a development system that will use the ADK, and the skills needed to use it.

Chapter 2, Installation and configuration—describes how to download and install the ADK, and how to configure a test system to run the sample Device Adapter that is included with the ADK.

Chapter 3, Development tasks—describes the development options and the scenarios for which the ADK can be used, provides an overview of the

4


development tasks required for each of these development options, and describes the first and most basic of these tasks.

Chapter 4, Developing the basic Device Adapter—describes the development tasks required to develop the basic Adapter plug-in (this is the main development effort.)

Chapter 5, Developing resource and alarm capabilities—describes the steps required to develop support for resource and alarm management capabilities in the Adapter plugin.

Chapter 6, Developing a Model Conversion File—describes the format and syntax of the file that is used to map the object model used by the network element to the object model that is used by the Framework.

Chapter 7, Compiling and packaging your Device Adapter—describes the steps you must perform to compile, package, and test the Device Adapter that you have developed.

Appendix A, Allocation policy—shows the classes, number of instances and the associated allocation policy that you should use when developing your Adapter plug-in.

5


Appendix B, Engineering information—has been removed. For this information, see the Framework Engineering Guide, “Engineering Considerations” chapter.

Glossary—defines the major terms and abbreviations used in this guide and throughout NSP.

6


Conventions and Feedback

Conventions

The Device Adapter Development Kit (ADK) Developer’s Guide uses graphic aids to help you find information and to highlight input selections.

■ Cross-references in the document are hyperlinked, indicated by blue text. Table of contents entries and index entries are also hyperlinked but are shown in plain text.

■ UNIX commands and the names of files, methods, classes, and directories appear in Courier.

■ Method names appear in the text followed by ‘()’ regardless of whether the method has parameters, for example, Reconfigure().

■ Names of menu items and button labels appear in bold, Arrows separate levels on the main menu and the submenus; for example, Choose Fault > Client1.

Feedback

Documentation change requests are tracked in ClearQuality. If you see an error, or you feel we need to provide more emphasis or clarity, please let us know. This will help us to keep this Guide accurate, effective and up-to-date.

7


For Further Information

Additional documentation is available for developers, as follows:

■ Odyssey 3 Technical Overview

■ Odyssey 3 Developer Guide

■ ADK API Reference

■ List of Operational Considerations (LOC)

All of these documents are available on the Advantage web site located at: http://advantage.ca.nortel.com/

8

http://advantage.ca.nortel.com/


sign & egration esting

X

Document Roadmap

For your reference and to assist you with navigating through this book, we are introducing a list of suggested topics based on your particular interest profile. For instance, if you are a Designer refer to the Designer list of recommended readings. In most cases, you may hyper-link directly to each topic.

You may return directly to this page from other sections in this book by clicking on the “Return to Document Roadmap” box (pictured below).

RETURN TO DOCUMENT ROADMAP

Area of Interest Location Architect DesignerDe

IntT

Functionality “ADK Device Adapter Features” on page 30 X

Architecture “Architecture” on page 22 X

Engineering Limits Refer to the Engineering Considerations chapter in the Framework Engineering Guide

X X

List of Operational Considerations “For Further Information” on page 8

X

Client request: Manual Alarm Clear; acknowledgement

“Develop special alarm handling” on page 138

X

Development Environment requirements including Platform and 3rd party software and compiler requirements

Release NotesX X

What elements are required to compile a DA plug-in?

“Compiling and packaging your Device Adapter” on page 175 X

9


X

X

X

X

X

X


What is available from the ADK API? “For Further Information” on page 8(see ADK API Reference)

X

Where to get support “Downloading and installing the ADK” on page 35

X

How to get started “Configuring and sanitizing the test environment” on page 47 and “Developing the basic Device Adapter” on page 73

Model Conversion Files and how to construct, package and deploy.

“Developing a Model Conversion File” on page 148

How to test the plug-in “Use the Compliance Tools” on page 51

Fault Information: How to model it “Developing resource and alarm capabilities” on page 105

X

Fault Information: What is the minimum information needed for the “northside client”?

Refer to Partner Application Development Team X

Fault Information: What information is expected from the various Framework components?

(see the NSP Developer’s Guide - Chapter NSP Fault - reference in “For Further Information” on page 8

X

How to run ADK components from the command line, bypassing AM.

“Run the Device Adapter” on page 53

How to use the compliance tools. “Use the Compliance Tools” on page 51

How do the DA components work? “Architecture” on page 22

Overview of the various logs and how to control the logging level

“Logging and tracing” on page 103 X

When we test a DA, what should the plug-in log?

“Logging and tracing” on page 103


IntT

10


X

X


Resource information: How to model it “Developing a Model Conversion File” on page 148

X

Resource Information: What is the minimum information needed for the “northside client”?

“Establish communications with the NE/EMS” on page 114 X

Resource Information: What information is expected from the various Framework components?

“Handle OSI state changes” on page 132 X

Plug-in sequence, initialization and event loop

“Developing the basic Device Adapter” on page 73and “Developing resource and alarm capabilities” on page 105

X

EMS resynchronization and plug-in recovery considerations

“Developing resource and alarm capabilities” on page 105

X

How to convert your existing plug-in to use the latest ADK/FW features

“For Further Information” on page 8(see ADK Release Notes)

X

What source files should be included? “Compiling your Device Adapter” on page 179

X

Application Management of a plug-in “Specialize Init()” on page 84 to “Specialize Shutdown()” on page 93

X X

How to package and deliver a DA “Packaging your Device Adapter” on page 181 X X


IntT

11

Contents

Framework ■ ADK Developer’s Guide

Table of Contents

1Introduction

Architecture 22ADK CORBA Adapters 24Integration Server 26Device Adapter 27

Advantages of using the ADK 29

ADK Device Adapter Features 30

Network element requirements 32

Platform and compiler requirements 33

2Installation and configuration

Downloading and installing the ADK 35

Release-specific installation or upgrade issues 37Installing ADK 37Installing a lightweight ADK 41Third-Party Software Packages 42

ADK files and directories 42

Sanitize the development environment 45

Configuring and sanitizing the test environment 47

Managing the Device Adapter 54Starting and stopping the background processes 54

Configuring multiple Device Adapters 56

Process view 57Component view 59Assigning domains in a multi-DA environment 60

Configuring multiple sub-domains 61Configuration 63Sample configuration file 63Changing the number of sub-domains 64Synchronization with multiple sub-domains 64Replacing Device Adapters 64Assigning Model Service domains 65

Upgrading ADK 66

Uninstalling ADK 68

3Development tasks

New NE Types 70

14

Contents


Develop an NE-specific Device Adapter 71

Develop a Model Conversion File 72

4Developing the basic Device Adapter

Overview of Device Adapter basics development 74

Device Adapter base classes 79Write a global function to create an MDRAdapterFactory instance 80Specialize the MDRAdapterFactory class 81Specialize the MDRAdapter class 82Implement the constructor 84Specialize Init() 84Specialize SetupInitialConfig() 86

Specialize Reconfigure() 88Using GetConfig() 91Specialize Start() 91Specialize Stop() 92Specialize Shutdown() 93Specialize Resynchronize() 95Providing Automatic Restart 97Adding capabilities to your plugin 98

General development considerations 99

Required attributes 100Error handling and exception policy 101Logging and tracing 103

Synchronization 104

5Developing resource and alarm capabilities

Overview of developing resource and alarm capabilities 106

Develop a way for Shutdown() to communicate with Start() 112

Specialize the Start() method 113

Establish communications with the NE/EMS 114

Perform initial NE discovery 115

Add vendor-specific information 116Adding support for Easy.ON support bits 117

Perform initial alarm discovery 125

Call StartCB() 126

Develop the event loop 127Handle NE events 129

15

Contents


Handle alarm events 130Handle OSI state changes 132Handle NE attribute changes 133Fault/Resource Synchronization scenarios 134Check for shutdown calls 137

Develop special alarm handling 138Handle manual alarm clear requests 139Handle alarm acknowledge request 143Handle service grade alarms 147

6Developing a Model Conversion File

Introduction to the Model Conversion File 149

Distinguished name 151NSP Object Model 152Name binding tree 154Generic attributes 161Network object mapping 162MCF restrictions and limitations 163

Create the Model Conversion File for your plugin 165

Sample inm.map file (MCF) 173

7Compiling and packaging your Device Adapter

Chapter overview 176

Directory Structure 177

Compiling your Device Adapter 179

Packaging your Device Adapter 181

Installing your packaged Device Adapter 182

AAllocation policy 183

BEngineering information 186

ADK platform requirements 187ADK engineering limits 188

Glossary 189

16

List of Figures


List of FiguresFigure 1-1 Device Adaptation architecture 23

Figure 2-1 Multi-DA - Logical/Process View 57

Figure 2-2 Multi-DA - Component View 59

Figure 2-3 Multiple sub-domain configuration 62

Figure 4-1 Device Adapter lifestyle message sequence diagram 75

Figure 4-2 MDR factory and adapter class diagram 79

Figure 4-3 Sample code for init_mdr_factory() 80

Figure 4-4 Code example for inheriting the MDRAdapterFactory class 81

Figure 4-5 Code example for implementing the createMDRAdapter() method 81

Figure 4-6 Code example for implementing the MDRAdapter constructor 84

Figure 4-7 Sample code for specializing Init() 84

Figure 4-8 Code example for specializing SetupInitialConfig() 87

Figure 4-9 Code example for specializing Reconfigure() 90

Figure 4-10 Code example for specializing Stop() 93

Figure 4-11 Code example for Shutdown() 94

Figure 4-12 Code example for retrieving an invalid argument exception string 102

Figure 5-1 Simplified resource and alarm class diagram 108

17

List of Figures


Figure 5-2 Basic resource and alarm interactions diagram 110

Figure 5-3 Resynchronization diagram (following failure of JBoss or Model Service) 111

Figure 5-4 Code example for declaring a global variable 112

Figure 5-5 Code example for handling OSI state changes 132

Figure 5-6 Code example for handling NE Attribute changes 133

Figure 5-7 Code example for checking shutdown calls 137

Figure 6-1 Sample entries from a Model Conversion File 149

Figure 6-2 Managed object name binding tree 155

Figure 6-3 Sample mapping line 169

Figure 6-4 Mapping a line in the MCF to the Object Model 170

Figure 6-5 Default mapping of an object not specified in the MCF 171

Figure 6-6 Multi-level network object mapping 171

Figure 6-7 Sample inm.map file (1 of 2) 173

Figure 6-7 Sample inm.map file (2 of 2) 174

18

List of Tables

19

Framework - ADK Developer’s Guide

List of TablesTable 4-1 Specialization of the MDRAdapter base class

methods 82

Table 5-1 Required specialization for resource and alarm management capabilities 109

Table 5-2 Support Bits Constraints 118

Table 5-3 Events, objects, and methods in the event loop 128

Table 5-4 Definition of event times 131

Table 5-5 SupportBitConstants for manual alarm clear requests 139

Table 6-1 Supported standard object classes 156

Table 6-2 Supported generic object attributes 161

Table A-1 ADK allocation policy 183

Table B-1 ADK Engineering Limits 188

http://crestdoc.ca.nortel.com/FRAMEWORK/BookFeedback/feedback_obtain.php

Introduction


1

Introduction

The Framework provides two development kits:

■ Desktop UI

■ Device Adapter Development Kit (ADK)

These development kits enable you to build Graphical User Interfaces, Applications, and Device Adapters for Framework based Management Solutions (FMS).

Device Adapters adapt the data from a specific type of network element (NE), often through an Element Management System (EMS) that controls a number of NEs, into a format that can be used by Framework- based Management Solutions. Device Adapters also either perform network management commands that are issued by Framework-based Management Solution users, or relay them to the network elements.

The ADK provides tools, run-time components, libraries, and an Application Programming Interface (API) that allows developers to create a Device Adapter as quickly and efficiently as possible.

20


1 RETURN TO DOCUMENT ROADMAP

This guide provides instructions to help you:

■ install the ADK

■ configure a development system to use the ADK

■ configure a system for testing the developed Device Adapter

■ develop a Device Adapter using the ADK, including capabilities for resource and alarm management

■ compile, test, and package the Device Adapter

This chapter describes:

■ Architecture

■ Advantages of using the ADK

■ ADK Device Adapter Features

■ Network element requirements

■ Platform and compiler requirements

Note: Any mention of Device Adapter in this document refers to Device Adapters created using the ADK.

Introduction 21

Architecture



Architecture Device Adaptation is achieved through a package of software components and supplemental files that are used to normalize the data from a specific type of NE, often through the NE’s EMS, into the CORBA-based format used by FMS.

Each of these components and their place in the Device Adaptation architecture is shown in Figure 1-1, below. Each component is discussed in greater detail in the pages following this figure.

Introduction 22

Architecture



Figure 1-1 Device Adaptation architecture

M C F

D e v ic e A d a p t e r

X M L - J M S

I n t e g r a t io n S e r v e r

A D K C o r b a A d a p t e r

C O R B AG a t e w a y

N S P

C O R B A

X M L - J M S

N E / E M S

A P

X D R

m a n a g e m e n t p r o t o c o l

M C F

D e v ic e A d a p t e r

X M L - J M S

I n t e g r a t io n S e r v e r

A D K C o r b a A d a p t e r

C O R B AG a t e w a y

N S P

C O R B A

X M L - J M S

N E / E M S

A P

X D R

m a n a g e m e n t p r o t o c o l

Introduction 23

Architecture



ADK CORBA Adapters

The ADK CORBA Adapter component manages the north-bound CORBA communications with the Framework resource and fault applications, respectively. These mediation components are bundled in the ADK as a precompiled binary that requires no modification. An ADK CORBA Adapter runs in a single UNIX process.

The presentation function involves exposing the mediator interface over a networked interface such as IDL/IIOP (TMN CORBA).

The mediation function is the enhancement of the services and the recomposition of the objects of a management interface to produce an interface expected by a TMN manager (Q3). In framework based management solutions the presentation and mediation functions are provided by the fault and resource interfaces of the ADK CORBA Adapter.

The functions assumed by the mediation layer are:

■ attribute recomposition—attributes are split or amalgamated based on type and on value to be compatible with a standard information model (M.3100, M4, etc.)

■ provision of ITU common services—ITU specified system management services which can be applied to any resource in an NE (for example X.734 for event forwarding and discrimination)

Introduction 24

Architecture



■ provision of ITU conformable interfaces— these follow established standard resource and service frameworks for NE management interfaces which are expressed in GDMO/ASN.1. The resources of the interfaces are a specialization of one or more standard resources, and the services of the interfaces must be resource-independent.

The ADK CORBA Adapter is the upward-looking interface of a Device Adapter that communicates with the Framework resource management clients over a standards-based CORBA interaction model. It provides fault management and resource data on all the managed network elements.

Introduction 25

Architecture



Integration Server The Integration Server (IS) provides a number of services to route and process XML encoded messages and domain objects (alarms, managed elements). Device Adapters send XML serialized domain objects to the Integration Server with XML messages transported over the Java Messaging Service.

The Integration Server assumes the function of object recomposition, which recomposes and renames the NE’s objects to be compatible with a standard information model (M.3100).

The IS also provides a centralized, non persistent, cache for all ADK components.

Introduction 26

Architecture



Device Adapter The Device Adapter retrieves data from many network elements of a specific type for use in FMS and conveys commands, issued by users to those network elements. It is this component, the Device Adapter binary, that requires the main development effort. It is bundled in the ADK in the form of the Device Adapter libraries, which handle the northbound interface to the Integration Server, and the ADK API. From the ADK API you develop the Device Adapter plug-in, the south-bound interface to the NE or EMS. When they are compiled, the Device Adapter libraries and the Device Adapter plug-in form the Device Adapter binary.

In addition to the Device Adapter plug-in, you must develop the Model Conversion File, a supplementary file which is required by the resource management functions of the Device Adapter.

Device Adapter libraries—These handle much of the functionality of the Device Adapter binary and require no development. They receive the NE or EMS data from the Device Adapter plug-in and communicate this data to the appropriate integration service using XML messaging over a Java Messaging Server (JMS). The Adapter libraries are linked with the Adapter plug-in to create the Device Adapter binary. This binary runs as a multi-threaded UNIX process, one thread of which is dedicated to NE-specific adaptation where the Adapter plug-in is run.

Introduction 27

Architecture



The ADK Adapter libraries and mediation components hide the CORBA-based interface to the Framework based management components. This frees you from having to know CORBA or the Framework-supported Interface Definition Language (IDL) when developing the NE-specific Adapter plug-in.

Device Adapter plugin—This is the component that you develop. It is the downward-looking interface of the Device Adapter that receives information from a specific type of network element and formats it into the model used by the Device Adapter client applications.

Device Adapter Binary—This is the component that is built when you compile the Adapter libraries from the ADK and the Adapter plug-in that you develop.

MCF—The Model Conversion File, which you must develop, is one of the supplementary files that must be included in the Device Adapter package. It is used by resource management to map network entities in the NE object model to entities in Framework object model.

Introduction 28

Advantages of using the ADK



Advantages of using the ADK

The ADK is designed to provide a simple and efficient way to integrate network elements into the Framework based management solutions. The main advantages of using the ADK include:

■ a reliable approach to developing Framework- compliant Device Adapters

■ a vendor-independent way to make Network Elements (NE) Framework compatible

■ a reduction in the technology that must be learned

■ a reduction in code complexity, achieved by hiding low-level interactivity between the Framework based management solution and the Device Adapter

Introduction 29

ADK Device Adapter Features




This section describes the capabilities, dependencies, restrictions and limitations of an ADK-developed Device Adapter.

Device Adapter capabilities

Device Adapters developed with the ADK support the following specific capabilities for:

■ resource management:

■ automatic network element discovery

■ support for multi-level network objects

■ fault management:

■ active alarm discovery and alarm synchronization by NE

■ manual clearing of alarms from the GUI■ alarm acknowledgement■ flagging alarms as being service grade

Scalability and engineering

A Device Adapter developed with ADK supports up to 3500 NEs and 24,000 alarms.

The ADK CORBA Adapter and Integration Server components can support multiple Device Adapter processes, based on the resources that are available on the run-time platform and the resource usage of the

Introduction 30




plug-in and the EMS. The recommended maximum limit is four Device Adapter processes per Integration Server.

Dependencies on the Framework

Device Adapters developed using ADK are designed to work with Framework 3.0, 3.1 or 3.2.

Framework Object Model limitations

Certain limitations are imposed by the Framework Object Model, on which the Model Conversion File is based. These limitations are not listed here, as a full understanding of their implications requires that you become familiar with the concepts of the Framework Object Model and the Model Conversion File. For background information on the Framework Object Model and the Model Conversion File, see chapter 6, “Developing a Model Conversion File” on page 148. For a list of the limitations imposed by the Framework Object Model, see “MCF restrictions and limitations” on page 163.

Introduction 31

Network element requirements



Network element requirements

In order to integrate an EMS or NE into FMS using the ADK, you must ensure that they support the following capabilities, or you must develop them. The EMS must:

■ provide APIs for retrieving all NEs in its management domain upon initial connection or synchronization

■ be able to notify the Device Adapter about NEs added to, or deleted from, its management domain

■ be able to notify the Device Adapter about any state or attribute change of any NE in its management domain

■ provide APIs for retrieving all alarms for any one or for all NEs in its management domain upon initial connection or synchronization

■ be able to notify the Device Adapter of any alarms that are raised or cleared

■ provide a user interface that is accessible using TCP/IP

■ support an object-based information model

■ be able to detect the loss of communication with the NE and send notification of both loss and re-establishment of communication

Introduction 32

Platform and compiler requirements



Platform and compiler requirements

The Device Adapter Development Kit supports the Solaris 8 platform. The Device Adapter has an external dependency on third-party software libraries: Roguewave’s SourcePro and Iona’s Orbix ORB and Orbix Trader. The Device Adapter runs on Sun

UltraSPARC workstations. The Sun Forte TM C++ compiler is required.

Developer skills required

In order to use the ADK successfully, you must have knowledge of, and experience with:

■ object-oriented design and programming

■ multi-threaded programming

■ C++ language

Introduction 33

Installation a


2

Installation and configuration

This chapter guides you through downloading and installing the ADK. It describes how to set up the environment in which the Adapter plug-in is developed and tested; two tasks that can be performed on the same or different machines.

nd configuration 34

Downloading and installing the ADK




All software downloads and support for the ADK are handled through the Framework Advantage program.

The ADK software is now packaged using Sun packaging tools and is delivered in the following compressed.tar file: adk<version>.<load>.sun.<date>.tar.Z

This file contains two packages, NNadkrt (runtime) and NNadkdev (development). Installation of the development software requires the installation of the runtime package as well.

The software may be installed in the default directory or in a directory of your choice. Procedures for both installations are provided in “Installing ADK” on page 37.

The ADK software no longer includes 3rd party software and relies on the Framework installation to provide these components.

The ADK software is available to registered partners of the Framework Advantage program. It can be downloaded from the “My Advantage Program” link on the Framework Advantage page. For information about becoming a Framework Advantage partner select the “Help/Support information!” link and select the link entitled “Partner Registration”.

Installation and configuration 35

http://presideadvantage.ca.nortel.com/




The Framework Advantage web page also provides the following:

■ product information on the ADK and Framework

■ third-party software licensing information

■ access to ADK toolkits for registered partners.


http://presideadvantage.ca.nortel.com/




Release-specific installation or upgrade issues

For any issues relating to installation or upgrades for specific releases, see the List of Operational Considerations document for the applicable Framework release.

Installing ADK ADK software is bundled in 2 packages to streamline ADK installation, and the deployment of a developed Device Adapter.

NNadkrt.pkg: This package consists of all components that make up the ADK run time environment. This environment is essential for the device adapter development system and for the runtime deployment of the device adapter.

NNadkdev.pkg: This package consists of additional ADK components needed only on the ADK development system, and has a dependency on the runtime package NNadkrt.pkg. The installation of the development package will place additional components within the ADK runtime directory structure.

Note: ADK installation relies on Framework for 3rd party software. The prior installation of Framework is a prerequisite for the installation of ADK runtime (NNadkrt.pkg), which in turn is a prerequisite for the installation of ADK development (NNadkdev.pkg).





To install the ADK development environment in the Default directory

1. If you have not done so yet, install Framework on the target system.

2. Login to the target system as the root user.

3. Extract ADK packages NNadkrt.pkg and NNadkdev.pkg from the distribution compressed.tar file and place them in the Framework packages directory: zcat

adk.<version>.<load>.sun.<date>.tar.Z |

tar -xvf -mv NNadk*.pkg /opt/nortel/packages

4. cd to directory:

/opt/nortel/PresideNSP/current_NSPcommon/bin and invoke the ADK installation script with the -dev option: default_adk_install.sh -primary

<servername w/ trader> -type dev

For installing runtime components only, use "-type rt" option.

The installation script will take care of locating the appropriate packages, in the Framework packages directory

/opt/nortel/packages and installing them.





To install the ADK development environment in the directory of your choice

Assuming you wish to put the software under

/myloadbuild/adk_4.3.0.

1. If you have not done so yet, install Framework on the target system.

2. Login as the loadbuild administrator.

3. Enter the following script:

pkgtrans -o /opt/nortel/packages/

NNadkdev.PKG /myloadbuild

NNadkdev

This produces the following directory structure:

NNadkdev/|-- install`-- root `-- $ADKDir `-- adk_4.3.0 |-- lib `-- resources

4. Enter the following:

mv '/myloadbuild/NNadkdev/root/

$ADKDir/adk_4.3.0' /myloadbuild/

adk_4.3.0

5. Enter the following:

rm -rf /myloadbuild/NNadkdev





6. To locate ADK dev package files, change to the following directory:

cd /myloadbuild/adk_4.3.0

Disk Space Requirements

Installation of both ADK packages will require an estimated 90 MB of disk space excluding any Framework packages.

Installation logs are located in /opt/nortel/logs/PresideNSP

The installation process will update /etc/inittab to automatically start the Integration Server (IS) services of the ADK, and will register the Northbound ADK CORBA Adapter with the Application Manager (AM).

You can verify the registration of the ADK CORBA Adapter with AM, using the Framework AM script amcli.sh as follows:

./amcli.sh lsproctemplates wcars14k Waiting to connect to Orbix Daemon on host wcars14k ...Connected. Retrieving templates ...…. TEMPLATE_MFT_Corba_Adapter Done





Installing a lightweight ADK

Perform the following procedure to install ADK without the Orbix software that is responsible for the trader function.

In this configuration, Application Manager (AM), the northbound CORBA Adapter (CA), and any C++ adapter cannot be used, because of the dependence on Orbix. This option might be desired if north and south bound interfaces are not managed by AM and if they interact directly with the ADK Model Service.

To perform this installation, start the ADK installation script from the NSP bin directory with the option -orbix no as follows:

/opt/nortel/PresideNSP/

current_NSPcommon/bin/

default_adk_install.sh -orbix no

Note: This option changes the ADK dependency on the Orbix package: Framework does not install Orbix by default on this system.

Restoring the dependency on Orbix

To restore the original Framework installation behavior, you need to restore the original dependencies.dat file from dependencies.bak file in the following directory:


current_NSPcommon/resources


ADK files and directories



Persistent ADK configurations

Place ADK configurations that are to be preserved over releases and upgrades in the following directory:

/opt/nortel/config/adapters/adk/

Third-Party Software Packages

ADK 4.3 installation relies on MIP 5.0 for third-party software.

For more information, please refer to the ADK 4.3 Release Notes.


Once installation of the ADK is complete, and before you begin to test the system, you should examine the ADK directory structure and files.

ADK installs in "/opt/nortel/adapters/adk/current_adk". This is a fixed location and cannot be changed. The name current_adk is a symbolic link to the current ADK version directory within the same parent directory (i.e. ./current_adk -> ./adk_4.3.0). This link is updated with every ADK upgrade.

The subdirectories of the ADK installation are:

■ Runtime directory structure

■ bin■ Jars■ Lib■ resources/cfg





■ resources/cfg/EModel■ resources/cfg/generic■ resources/cfg/Mod■ resources/deploy

■ Supplemental development directories

■ resources/inc

■ resources/src/plugin

■ resources/doc/c++_api

■ resources/doc/java_api

The contents of each of these directories are discussed in the following paragraphs.:

bin: contains the binaries and launchers.

Jars: contains all the java classes required to run the background java proxies and messaging services

Lib: contains all of the ADK libraries used to develop, compile, and run a Device Adapter.

resources/cfg: contains various configuration files, including a sample inm.map (MCF) file in the generic subdirectory, which provides the default mapping of NE objects. Also, the start & stop scripts for ADK background processes.

Resources/deploy: contains QueueMgrEJB.jar for Jboss





resources/inc: contains the ADK header files that are required to compile the Device Adapter binary.

resources/src/plugin: contains the sample device adapter, source file, header file and the sample adapter makefile.·

resources/doc: contains the Java and c++ API subdirectories that contain the ADK API Reference (.html), and a soft copy of this guide.

ADK runtime logs are located within the subdirectories of "/opt/nortel/logs/adapter/adk/logs".

The sample device adapter located in the …/resources/src/plugin directory, is part of the ADK development package. It is included along with a sample makefile and a sample AM add template script. This device adapter provides a well-documented example of developing your own device adapter, and it presents a working example for compiling and running an adapter. In addition, it is used to sanitize the development and runtime environments.


Sanitize the development environment




Once you have installed the ADK development environment, compile the sample Device Adapter that is bundled with the ADK development package to ensure that your system is configured properly for the development of your Device Adapter.

The provided sample device adapter is a template to help you write your own plugin. It is also used for sanitizing your development and test environments.

The header file, source file, and makefile for the sample Device Adapter are located in resources/src/plugin subdirectory.

Compiling the Sample Device Adapter:

In order to compile the provided sample device adapter, you will need to update the location of your C++ compiler within the makefile.

■ cd to /opt/nortel/adapters/adk/

current_adk/resources/src/plugin

■ make a copy of the provided sample.makefile

■ update the C_DIR variable within the copy of the sample.makefile to point to the compiler installed on your system·

■ issue a make on the makefile





If all is well, you should have an executable created for you from the sample device adapter (SampleDeviceAdapter) to use in the next procedure, “Configuring and sanitizing the test environment” on page 47.

Compiling your own device adapter

To compile your developed device adapter, please refer to “Compiling your Device Adapter” on page 179.


Configuring and sanitizing the test environment




This section describes the tasks that you must perform to properly configure a system to run and test the Device Adapter that you develop, which also allows you to sanitize the test system.

Note: Many of these tasks must be done as the root user. If you do not have root privileges on the UNIX machine on which you are testing the Device Adapter, you must request that the configuration tasks be done by a system administrator.

You can run and test your Device Adapter on the same system that you develop it on, or on a different system. The ADK development installation provides complete run-time capabilities.

If you want to test the Device Adapter on another system, you will need to package the SampleDeviceAdapter, perform the ADK installation on the target system using runtime option only; and deploy the packaged device adapter.





Perform the following steps:·

■ Package the Sample Device Adapter

■ Install the ADK runtime

■ Install the Packaged SampleDeviceAdapter

■ Configure and Run the ADK CORBA Adapter

■ Use the Compliance Tools

■ Run the Device Adapter

Running the sample Device Adapter gives you hands-on experience with the interactions between the Application Manager and a Device Adapter, which is a part of your adapter development effort.

1. Package the Sample Device Adapter

Using your favorite packaging tool (the Sun Packaging Tool is recommended), locate and bundle the following files from the development system:

current_adk/bin/SampleDeviceAdapterLaunch.sh current_adk/resources/src/plugin/SampleDeviceAdapter

Note: Alternatively, you can use the SampleDeviceAdapter executable provided in the bin sub-directory.

2. Install the ADK runtime

This is needed only if the test is to be carried on a separate system (other than the development system, for example). The runtime installation steps are the





same as in the ADK development installation with the runtime option only. Please refer to “Installing ADK” on page 37 and select runtime option in step #4 (type-rt option).

3. Install the Packaged SampleDeviceAdapter

Place the files obtained from step #1, "Packaging the SampleDeviceAdapter" into current_adk/bin/

4. Configure and Run the ADK CORBA Adapter

This procedure describes how the new Application Management 3.2 is used by the ADK to add and configure the ADK CORBA Adapter. See the Network Services Platform (NSP) Developer’s Guide and view the chapter on Application Management for more information.

Application Management 3.2 relies on internal Orbix functionality to maintain the list of active processes along with maintaining the configuration of each individual process. In order for the ADK processes to be visible to AM 3.2, the ADK installation script registers the ADK CORBA Adapter template with Application Management at installation time. One ADK CORBA Adapter supports one DA.

Note: .../current_adk/bin/addAMtemplate.sh script does the registration of SampleDeviceAdapter template with AM, and it is invoked at installation time. This script can be used for customized templates registration.





To ensure the Device Adapter is properly configured, complete the following procedure (it is recommended that you have a copy of the Application Management 3.2 User Guide, 450-3101-221).

■ In AM configuration GUI, create a server by retrieving the ADK CORBA Adapter

■ Configure the ADK CORBA Adapter using the following information: — The domain name of the CORBA Adapter must match the sub-domain name of the associated FMBB and TUMSBB. —The sub-domain name of the CORBA Adapter must match the domain name of its associated Device Adapter. — ensure the acknowledgement field is set to TRUE (the default is FALSE) if you are using the sample adapter or if the device adapter supports alarm acknowledgement (the sample adapter supports alarm acknowledgement)

Note: Upon a successful ADK installation, the processes can be added, started, configured, and monitored using a combination of tools found in /opt/nortel/PresideNSP/current_NSPcommon/

bin. All the application management functions must be run from the machine running the Framework load. The shell script commands you will likely use include amcli.sh, config.sh, and monitor.sh. Please use the Network Services Platform (NSP) Developer’s





Guide, Application Management chapter to learn how to run and properly use these tools to add and configure the ADK servers.

5. Use the Compliance Tools

The ADK runtime package provides compliance tools (fm_compl_tool and rm_compl_tool in the current_adk/bin directory) to sanitize your test environment and test your Device Adapter for compliance without the need of a fully deployed Framework.

The Compliance Tools act as clients (in place of the Framework BBs) and send requests to the server. The compliance tools have a command line interface and can be invoked with the "-help" option for additional help information (rm_compl_tool -help) or (fm_compl_tool -help).

In the current_adk/bin directory you will find several sample files used to drive the fm_compl_tool (ackin.txt, filter.input, …)

To run the fm compliance tool:

■ open a separate xterm

■ in the new xterm, setup your shell environment properly by sourcing: current_adk/resources/cfg/

moafw.profile





■ run: ./current_adk/bin/fm_compl_tool -d

<domainname>

Note: The two main options used (common to both tools) are:·

-d <domainname> -- Mandatory. Specifies domain name for trading. This is the CORBA Adapter domain entered in the previous step·

-log -- Optional. Synchronous Get mode. Program retrieves all logs from the domain cache, and disconnects once they have been received. If not specified, only new logs are received, and disconnection takes place when the user disconnects.

To run the rm compliance tool:

■ open a separate xterm

■ in the new xterm, setup your shell environment properly by sourcing: current_adk/resources/cfg/

moafw.profile

■ run: ./current_adk/bin/rm_compl_tool -d

<domainname>

Note: The two main options used (common to both tools) are:·

-d <domainname> -- Mandatory. Specifies domain name for trading. This is the CORBA Adapter domain entered in the previous step·





-log -- Optional. Synchronous Get mode. Program retrieves all logs from the domain cache, and disconnects once they have been received. If not specified, only new logs are received, and disconnection takes place when the user disconnects.

6. Run the Device Adapter

If you want to trace events and NE enrollments produced by the Device Adapter, you should first start the compliance tools as described in the previous step “Use the Compliance Tools” on page 51.

The behaviour of the Device Adapter depends on the Device Adapter used. If you choose to run your developed Device Adapter, you need to make sure the environment is set properly.

The provided SampleDeviceAdapter will exercise the installation runtime by going through the steps of registering NEs, updating their status and producing fault on the NEs. Please refer to the code and comments provided within the SampleMDRAdapter.cxx for more details.

Running the sample device adapter:·

■ cd to current_adk/bin directory·

■ Start the compliance tools as described above.·





■ Start the SampleDeviceAdapter by invoking its launch script SampleDeviceAdapterLaunch.sh (for example, ./SampleDeviceAdapter.sh<processIDnumbe

r><DAdomain>

The SampleDeviceAdapter produces log files SampleDeviceAdapter *.log in the /opt/nortel/logs/adapters/adk/logs directory.

Managing the Device Adapter

To configure, manage and monitor the ADK CORBA Adapter or Device Adapter processes, use the Application Management client, either directly or through an SMC agent.

Starting and stopping the background processes

If for any reason, you need to stop the ADK background processes, perform the following steps:

1. From within the Application Management (AM) system, stop the ADK CORBA adapter.

2. Invoke the script current_adk/bin/stopClean.sh

To start the background processes, perform the following steps:

1. Invoke the script current_adk/bin/startJProcs.sh

2. Start the ADK CORBA adapter from the Application Management (AM) system.





You can stop and start (or restart) the ADK model service background process without having to stop the CORBA Adapter (and the Device Adapter, if designed for Resynchronization—see “Specialize Resynchronize()” on page 95). But, the ADK recommended order of startup is as follows:

1. Wait 2 minutes after jboss starts (or restarts) before starting (or restarting) any ADK components.

2. Then, wait 30 seconds after the Model Service starts (or restarts) before starting (or restarting) any Adapters (CA/DA).

In the case of rapid successive restarts, follow the startup order in the above recommendation.


Configuring multiple Device Adapters




The Multi-DA feature allows two or more DAs to be co-resident on a server. The maximum number of DAs that can be installed on one server is dependent upon many factors, however the design target is to allow four DAs on one server.

Installing multiple DAs on a server reduces the cost of developing, deploying and managing DAs. Resource usage (HD, RAM, CPU) is reduced, and less time is required to build, package and install ADK 4.3, compared with previous versions of ADK. Improved performance is an additional benefit.





Process view Figure 2-1 provides a logical view of the multi-DA feature and shows the processes used by the components.

Figure 2-1 Multi-DA - Logical/Process View

E M S N E

A D K< < d e v e lo p e d u s in g > >

X M L -J M S

X M L -J M S

C O R B A

T U M S B B

C O R B A

F M B B

D e v ic e A d a p te r

In te g ra t io n S e rv e r

A D K C O R B AA d a p te r

1 . .*1 . .*

1 . .*

1 . .*

1 . .*

1 ..*

1 1

( J a v a p ro c e s s ) ( C + + p ro c e s s )

( J a v a p ro c e s s )


( J a v a o r C + + p r o c e s s )

o n e o n e

m a n ym a n y

m a n y

o n e

o n e

m a n y

m a n y m a n y

m a n ym a n y

E M S N E

A D K< < d e v e lo p e d u s in g > >

X M L -J M S

X M L -J M S

C O R B A

T U M S B B

C O R B A

F M B B

D e v ic e A d a p te r

In te g ra t io n S e rv e r

A D K C O R B AA d a p te r

1 . .*1 . .*

1 . .*

1 . .*

1 . .*

1 ..*

1 1

( J a v a p ro c e s s ) ( C + + p ro c e s s )



( J a v a o r C + + p r o c e s s )

o n e o n e

m a n ym a n y

m a n y

o n e

o n e

m a n y

m a n y m a n y

m a n ym a n y





CORBA Adapter

The ADK CORBA Adapter replaces the RmMOA and FmMOA of earlier versions, and contains the interface functionality formerly handled by these devices. Its purpose is to adapt the XML input from the Integration Server to the CORBA IDL format that is used by the FMBB and TUMSBB.

Integration Server

The Integration Server provides the following services:

■ Transform

■ Notification Service

■ Model Service





rogwaverogwaverogwave

Component view Figure 2-2 provides a component view of the multi-DA feature and illustrates the package dependencies.

Figure 2-2 Multi-DA - Component View

The two main packages (Development Package and Runtime Package) contain all that is required to develop and deploy a new DA. The Development Package, NNadkdev, includes a sample DA that can be used as the basis for a new DA. The Runtime Package, NNadkrt, includes software to run the ADK CORBA Adapter and the Integration Server. The C++ shared libraries, also part of the Runtime Package,

• CORBA Adapter jar• Integration Server jar• C++ shared libraries• scripts• compliancy tools

NNadkrt

NNorbix NNjre NNjboss NNNNnspcmnNNnspcore

• header files• documentation• sample DA source

NNadkdev

DA

developed with

deployed with

Development Package

Runtime Package

FrameworkSoftware Packages


NNadkrt



NNadkdev

DA

developed with

deployed with

Development Package

Runtime Package


NNadkrt


NNadkrt



NNadkdev


NNadkdev

DA

developed with

deployed with

Development Package

Runtime Package

FrameworkSoftware Packages





include the C++ API of ADK. The Runtime Package is dependent on a number of software packages that are part of Framework. These are shown at the bottom of Figure 2-2.

Assigning domains in a multi-DA environment

To associate ADK components running in a multi-DA environment, they are assigned a domain and a sub-domain. A domain is an arbitrary string that is unique within the scope of a multi-DA environment. To create a domain, we need to create a server instance for the ADK CORBA Adapter (CA) within Application Management, and assign it a unique domain (for north bound identification) say “cal”, and a unique sub-domain (for south bound association with the Device Adapter) say "dal".

Note: You cannot change the domain for the duration of this DA instance existence.

Given the Device Adapter the domain “dal” will associate it with the previously created CORBA Adapter. The CORBA Adapter assigned domain “cal” is used to associate the CA with the Framework BBs and the compliancy tools.

Replacing Device Adapters

See “Replacing Device Adapters” on page 64.


Configuring multiple sub-domains




This is an extended feature that allows ADK to support multiple sub-domains within a single CORBA Adapter (CA) domain. In contrast to the previous multi-DA configuration where you would have had to create a CA server for every DA running on the system, this configuration allows you to combine several DAs under one CA domain.

Figure 2-3 shows the multi sub-domain configuration.





Figure 2-3 Multiple sub-domain configuration

CA—CORBA AdapterMS —Model ServiceDA—Device AdapterBB—Building Block

MS 1 MS 2

CA 3CA 2CA 1

Building Blocks

MS 3

DA 4DA 2DA 1

DA 3





Configuration When ADK starts, the Model Service (MS) looks for the following configuration file:

/opt/nortel/config/adapters/adk/

registery.xml

If it doesn't exist, a default one will be created. This file is used to tell the MS the number of expected sub-domains for every CA/MS domain.

Sample configuration file

Following is a sample XML configuration file.

<?xml version="1.0" encoding="utf-8" ?><adapterlist> <modelQueue name="MS2"> <msgType name="da" value="2"> </msgType> </modelQueue> <modelQueue name="MS1"> <msgType name="da" value="1"> </msgType> </modelQueue></adapterlist>

In the previous sample XML file, there are two tags for the Model Service, called modelQueue name. They are MS2 and MS1.

The value that is associated with the tag msgType name="da" informs the Model Service of the number of sub-domains expected. For example, the MS domain MS2 has a value of 2 (value="2"), meaning that two adapters are attached to this domain, while the MS domain MS1 has a value of 1. The default value, if not explicitly set, is one DA per MS.





Changing the number of sub-domains

If the number of sub-domains needs to change, you must update the XML file manually and restart the Model Service. Do not update this file while the MS is up and running because the MS is continuously updating this file to reflect connected Adapters.

Synchronization with multiple sub-domains

In this multiple sub-domain configuration, the CA domain will not be synchronized until all individual sub-domains are synchronized. If one DA becomes unsynchronized or disconnected, the CA domain will not be synchronized.

Each sub-domain is identified by the DA name and the assigned instance number from Application Management (AM). For example, MyDA12345.

Replacing Device Adapters

If a MS domain has one sub-domain, the corresponding DA can be replaced by shutting down the DA, and starting a new DA under the same MS domain. The new DA will replace the previous DA in the MS cache, specifically, the MS cache will be marked as belonging to the new DA, and the same resynchronization rules apply.

In a multiple sub-domain configuration, DAs cannot be replaced while the MS is up and running.





Assigning Model Service domains

You must assign DA MS domains when creating server instances in Application Management. You cannot change the domain for the duration of this DA instance existence. This rule applies to either configuration, single or multiple sub-domain.


Upgrading ADK



Upgrading ADK The process for upgrading ADK is the same as installing ADK and uses the same installation script default_adk_install.sh

ADK directory structure, using a fixed path and a symbolic link to the current version (that is current_adk -> adk_r4.3.0), simplifies installation, configuration and provides a cleaner upgrade path.

When an upgrade installation is performed, the current ADK installation will not be removed or altered, and the new installation will branch off under the new version number.

What will be done:·

■ Currently running ADK processes are halted.·

■ The new release will be installed in the same location under the new release number (i.e. …/adk/adk_r4.3.0)·

■ The symbolic link current_adk will point to the new subdirectory (that is, current_adk ->adk_r4.3.0)

■ Any AM application needed will be done.·

■ The inittab entries are updated if needed and the new processes are invoked.

This procedure ensures the continuous existence of prior releases of ADK for overlapped periods.


Upgrading ADK



Release-specific upgrade issues

For any issues relating to installation or upgrades for specific releases, see the List of Operational Considerations document for the applicable Framework release.


Uninstalling ADK



Uninstalling ADK

To uninstall ADK (development, runtime, or both), invoke the following Framework uninstall script:


current_NSPcommon/bin/uninstall.sh

To remove the development package, select the following:

■ MIP 5.0.0

■ Current

■ NNadkdev(4.4)

To remove the run-time package, select the following:

■ MIP 5.0.0

■ Current

■ NNadkrt(4.4)

During installation of the ADK packages, the system maintains a record of the installed components and will remove only these components at the package removal time.

For this reason, any development under the ADK should not modify ADK files, but rather modify a copy of these files. (Referring to the sample make file, and sample device adapter)


Developmen


3

Development tasks

This chapter provides an overview of the tasks required to develop a Device Adapter using the ADK, so that you can plan your project effectively.

The supported functionalities are listed and the components that must be developed are described.

There are, at most, three development tasks that you must perform to create a Device Adapter that will draw data from the type of NE or EMS that you are integrating and present it in a format that is usable by a Framework-based Management Solution (FMS). Those three tasks are described in the following sections.

■ New NE Types

■ Develop an NE-specific Device Adapter

■ Develop a Model Conversion File

t tasks 69

New NE Types



New NE Types The process for integrating a new NE type has been changed and simplified. Solution partners fill out a request form for a new NE type and the request is processed by the Managment Technology team.

Integration of the NE type is performed dynamically. The MIP software does not need to be compiled after deployment in order to support a new NE type. Instead, the configuration file must be updated and TUMSBB must then be re-started.

Full details of the NE integration process, including access to the online New NE Type Request form may be found at the following website:

http://knowledgeonline.ca.nortel.com/sws/livelink.exe/fetch/2000/560690/653635/2539378/Welcome.htm?nodeid=2576459&vernum=0

Development tasks 70

Develop an NE-specific Device Adapter



Develop an NE-specific Device Adapter

This involves implementing plugin code between the runtime components included in the ADK that handle upwards communications to the appropriate Framework components and the specific type of NE you are integrating. The following list indicates which development tasks are required to create an NE-specific Device Adapter and refers you to the chapters in this manual where these tasks are discussed in detail.

1. Developing the basic Device Adapter, covers:

■ specialization of the adapter factory classes, which create instances of the specialized Adapter plugin

■ specialization of the initialization and configuration methods, which manage the initial startup of the Adapter process and any configuration changes that are made by a user in Application Manager client.

2. Developing resource and alarm capabilities, covers:

■ specialization of the Start() method, including:

■ performing initial resource discovery■ performing initial alarm discovery■ developing an event loop that handles

resource and alarm event reporting

■ specialization of the HandleAlarmClearRequest() method HandleAlarmAckRequest() method


Develop a Model Conversion File



Develop a Model Conversion File

This involves creating a text file that maps the conversion of the object model used by the NE you are integrating to the object model used by a Framework-based Management Solution, which is covered in chapter, Developing a Model Conversion File.


Developing


4

Developing the basic Device Adapter

This chapter guides you through the steps that are required to develop the basic structure of a Device Adapter (DA). Specifically, this chapter describes the development of the initialization and configuration functions of the DA process, it briefly mentions the starting up of network data reporting, and it describes the development of the functions that stop the reporting and shut down the DA process.

The details of initial network data discovery, ongoing event-based reporting, and request handling functions for resource and alarm management capabilities are covered in Developing resource and alarm capabilities.

This chapter also covers such general development issues as error handling and exception policy, and logging and tracing.

the basic Device Adapter 73

Overview of Device Adapter basics development




This section first introduces you to the life cycle of the DA process, then describes the classes that must be specialized to provide these basic functions. The lifestyle of the DA process is illustrated in Figure 4-1, and described in the accompanying text.

Developing the basic Device Adapter 74




Figure 4-1 Device Adapter lifestyle message sequence diagram

Note: *Resynchronize() and ResynchronizeStart() in Figure 4-1are part of the DA life cycle only following a JBoss or Model Service (MS) failure.





These steps shown in Figure 4-1 above, are explained in the following paragraphs:

1. User clicks on the Start button in Application Manager GUI while a DA instance is highlighted.

2. Application Manager calls the DA library.

3. DA library calls the init_mdr_factory() method in the DA, which instantiates the specialized MDRAdapterFactory.

4. DA library calls createMDRAdapter() of the specialized MDRAdapterFactory which instantiates the specialized MDRAdapter.

5. DA library calls the Init() method, giving the specialized MDRAdapter object access to command line arguments.

6. DA library calls SetupInitialConfig(), in which you do any one-time plugin initialization and pass alternate DA configuration parameters, with default values, to the Application Manager.

7. DA library calls the Reconfigure() method, which validates the values and implements any configuration parameters set in the Application Manager.

8. User clicks on the Activate button in the Application Manager GUI with the interface of the DA process highlighted.






10. DA library calls the MDRAdapter::Start() method.

11. DA performs initial resource and alarm discovery.

12. DA calls MDRAdapter::StartCB() method before entering an event loop.

13. DA enters an event loop that provides ongoing updates on resource and alarm events. The event loop exits when the Shutdown() method is called. (Implementation of the Start() method is discussed in Developing resource and alarm capabilities.)

14. If a resynchronize condition is met (failure of JBoss or the Model Service), the MDRAdapter::Resynchronize()method is called by the ADK to stop the process of event calls.

15. Once resynchronization is ready to begin, the user adapter implementation calls MDRAdapter::ResynchronizeStart to re-enable the flow of events.

16. User clicks the Deactivate button in the Application Manager GUI with the interface of the DA process highlighted.


18. DA library calls the Shutdown() method, which communicates to the resource and alarm event loop that it must exit, then performs any required cleanup.





19. DA calls the MDRAdapter::EndCB() method to communicate to the DA library that the event loop has exited.

20. User clicks on the Stop button in the Application Manager GUI while the DA instance is highlighted.


22. DA library calls the Shutdown() method. The Shutdown() method communicates to the Start() methods event loops—if they are still running—that they must exit, then performs any required cleanup.

23. DA calls the MDRAdapter::EndCB() method to communicate to the DA library that the event loop has exited.

The development tasks that must be performed to provide the basic functionality of a DA process are described in the list below.

1. Write a global function to create a single instance of the specialized MDRAdapterFactory class

2. Develop a specialization of the MDRAdapterFactory class that creates an instance of the specialized MDRAdapter class.

3. Develop a specialization of the MDRAdapter class that implements lifecycle and message handling methods.





Device Adapter base classes

The base classes used to develop the Device Adapter are shown in the simplified class hierarchy diagram “MDR factory and adapter class diagram” on page 79. Factory classes create the Adapter instances. The Adapters are derived from the MDRAdapter class.

Figure 4-2 MDR factory and adapter class diagram

MDRProcessAdminMDRProcAdminFactory

MDRAdapterFactory<<Singleton>> MDRAdapter<<instantiate>>

MyMDRAdapterFactory MyMDRAdapter





Write a global function to create an MDRAdapterFactory instance

This is a mandatory step in the development of your Device Adapter. The DA library invokes the init_mdr_factory() method, which instantiates a specialized version of the MDRAdapterFactory as shown in the code listing below.

Figure 4-3 Sample code for init_mdr_factory()

This function is called only once during the lifetime of the DA process. Thus, there should be only one instance of the MDRAdapterFactory class retained in memory by the DA process.

void init_mdr_factory() { new MyMDRAdapterFactory(); }





Specialize the MDRAdapterFactory class

This step provides a way for you to create a specialized MDRAdapterFactory object.

1. In the header file, inherit from the MDRAdapterFactory class. In the following example, the subclass is called MyMDRAdapterFactory.

Figure 4-4 Code example for inheriting the MDRAdapterFactory class

2. In the source code file, provide implementation for the createMDRAdapter method.

Figure 4-5 Code example for implementing the createMDRAdapter() method

class MyMDRAdapterFactory: public MDRAdapterFactory { public: MyMDRAdapterFactory() { cout << "MyMDRAdapterFactory constructor" << endl; } ~MyMDRAdapterFactory() { cout << "MyMDRAdapterFactory destructor" << endl; } private: virtual MyMDRAdapterFactory*

MDRAdapter* MyMDRAdapterFactory::createMDRAdapter() { ALG_TRACER(gAlgCLogger_,"MDRAdapter::createMDRAdapter()"); return new MyMDRAdapter(); }





Specialize the MDRAdapter class

The MDRAdapter class offers methods for initialization, configuration, reporting start, reporting stop, resynchronization, and DA process halt operations.

The methods that can be specialized (both mandatory and optional) to provide the initialization and configuration functions are summarized in the following table.

Table 4-1 Specialization of the MDRAdapter base class methods

Method Purpose Specialization

Init() Called by the DA library to provide command line arguments used to start the DA process.

Optional. Provides implementation to parse and process command line options (if any). Can perform any one-time initialization processing.

SetupInitialConfig()

Called by the DA library to retrieve initial configurations that are sent to Application Management.

Mandatory.Provides implementation to return application-specific initial configurations to be sent to Application Management client.

Reconfigure() Called by the DA library when the application is reconfigured by Application Management.

Mandatory. Provides implementation to accept or reject the parameters reconfigured by a user in Application Manager client.

Start() Called by the DA library when a user clicks on the Activate button in AMGUI with the Adapter process interface selected.

Mandatory. Contains resource and alarm discovery and event-based reporting. This is covered in the chapter, “Developing resource and alarm capabilities” on page 105.

Stop() a Called by the DA library when a user clicks on the Deactivate button in AMGUI or clicks on the Stop button in AMGUI when the DA interface is still active.

Mandatory. Provides implementation to suspend the reporting of events. The Stop() method must send a signal to the Start() method to halt reporting.





Adapter instance global variable

Normally, when an instance of a class is created, it has an implicit “this” pointer to the methods of the parent class, and the pointer is used to invoke those methods. However, because the Adapter instance, and the methods it spawns, each run in their own thread, the implicit “this” pointer is not passed between threads. Therefore, you must provide a global variable to remember the created instance.

Shutdown() Called by the DA library when a user clicks on the Stop button in AMGUI.

Mandatory. Provides implementation for the work to be done (such as cleanup) when terminating the process. The method must send a signal to the Start() method to halt reporting.

Resynchronize() Called when the ADK Library detects a resynchronization condition (failure of JBoss or Model Service).

Optional. Provides implementation to resynchronize the network Model used by the ADK.

a.The Stop() method is used only with DAs developed prior to release 4.1 of ADK. DAs developed using ADK 4.1 use shutdown() to initiate the stop process

Table 4-1 Specialization of the MDRAdapter base class methods (Continued)






Implement the constructor

See Figure 4-6 below for an example of the implementation of the MDRAdapter constructor.

Figure 4-6 Code example for implementing the MDRAdapter constructor

Specialize Init() Specialization of the Init() method is optional. Init() gives you access to the command line arguments for the DA process, which are typically specified in the launch script used to start the DA from Application Management. Also, Init() can perform any one time initialization processing.

An example of the implementation of Init() is shown in Figure 4-7, below.

Figure 4-7 Sample code for specializing Init()

MyMDRAdapter::MyMDRAdapter() {

myAdapter_ = this; // initialize stop_ and shutdown_ stop_ = FALSE; shutdown_ = FALSE; }

void MyMDRAdapter::Init( int argc, char * argv[]) { for( int i = 0; i < argc ; i++) cout << "argv[" << i << "] is: " << argv[i] << endl; }





The parameters for Init() are as follows:

■ the first parameter is an integer indicating the number of arguments

■ the second parameter is an array of the arguments

For more information, see the ADK API Reference coverage of:

■ MDRProcessAdmin::Init()

■ MDRAdapter::Init()


./c++_api/class_mdrprocessadmin.html#a6

./c++_api/class_mdradapter.html#a17




Specialize SetupInitialConfig()

Specialization of the SetupInitialConfig() method is mandatory. It provides all available configuration attributes and values for the DA process to Application Management. You need to specialize it if the DA uses unique initial, or configurable, parameters. This method is called only once. A default implementation is supplied for SetupInitialConfig().

Pass the configuration attributes to Application Management in an AdapterConfig instance. For each configurable attribute, call the appropriate overloaded AdapterConfig::AddAttribute() method, specifying:

■ the attribute name

■ a value of int or string

■ whether it is read-only or user-configurable

When you add an attribute like this, it appears in the list of configurable attributes in the Application Management GUI, where the user can select the preferred configuration. See the code example in Figure 4-8 on page 87.





Figure 4-8 Code example for specializing SetupInitialConfig()


■ MDRProcessAdmin::SetupInitialConfig()

■ MDRAdapter::SetupInitialConfig()

■ AdapterConfig

void MyMDRAdapter::SetupInitialConfig(AdapterConfig& myConfig) { try { // Let user see the NE and alarm file names in AM GUIS myConfig.AddAttribute(myEMS_->GetNEListFileAttributeName(), myEMS_->GetNEListFileName(),TRUE); myConfig.AddAttribute(myEMS_->GetTL1AlarmListFileAttributeName(), myEMS_->GetTL1AlarmListFileName(),TRUE); myConfig.AddAttribute(myEMS_->GetActiveAlarmListFileAttributeName(), myEMS_->GetActiveAlarmListFileName(),TRUE); myConfig.AddAttribute(myEMS_->GetNumberOfUIAttributeName(), myEMS_->GetNumberOfUI(),FALSE); myConfig.AddAttribute(myEMS_->GetPortNumberAttributeName(), myEMS_->GetPort(),FALSE); } catch(...) { cout << “error” << endl; exit(1); } }





./c++_api/class_adapterconfig.html




Specialize Reconfigure()

Specialization of the Reconfigure() method is mandatory. It is called when a user changes the DA process configuration in AMGUI. The updated attributes are passed to Reconfigure() in an AdapterConfig object. You must provide an implementation of Reconfigure() that validates the attributes passed to it.

The behavior you must implement is as follows.

1. Call AdapterConfig::GetNumberOfAttributes().

2. For each attribute, read the attribute by calling either AdapterConfig::GetStringAttributeValue() or AdapterConfig::GetIntAttributeValue().

3. Determine if the value is correct, and set the return code for the parameter by calling AdapterConfig::SetReturnValue(). If the value was incorrect, reset it to the default value.

4. If all the attributes are correct, return TRUE, otherwise return FALSE. If a change is made to the element controller ID (EC_ID change), the DA must be stopped and re-started for the change to take effect.





See the code example in Figure 4-9 on page 90. For more information, see the ADK API Reference coverage of:

■ AdapterProcessAdmin::Reconfigure()

■ MDRAdapter::Reconfigure()

■ AdapterConfig.




./c++_api/class_adapterconfig.html




Figure 4-9 Code example for specializing Reconfigure()

RWBoolean MyMDRAdapter::Reconfigure(AdapterConfig& myConfig) { RWBoolean error = FALSE; try {

// Check the attributes received from AM if (myConfig.GetStringAttributeValue(

myEMS_->GetNEListFileAttributeName()) == myEMS_->GetNEListFileName())

{ // Inform AM of the correctness of the attribute’s value myConfig.SetReturnValue(myEMS_->GetNEListFileAttributeName(),

myEMS_->GetNEListFileName()); } else { // Set error flag. error = TRUE; // Inform AM of the incorrectness of the attribute value myConfig.SetReturnValue(myEMS_->GetNEListFileAttributeName(),

myEMS_->GetNEListFileName(), ADAPTER_FAILURE, ADAPTER_FAILUREWITHMESSAGE “NE list file name does not match.”);

} ... // Check the other attributes here. ... return (error); } // Catch any exceptions catch (...) { cerr << “Problem with config stuff” << endl; exit(1); } }





Using GetConfig() The GetConfig() method is used to access configuration information set in AMGUI from inside the Start() method.

For more information, see the ADK API Reference coverage of GetConfig().

Specialize Start() The majority of your development is specializing the Start() method. Initial discovery and ongoing updates discovered in an event loop are developed within the Start() methods for resource and alarm management capabilities, respectively. These functionalities, however, are covered in other chapters. (See “Developing resource and alarm capabilities” on page 105).

These methods are mentioned here only to provide a complete view of the basic behavior of the DA. In the Start() method, you must develop the following behavior.

■ establish connections to the NEs or EMSs

■ perform initial discovery

■ call StartCB() to signal that the plugin is entering the event loop

■ develop a loop that discovers new network events and responds to the Shutdown() method.






Specialize Stop() Note: This method is used only with DAs developed prior to release 4.1 of ADK. DAs developed using ADK 4.1 use shutdown() to initiate the stop process.

Specialization of the Stop() method is mandatory (if the Start() method was used). Stop() is called by the DA library to stop event reporting (in response to a user clicking on the Deactivate button in AMGUI for the highlighted interface). As these functions run in a different thread from the Start() method, a way must be developed for these methods to communicate. One possible implementation, which is described throughout this manual, is to define boolean variables that will indicate when these methods have been called and have the Start() method check these variables as part of their event loops. When the Start() method is called, the value of the stop_ variable must be set to TRUE. This is detected when the event loop checks the value of stop_ , depending on whether the loop is in the Start() method (see “Check for shutdown calls” on page 137). When a value of TRUE for stop_ is detected, the appropriate event loop exits.

As the last step in the stop sequence, you must call EndCB() to inform the DA library that the event loop has been stopped. The implementation of one of these scenarios is shown in Figure 4-10, below.





Figure 4-10 Code example for specializing Stop()


■ MDRAdapter::Start()

■ MDRAdapter::EndCB()

Specialize Shutdown()

Note: For DAs developed using ADK 4.x, this is the only method used to initiate the stop process.

Specialization of the Shutdown() method is mandatory. It is called by the DA library in response to a user clicking on the Stop button in AMGUI. As the Shutdown() method runs in a different thread from the Start() method, a way must be developed for these methods to communicate.

One possible implementation, which is described throughout this manual, is to define a boolean variable that will indicate when the Shutdown() method has been called and have the Start() method check this variable as part of their event loops. When the Shutdown() method is called, the value of the shutdown_ variable must be set to TRUE. When the

void MyMDRAdapter::Stop() { // Inform main event loop to stop stop_ = TRUE; EndCB(); }







Start() method detects that the value of the shutdown_ variable is set to TRUE, they perform any required cleanup and exit their event loops (see “Check for shutdown calls” on page 137).

The Shutdown() method is responsible for cleaning up all resources allocated by the plugin. As the last step in the shutdown sequence, you must call EndCB() to inform the Adapter libraries that the plugin shutdown sequence has ended.

Figure 4-11 Code example for Shutdown()


■ MDRAdapter::Shutdown()


■ MDRAdapter::EndCB()

void MyMDRAdapter::Shutdown() { // Inform main event loop to shut down. shutdown_ = TRUE; EndCB(); }








Specialize Resynchronize()

Although specialization of Resynchronize() is optional, it is strongly recommended.

Resynchronize() is called when the ADK library detects a resynchronization condition (failure of JBoss or Model Service). When either of these conditions is met, the network state (resources and alarms) must be resynchronized with the Model to provide an accurate view of the network.

The default behavior of this method (if you choose not to specialize it) is to call exit().

The implementation of Resynchronize() is dependent on the particulars of your DA. Generally, you are required to:

1. Perform clean-up action, if necessary.

2. Acquire the current state of the network (resources).

3. Call ResynchronizeStart() when you are ready to propagate the complete state of the network.

4. Send resource and alarm events.

5. Call PushDomainSynchronized() (see Figure 5-3 on page 111 for an overall view of the resynchronization lifecycle).





Library behavior during loss of connection to Model Service

It is important to note the behavior of ADK libraries during the absence of a Model Service (MS) connection (when MS or Jboss is down). If the DA is starting, it will block until it establishes a connection and registers successfully with the MS. From then onward, if the MS connection is interrupted, every DA attempt to send an event to the MS fails after a 30 seconds time-out. Eventually, the DA will receive a resynchronize() callback notification, if implemented in the DA, once the connection with the MS is re-established.





Providing Automatic Restart

In ADK 4.x, a plug-in adapter is not restarted automatically by FrameWork (Orbix daemon). You should plan to have a restart mechanism in place in case of abnormal termination.

For example, AM provides a facility, the restarter, to enable automatic restarting of processes, including DAs. It will watch-dog a group of processes that share the same CORBA name prefix. The restarter can be configured into inittab with the following command:

/opt/nortel/PresideNSP/current_NSPcommon/bin/restarter.sh <corbaprefix>

Example:

/opt/nortel/PresideNSP/current_NSPcommon/bin/restarter.sh vecMDRAdapter





Adding capabilities to your plugin

This concludes the coverage of basic structure development of a Device Adapter. If you have performed the tasks documented in this chapter, your plugin still does not have any useful capabilities in terms of retrieving network data for the ADK clients or handling requests from those clients. Those capabilities, whether for resource or alarm management support, are covered in “Developing resource and alarm capabilities” on page 105.

The remainder of this chapter discusses general development issues, such as error handling and exception policy, and logging and tracing.


General development considerations




This final part of this chapter discusses policies and approaches that should be followed throughout the development of the Device Adapter. It includes discussions of:

■ Required attributes

■ Error handling and exception policy

■ Logging and tracing

Note: An additional general development issue is allocation policy, which is documented in the Appendix, “Allocation policy” on page 183.





Required attributes The following network element attributes are required by ADK:

■ objectId

■ eventTime

■ neName

■ neType

■ adminState

■ operationalState

■ unknownStatus

The following alarm attributes are required by ADK:

■ objectId

■ eventTime

■ notificationId

■ alarmType

■ alarmSeverity

■ probableCause





Error handling and exception policy

To preserve performance, only the following minimal checking is performed.

■ Argument out of range

■ Missing or incorrect attributes

These are discussed in the paragraphs that follow.

Argument out of range

For the set methods of the helper classes (such as setEventTime), an moafw_invalid_argument exception, modeled on the ANSI C++ standard invalid_argument exception, will be thrown if the argument is out of range. This exception will contain a character string with the name of the attribute followed by a colon “:” followed by the offending value, for example, “EventTime:19980420142233Y”.

You can retrieve this character string by calling the standard what() method. If the allocator helper class was allocated on the heap, you must ensure that it is correctly deallocated (that is, by using an auto_ptr). For an example, refer to Figure 4-12 on page 102.

Note: An auto_ptr supports the “resource acquisition is initialization” technique and is a smart pointer that is automatically initialized and automatically deleted when an exception is received to prevent the common mistake of not properly





initializing a ptr and deleting it. Please refer to The C++ Programming Language, 3rd edition, Stroustrup, Section 14.4.2, Auto_ptr, for a complete explanation.

Figure 4-12 Code example for retrieving an invalid argument exception string

Missing or incorrect attributes

For the push methods of the MDRAdapter class (such as pushAlarm), if one or more of the mandatory attributes of the AdapterAlarm, AdapterNeEnrol, etc. classes is missing or set incorrectly, then the moafw_invalid_argument exception will be thrown and the name of the first missing or incorrect attribute

try { myEnrol->setObjectId(myObjectId); myEnrol->setEventTime(“19981030000001Z”); myEnrol->setNeName(“Freds_NE”); myEnrol->setIPAddress(“47.13.14.15”); myEnrol->setEmlIPAddress(“47.13.14.14”); myEnrol->setVersion(“1”); myEnrol->setUnknownStatus((RWBoolean)TRUE); myEnrol->setOperationalState(1); // 1=enabled ... // etc } catch (invalid_argument& invalid_arg) { cout << “Bad Argument Value passed “ << invalid_arg.what() << endl; // Do something! }





will be stored within the exception. It can be retrieved by calling what(). See the lists of mandatory NE and alarm attributes in “Required attributes” on page 100.

Logging and tracing We recommend that Device Adapter developers log raw messages received from an NE/EMS as a matter of course, as this is helpful in trouble-shooting at a customer site.

At a medium log level, a DA should, as a minimum, log the following:

■ MAC and ACK request received

■ push LOA()

■ LOA to EMS/NEs

At the debug level, the DA should also log the following:

■ object sent upward NE and alarms

A global instance of the ALG logging object, gAlgCLogger_, can be allocated. You call methods on this global logging object instance in order to generate plugin-specific log and trace messages.

The file containing the logging and tracing information is saved to the same file, located in /opt/nortel/log/adapters/adk/logs with the filename:

<executable_name> <unique_identifier_from_AM_GUI>.log


Synchronization



For example: myadapter083792.log

For more information, see the ADK API Reference coverage of the Logging and Tracing Macros.

Synchronization Synchronization is the term used to describe the work that FMBB executes to ensure that its alarm information is correct, complete and fully aligned with the alarm information in its subtending device adapters (DAs).

For details of the synchronization process, please refer to the FMBB chapter of the NSP Developer’s Guide.


./c++_api/logutil_hxx.html

./c++_api/logutil_hxx.html

Developing


5

Developing resource and alarm capabilities

This chapter describes the steps required to add resource and alarm management support to your Device Adapter (DA).

Note: The tasks described in “Developing the basic Device Adapter” on page 73 are pre-requisites for the tasks described in this chapter.

Note: See the Sample Device Adapter for a simplified reference implementation of Device Adapter.

resource and alarm capabilities 105

Overview of developing resource and alarm capabilities




To develop resource and alarm capabilities you must perform the following tasks:

■ Develop a way for Shutdown() to communicate with Start()

■ Specialize the Start() method

■ Establish communications with the NE/EMS

■ Perform initial NE discovery

■ Add vendor-specific information, including:

■ Adding support for Easy.ON support bits

■ Adding support for Easy.ON support bits

■ Perform initial alarm discovery

■ Call StartCB() to signal to the DA library that the DA is entering the event loop

■ Develop the event loop

■ Handle NE events■ Handle alarm events■ Handle OSI state changes■ Handle NE attribute changes■ Fault/Resource Synchronization scenarios■ Check for shutdown calls

■ Develop special alarm handling

■ Handle manual alarm clear requests■ Handle alarm acknowledge request■ Handle service grade alarms

Developing resource and alarm capabilities 106




The methods that are used, including the relevant helper classes are shown in the figure “Simplified resource and alarm class diagram” on page 108. The method of the MDRAdapter class that must be specialized is shown in Table 5-1 on page 109. The interactions between the DA library, the DA, and the NE or EMS are shown in Figure 5-2 on page 110. Following this information, each of the resource and alarm enabling development tasks listed above is explained in the sections of this chapter.





Figure 5-1 Simplified resource and alarm class diagram

MDRAdapter

Init()SetupInitialConfig()GetConfig()Reconfigure()Start()StartCB()Stop()Shutdown()EndCB()PushEnrol()PushAlarm()PushDeEnrol()PushNEUnknownStatus()Resynchronize()ResynchronizeStart()PushOsiStateEvent()PushEMSAssociationLost()PushAttributeValueEvent()HandleAlarmClearRequest()HandleAlarmAckRequest()

MyMDRAdapter

AdapterNeEnrol(from Model Binding Classes)

AdapterNeDeEnrol(from Model Binding Classes)

AdapterAlarm(from Model Binding Classes)

AdapterOsiStateEvent(from Model Binding Classes)

AdapterAttributeValue

(from Model Binding Classes)Event





Figure 5-2 on page 110 shows the basic resource and alarm management behavior of the DA. The lifecycle of a resynchronization activity following the failure of JBoss or the Model Service is shown in Figure 5-3 on page 111. Additional interaction diagrams show the details of some of the optional resource and alarm features, such as:

■ Handling lost and restored association

■ Handling manual alarm clear requests

Table 5-1 Required specialization for resource and alarm management capabilities


Start() Called by the DA library in a new thread. Start() handles initial NE and alarm discovery, and then processes NE events and faults in an event loop.

Provides implementation for initial NE discovery, and the NE event and fault management loop.

HandleAlarm ClearRequest()

Called by the DA library in response to a manual alarm clear request, if the NE/EMS needs to be notified of the clear request and consequently has to handle the request.

Mandatory only if NE/EMS involvement is required for manual alarm clear requests. Provides implementation to handle the alarm clear request according to the needs of the NE/EMS.

HandleAlarmAck Request()

Called by the DA library in response to an alarm acknowledgement, if the NE/EMS needs to be notified of the request and consequently has to handle the request.

Mandatory only if NE/EMS involvement is required for the alarm acknowledgement. Provides implementation to handle the alarm acknowledgement request according to the needs of the NE/EMS.





Figure 5-2 Basic resource and alarm interactions diagram





Figure 5-3 Resynchronization diagram (following failure of JBoss or Model Service)

Resynchronize()

Clean up and prepareto resynchronize

(ready to resynchronize)ResynchronizeStart()

Retrieve NE data

NE data from network

PushEnrol()

PushDeEnrol()

Alarm messages from network

PushNeUnknownStatus()

PushDomainSynchronized()

Adapter Libraries Adapter plugin NE/EMS

PushAlarm()


Develop a way for Shutdown() to communicate with Start()



Develop a way for Shutdown() to communicate with Start()

The Start() method and the Shutdown() methods are called from different threads, so thread synchronization is needed for the Shutdown() method to notify the event loop in the Start() method to exit.

One possible mechanism you could use, as is a global variable, as shown in Figure 5-4, below.

Figure 5-4 Code example for declaring a global variable

Alternatively, you could use either shared memory or messaging between the Start() and Shutdown() methods.

// Initialize class variables RWBoolean MyMDRAdapter::stop_ = FALSE; RWBoolean MyMDRAdapter::shutdown_ = FALSE;


Specialize the Start() method



Specialize the Start() method

Specialization of the Start() method is mandatory. It starts the DA process in a new thread when a user clicks on the Activate button in AMGUI. As users may Deactivate and then Activate the DA process again, the Start() method may be called more than once.

The Start() method does the following:

1. Establishes connections to the NE or EMS.

2. Performs initial NE discovery.

3. Performs initial alarms discovery.

4. Calls StartCB() to inform the DA library that the plugin’s resource and alarm event loop is starting.

5. Starts the main event loop.

For more information, see the ADK API Reference:


■ MDRAdapter::StartCB()

Note: For an example of specializing the Start() Method, please refer to the SampleDeviceAdapter (adk*/resources/src/plugin/SampleMDRAdapter.cxx)




Establish communications with the NE/EMS



Establish communications with the NE/EMS

At this point in the code it is necessary to establish communications with the network elements or element management systems from which the DA gathers its data. However, explaining how this is done, or providing code examples, is beyond the scope of the ADK and of this document. It is your responsibility to develop this functionality at this point in the code.


Perform initial NE discovery



Perform initial NE discovery

Performing initial NE discovery requires that you call each EMS to discover all the NEs, or call the NEs directly if no EMS is involved, and that you perform the following steps once for each NE discovered.

1. Allocate an AdapterNeEnrol instance.

2. Fill in the AdapterNeEnrol object by calling the appropriate set method.

Note: For detailed information on how to set those values, refer to the AdapterNeEnrol class in the ADK API Reference.

3. Push the AdapterNeEnrol object up to the DA library by calling PushEnrol().

4. Deallocate the AdapterNeEnrol object.


■ AdapterNeEnrol

■ MDRAdapter::PushNEUnknownStatus()

■ MDRAdapter::PushEnrol()

■ SupportBitConstants.hxx


./c++_api/class_adapterneenrol.html





./c++_api/SupportBitConstants.hxx

Add vendor-specific information




The ADK provides methods AdapterNeEnrol::addAddedVendorSpecificIn

fo() and AdapterAlarm::addAddedVendorSpecificInfo

() that allow users to add vendor-specific NE/alarm information. The ADK also uses that information to handle specific needs for various features. For example:

■ manual alarm clears. See “Develop special alarm handling” on page 138

■ customer-specified NE IDs. See “Adding support for Easy.ON support bits” on page 117

■ Easy Optical Network (Easy.ON) support bits. See “Adding support for Easy.ON support bits” on page 117





Adding support for Easy.ON support bits

Easy.ON support bits allow the NE to notify NSP about which functionalities it can support. This allows NEs to be handled according to their specific needs. New Optical NEs can send different support bits to the Platform, depending on which version they connect to. An Easy.ON support bit is added through the “addAddedVendorSpecificInfo” method of the “AdaptorNeEnrol” class.

The ability for NEs to turn on and off NSP functionality allows:

■ an older NE to tell NSP which new NSP feature it does not support

■ a newer NE to tell NSP when a new NE feature would disable an existing NSP feature





Table 5-2 Support Bits Constraints

Bit #

XDR Definition

Characteristics when “ON”

Characteristics when

“OFF”

Basic

Comments/ Exceptions

1 XDR_NE_SUPPORT_PROTECTION

Auto-discovered links will appear.

Auto-discovered links will not appear.

No Enables traffic display.

2 XDR_NE_SUPPORT_SHELF_VIEW

When enabled, a double click will open a rlogin session for the NE. However, a special script is executed for this case. It is not the normal rlogin pathway. Right click display a menu which says “Open..”

Normal nodal dialog. Yes

This is not normally set with the OPC. When supported NEs are added to the GNE, the user can launch the remote graphical shelf view session for the NE.

3 XDR_NE_SUPPORT_DIRECT_NE_LOGIN

Login to NE menu entries appear black (enabled)

Login to NE menu entries appear gray (disabled)

Yes Used by OPC based products. Should be part of basic support.

4 XDR_NE_SUPPORT_PM

“Query Performance Statistics” item within the “Performance” menu of gnbrowse appears black (enabled)

“Query Performance Statistics” item within the “Performance” menu of gnbrowse appears gray (disabled)

No

5 XDR_NE_SUPPORT_INVENTORY

“Query Equipment Inventory” item within the “Configuration” menu appears black (enabled).

“Query Equipment Inventory” item within the “Configuration” menu appears gray (disabled).

No

When “ON” bit #12 should be “ON”. This needs NE bit #6 to be enabled as well.





Table 5.2 continued...

Bit #

XDR Definition



“OFF” Basic Comments/

Exceptions

6 XDR_NE_SUPPORT_SLG

“Shelf View” item within the “Configuration” and nodal menus of gnbrowse appear black (enabled).

“Shelf View” item within the “Configuration” and nodal menus of gnbrowse appear gray (disabled).

No When “ON” bit #12 should be “ON”.

7 XDR_NE_SUPPORT_X_SESSION

Enables x session for network elements. Not used by OPC based products.

Disables x session for network elements. Not used by OPC based products.

Yes Basic login for non-OPC products

8 XDR_NE_SUPPORT_CMT_SESSION

Enables character session for network elements. Not used by OPC based products.

Disables character session for network elements. Not used by OPC based products.


9 XDR_NE_SUPPORT_CONNECTION_MGMT

“Show Connections” item within the “Configuration”, link and nodal menus of gnbrowse appear black (enabled).

“Show Connections” item within the “Configuration”, link and nodal menus of gnbrowse appear gray (disabled).

No

10 XDR_NE_SUPPORT_INA_DATA No

Not used within the context of the gnbrowse/gnconfig.






Bit #

XDR Definition




Exceptions

11 XDR_NE_SUPPORT_FACILITY_PROVISIONING

“Show Facilities” item within the “Configuration” and nodal menus of gnbrowse appear black (enabled).

“Show Facilities” item within the “Configuration” and nodal menus of gnbrowse appear gray (disabled).

No

The XDR_MOPC_SUPPORT_FACILITY_PROVISIONING must be “ON” as well to enable facility provisioning.

12

XDR_NE_SUPPORT_CASE_INSENSITIVE_INVENTORY_FILTER

Used within remote inventory.

Used within remote inventory.

No

Used within remote inventory. Should be “ON” if bit #5 or #6 is “ON”.

13 XDR_NE_SUPPORT_PROTECTION_CONTROL

The PSC dialog will open allowing switch commands to be sent to the OPC.

The PSC dialog will open in a read-only mode where switch commands are not allowed (i.e. the combo boxes are disabled).

No

Since this is launched from the link menu, Bit #1 must be “ON” to discover the links before this can be launched.

14 XDR_NE_SUPPORT_PM_THRESHOLD

“Show PM Thresholds” item within the “Performance” menu of gnbrowse appears black (enabled).

“Show PM Thresholds” item within the “Performance” menu of gnbrowse appears gray (disabled).

No

This bit is also used by PM Threshold Templates. If this bit is OFF, it will disable PMTT for the corresponding NE type.

15 XDR_SNC_SUPPORT_X_SESSION

Enables x session for network elements. Not used by OPC based products.

Disables x session for network elements. Not used by OPC based products.







Bit #

XDR Definition




Exceptions

16 XDR_SNC_SUPPORT_CMT_SESSION

Enables character session for network elements. Not used by OPC based products.

Disables character session for network elements. Not used by OPC based products.


17 XDR_NE_SUPPORT_WEB_UI

Enables Web UI support.

Disables Web UI support.

18 XDR_NE_SUPPORT_ADAPTER

No Non-OPC based.

19 XDR_NE_SUPPORT_UE9K

Enables UE9000 support.

Disables UE9000 support.

No

20 XDR_NE_SUPPORT_TROUBLE_TICKETING

No This bit is not

used.

21 XDR_NE_SUPPORT_ALARM_STATE

Enables alarm state.

Disables alarm state. No

non-OPC based network elements.

22 XDR_NE_SUPPORT_MANUAL_CLEAR

Enables alarm manual clear

Disables alarm manual clear

No non-OPC based network elements.

23 XDR_NE_SUPPORT_UE9R

Enables UE9000 support.

Disables UE9000 support.

No






Bit #

XDR Definition




Exceptions

24 XDR_NE_SUPPORT_OSV

“Refresh Optical Link” item within the link menu of gnbrowse appears black (enabled). Once it has been selected, “Show Optical Section View” item within the link menu of gnbrowse appears black (enabled). A little prism will appear on the link, indicating that there are optical components that have been added to the TM database.

“Refresh Optical Link” item within the link menu of gnbrowse appears gray (disabled). “Show Optical Section View” item within the link menu of gnbrowse appears gray (disabled).

No

If any NE that owns a component along the optical link has the support bit disabled, the user will not be able to launch OSV.

25 XDR_NE_SUPPORT_OPM

Power management menu items within OSV appear black (enabled)

Power management menu items within OSV appear gray (disabled)

No

Since this application is launched within OSV, OSV must be enabled to run this.

26 XDR_NE_SUPPORT_RMINV_CI

Allows request for the inventory i/f of RMBB.

Disallows requests for the inventory i/f of RMBB. (exception is thrown)

No Applicable as of XDR major version 14 only.

27 XDR_NE_SUPPORT_RMTTP_CI

Allows request for the TTP i/f of RMBB.

Disallows requests for the TTP i/f of RMBB. (exception is thrown)







Note: Non-OPC based support bits are grayed out.

For more information, please refer to the EASY.ON Companion Guide at: http://knowledgeonline.ca.nortel.com/preside/frames.html?http://knowledgeonline.ca.nortel.com/sws/livelink?func=ll&objId=836973&objAction=browse&sort=name

Bit #

XDR Definition




Exceptions

28 XDR_NE_SUPPORT_PMSTATS_CI

Allows request for the PM history i/f of PMBB.

Disallows requests for the PM history i/f of PMBB. (exception is thrown)


29 XDR_NE_SUPPORT_PMTTP_CI

Allows request for the TTP i/f of PMBB.

Disallows requests for the TTP i/f of PMBB. (exception is thrown)


30 XDR_NE_SUPPORT_PMT_CI

Allows request for the threshold i/f of PMBB.

Disallows requests for the threshold i/f of PMBB. (exception is thrown)



http://knowledgeonline.ca.nortel.com/preside/frames.html?http://knowledgeonline.ca.nortel.com/sws/livelink?func=ll&objId=836973&objAction=browse&sort=name





■ SupportBitConstants.hxx

■ AdapterNeEnrol::addAddedVendorSpecificInfo

■ AvaType

Note: Please refer to the SampleDeviceAdapter for examples of vendor-specific information. This may be found at:

Note: adk*/src/plugin/SampleMDRAdapter.exx


./c++_api/class_adapterneenrol.html#a20

./c++_api/class_avatype.html

./c++_api/SupportBitConstants.hxx

Perform initial alarm discovery



Perform initial alarm discovery

Performing initial discovery of active alarms is essential to providing a reliable view of the alarms in the Framework-based applications. You perform initial active alarm discovery by calling each NE or EMS to retrieve the current active alarms. For each active alarm that is discovered on each NE with which you have communications you must:

1. Allocate an AdapterAlarm instance.

2. Fill each AdapterAlarm object by calling the appropriate set method.

3. Push each AdapterAlarm object up to the Adapter libraries by calling PushAlarm().

4. Deallocate each AdapterAlarm instance.


■ AdapterAlarm

■ MDRAdapter::PushAlarm()

Additional optional handling of alarms is described in the section “Develop special alarm handling” on page 138.


./c++_api/class_adapteralarm.html



Call StartCB()



Call StartCB() Once the initial discovery of NEs and alarms is done, but before the DA enters the event loop, you must call StartCB() to inform the DA library that the DA is entering the event loop.

For more information, see the ADK API Reference coverage of MDRAdapter::StartCB().



Develop the event loop




This section discusses what you must develop in the event loop of the Start() method. The DA process enters the event loop after initial NE and alarm discover. Your event loop should run continuously, providing updates on resource and alarm data, until it detects calls to the Stop() or Shutdown() methods. Specifically the event loop must do the following:

■ Handle NE events (see “Handle NE events” on page 129)

■ Handle alarm events (see “Handle alarm events” on page 130)

■ Handle OSI state changes (see “Handle OSI state changes” on page 132)

■ Handle NE attribute changes (see “Handle NE attribute changes” on page 133)

■ Handle Fault/Resource Synchronization scenarios (see “Fault/Resource Synchronization scenarios” on page 134)

■ Check for stop and shutdown calls (see “Check for shutdown calls” on page 137)

The events you must recognize, the objects you must define, and the methods of the MDRAdapter class that you must use to push them up to the DA library, are listed in Table 5-3 on page 128.





In the remainder of this chapter, the tasks that must be developed in the event loop are discussed in detail, except for the NE and alarm updates tasks, which are handled in much the same way as initial discovery.

Note: For more information, please refer to the SampleDeviceAdapter.

Table 5-3 Events, objects, and methods in the event loop

Event Object Method

NE added AdapterNeEnrol PushEnrol()

NE deleted AdapterNeDeEnrol PushDeEnrol()

Change in NE operational state AdapterOsiStateEvent PushOsiStateEvent()

Add new attribute(s) or change existing attribute(s)

AdapterAttributeValueEvent

PushAttributeValueEvent()

Lost or restored communications NE object ID (a list of AvaType objects)

PushNEUnknownStatus()

Alarm raised AdapterAlarm PushAlarm()

Alarm cleared AdapterAlarm PushAlarm()





Handle NE events Providing NE event updates is very similar to “Perform initial NE discovery” on page 115. The difference is in handling the removal of NEs from the network, which is described below, and handling a loss of association with an NE or EMS, which is described in “Fault/Resource Synchronization scenarios” on page 134.

You must do the following for each NE that is removed from the network:

1. Allocate an AdapterNeDeEnrol instance.

2. Fill in the AdapterNeDeEnrol object by calling the appropriate set method.

3. Push the AdapterNeDeEnrol object up to the DA library by calling PushDeEnrol().

4. Deallocate the AdapterNeDeEnrol object.


■ AdapterNeDeEnrol


■ MDRAdapter::PushDeEnrol()


./c++_api/class_adapternedeenrol.html







Handle alarm events Providing alarm event updates to the alarm management client applications is very similar to “Perform initial alarm discovery” on page 125.

When an alarm is pushed up from the DA, if the Correlated ID is NOT set and if an alarm already exists with the same NE ID and Notification ID, the internal behavior for the Integration Server is to discard the new alarm as a “babbler” alarm. However, all alarm clears are sent to the Framework-based management solution.

For new alarm events

For each new alarm event, you must do the following:

1. Create an AdapterAlarm object.

2. Fill it with the alarm information.

3. Call pushAlarm() method on the MDRAdapter class.

For alarm clearing events

For each alarm clear event, you must do the following:

1. Create an AdapterAlarm object

2. Fill it with the alarm information. In particular, set the correlated notification Ids for clear alarms using the setCorrelatedIds method to ensure that when





a clear alarm is received in the fault management building block, all correlated set alarms are removed from the active alarm list.

For more information, see the ADK API Reference: AdapterAlarm and “Develop special alarm handling” on page 138.

Event times for alarm events

Table 5-4 defines the following event times: raise, clear, attribute value change, state change.

Table 5-4 Definition of event times

Event time Definition

raise The time the alarm was created, which is usually obtained from the NE or EMS. It is not the time that the system sends the raise. For example, on initial query, the event times of the alarms must be the times the individual alarms are created.

clear The time that the NE cleared the alarm. If there is a manual clear that is being supported by the DA, it is the time that the DA created the manual clear. It is not the clear request time that is passed down to the user.

attribute value change

For the attribute value change to be applied correctly, the event time must be equal to the raise time of the alarm. This includes acknowledgments. The acknowledgment time is carried in a vendor specific attribute.

state change The time of the state change usually obtained from the NE or EMS


./c++_api/class_adapteralarm.html




Handle OSI state changes

You can optionally report OSI state changes, such as changes in the usage state, operational state, or admin state, by doing the following:

1. Allocate an AdapterOsiStateEvent instance.

2. Fill each AdapterOsiStateEvent object by calling the appropriate set method.

3. Register each AdapterOsiStateEvent object with the DA library by calling PushOsiStateEvent().

4. Deallocate each instance.

The code example below illustrates this behavior.

Figure 5-5 Code example for handling OSI state changes


■ AdapterOsiStateEvent

■ MDRAdapter::PushOsiStateEvent()

unsigned long NEId; AdapterOsiStateEvent osiEventObject; RWTPtrSlist<AvaType> dn; AvaType OsiEventAva; osiEventObject.setEventTime(getCurrentTime()); osiEventObject.setOperationalState((TmnOpStateValueEnum) OPER_STATE_ENABLED); osiEventObject.setAdminState((TmnAdmStateValueEnum)ADM_STATE_UNLOCKED); osiEventObject.setUsageState( USAGE_STATE_ACTIVE ); osiEventAva.attributeId.stringId = "EM"; osiEventAva.attributeValue.stringValue = "NE ID name"; dn.insert(&osiEventAva); osiEventObject.setObjectId(dn); myAdapter->PushOsiStateEvent(&osiEventObject);


./c++_api/class_adapterosistateevent.html






Handle NE attribute changes

To change an existing NE attribute or to add new vendor specific information, use either:

■ addNewAdditionalAttribute() for the vendorSpecificInfo or technologySpecificInfo attributes, or

■ addNewAttribute() for all other attributes

See the example code listing below.

Figure 5-6 Code example for handling NE Attribute changes


■ AdapterAttributeValueEvent

■ addNewAdditionalAttribute()

■ addNewAttribute()

■ MDRAdapter::PushAttributeValueEvent()

AdapterAttributeValueEvent *myAVCEvent = new AdapterAttributeValueEvent(); AvaType* vendorAva = new AvaType("manualClearNeedsEMS", TRUE); myAVCEvent->addNewAdditionalAttribute(ntNTDefined AttributeIds_vendorSpecificInfo_C,vendorAva); _myAdapter->PushAttributeValueEvent(myAVCEvent);


./c++_api/class_adapterattributevalueevent.html

./c++_api/class_adapterattributevalueevent.html#a6


./c++_api/class_adapterattributevalueevent.html#a5






Fault/Resource Synchronization scenarios

If the CORBA Adapter process should die, you do not need to provide logic to handle the situation. Application Management automatically restarts the, and the DA library handles all of the necessary synchronization.

You do need to provide specific behavior in your plugin to cope with:

■ The DA process dying

■ Losing communications with an NE

■ Regaining communications with an NE

■ Losing communications with an EMS

■ Regaining communications with an EMS

The development that you must undertake to handle each of these scenarios is outlined in the following sections.

DA process dying

Restarting is no different than starting for the first time.





Losing communications with an NE

If the DA process loses communications with an NE, the DA must call PushNEUnknownStatus(ne_name, time, TRUE) to tell the ADK CORBA Adapter that communication to the NE named “ne_name” has failed and that it has an unknown alarm status.

You can also call the PushEMSAssociationLost(). This single preferred command performs the same function for all NEs managed by that EMS.

Note: You should not clear existing alarms in the plugin code. SUMBB will be updated when the newly retrieved alarm list is pushed and synchronize(...) is called.

For further information on the re-synchronization process, please refer to the NSP Developer’s Guide.

Regaining communications with an NE

When the DA process regains communications with the NE:

1. Call PushNEUnknownStatus(ne_name, time, FALSE).

2. Call pushAlarm() for all active alarms against that NE.





Losing communications with an EMS

When the DA process loses connection to an EMS, you must PushNEUnknownStatus for each NE managed by that EMS with the status set to TRUE.

Regaining communications with an EMS

When the DA process regains connection to the EMS:

1. Call PushNEUnknownStatus() for all NEs managed by that EMS with the status set to FALSE.

2. Call pushAlarm() for all active alarms for all NEs managed by that EMS.



■ MDRAdapter::pushAlarm()







Check for shutdown calls

When a user clicks on the Stop button in the AMGUI, the DA library calls the Shutdown() method. One of the responsibilities of this method is to ensure that resource and alarm reporting is halted, but because the Shutdown() method runs in a separate thread from the Start() method, you must develop a way for Shutdown() to communicate with the Start() method.

One way to accomplish this communication is to define a global boolean variable, for example, shutdown_. You would set the original value of the variable to FALSE. If the Shutdown() method is called, you code it to set its variable to TRUE. Finally, you develop a control structure for the event loop that checks the value of the variable and exits the loop if the variable has a value of TRUE, as is shown in the example below.

Figure 5-7 Code example for checking shutdown calls

// Main event loopwhile(!( shutdown_ )) { try { ...


Develop special alarm handling




Certain special alarm handling is performed outside of the Start() method. This includes the following tasks:

■ Handle manual alarm clear requests (see “Handle manual alarm clear requests” on page 139)

■ Handle alarm acknowledge request (see “Handle alarm acknowledge request” on page 143)

■ Handle service grade alarms (see “Handle service grade alarms” on page 147

Note: When you send a change to an alarm, only the notification ID and vendor-specific information is propagated, since FMBB does not support changes to the technology-specific information list. If technology specific information are sent up, they will change the ADK internal cache.





Handle manual alarm clear requests

You can flag alarms that can be manually cleared.The Plugin Device Adapter (DA) clears the alarm by sending a request to the EMS followed by a pushAlarm() call to push the clear event up to the Framework-based solution.

The ADK provides two SupportBitConstants that can be used to support manual alarm clear requests at the NE level and one at the Alarm level.

Note: The above support bits are found in "SupportBitsConstants.hxx"

Manual Alarm Clear will be processed if ADK_ALARM_SUPPORT_MANUAL_CLEAR is true or, ADK_NE_SUPPORT_MANUAL_CLEAR is true and ADK_ALARM_SUPPORT_MANUAL_CLEAR is not set, otherwise, the request fails.

If ADK_NE_SUPPORT_MANUAL_CLEAR_NEEDS_EMS is set to false, then the Information Server (IS) handles the request, otherwise (i.e. true or not set), the method

Table 5-5 SupportBitConstants for manual alarm clear requests

ADK SupportBitConstant Explanation

ADK_NE_SUPPORT_MANUAL_CLEAR_NEEDS_EMS

Manual Clear of alarm from the framework and EMS

ADK_NE_SUPPORT_MANUAL_CLEAR Manual Clear of alarm from the framework

ADK_ALARM_SUPPORT_MANUAL_CLEAR Manual Clear of this alarm is allowed regardless of ADK_NE_SUPPORT_MANUAL_CLEAR state





MDRAdapter::HandleAlarmClearRequest(AdapterAlarm * alarm_handle, ActionTypeEnum action_type) is called.

The DA must specialize this method in order to handle Alarm Clears. The steps required to add support for this are as follows:

1. Specify which types of NEs will support manual alarm clearing before the NEs are enrolled:

In the absence of this attribute, the default value is FALSE.

2. Specify whether the DA is notified when a manual alarm clear request occurs before the NE enrollment. If the plug-in is not notified, the DA library clears the alarms automatically. If the plug-in is notified, the DA must clear the alarm by sending the subsequent clear event to the NE/EMS. This specifies that the DA will be notified:

This specifies that the plugin will not be notified:

myEnrol = new AdapterNeEnrol(); . . . AvaType *vendorInfo = newAvaType(ADK_NE_SUPPORT_MANUAL_CLEAR , TRUE); myEnrol->addAddedVendor SpecificInfo(vendorInfo); delete vendorInfo;

myEnrol = new AdapterNeEnrol(); . . . AvaType *vendorInfo = new AvaType(ADK_NE_SUPPORT_MANUAL_CLEAR_NEEDS_EMS, TRUE);

myEnrol->addAddedVendorSpecificInfo(vendorInfo);





If neither call is made, the default is set to TRUE.

3. Alternatively, specify on an individual basis whether an alarm can be manually cleared before the alarm is raised (while constructing the AdapterAlarm object), this will over-ride Step #2 values.

4. If you specified that the DA library notify the DA when a manual alarm clear request occurs, you must specialize the following method in the DA and clear the alarm specified in its parameter when the function is called:

If this method is not specialized by the DA, the IS will handle MACs on behalf of the DA, but the state is not persistent inside the ADK.

Note: Optionally, if you want to add a new NE vendor-specific attribute or change an existing one, after the NE is enrolled, use the method addNewAdditionalAttribute() as follows:

AvaType *vendorInfo = new AvaType(ADK_NE_SUPPORT_MANUAL_CLEAR_NEEDS_EMS, FALSE);

myEnrol->addAddedVendorSpecificInfo(vendorInfo);

AvaType *vendorInfo = new AvaType (ADK_ALARM_SUPPORT_MANUAL_CLEAR , TRUE); myAlarm->addAddedVendorSpecificInfo (vendorInfo); delete vendorInfo;

void MDRAdapter::HandleAlarmClearRequest (AdapterAlarm* alarm_handle, ActionTypeEnum action_type);





Caution should be exercised in making decisions on vendor-specific information in this case. If messages initiated in a DA and sent to Framework platforms contain any vendor-specific information, that information overwrites any previous vendor-specific information. Thus, full vendor-specific information could be replaced with partial information. If it is decided to use vendor-specific information, then ALL vendor-specific information must be included in all notifications.

Note: While the ADK provides an API for you to change certain NE attributes, it is your responsibility to ensure that the Framework-based solution is capable of processing the change.


■ AvaType

■ MDRAdapter::HandleAlarmClearRequest()

AdapterAttributeValueEvent *myAVCEvent = new AdapterAttributeValueEvent(); AvaType* vendorAva = new AvaType(ADK_NE_SUPPORT_MANUAL_CLEAR_NEEDS_EMS, TRUE); myAVCEvent->addNewAdditionalAttribute(ntNTDefined AttributeIds_vendorSpecificInfo_C,vendorAva);

_myAdapter->PushAttributeValueEvent(myAVCEvent);







Handle alarm acknowledge request

At the time of instantiating the ADK CORBA Adapter (CA), you need to decide whether Alarm Acknowledgement is supported by the ADK / Plugin Device Adapter or not. This setting cannot be changed for the life of the CA.

By setting the 3rd field Enter value for: Acknowledgement Supported to false, Alarm Acks are handled by the FMBB. To enable reception of Alarm Acks Messages to the ADK / DA, you need to set it to true.

Note: Many device adapters now have the ability to handle and store alarm acknowledgement information. If, following an upgrade, responsibility for alarm acknowledgement information is to be handled by DAs and not FMBB, FMBB will flush any stored (pre-upgrade) acknowledgement data it has if the acknowledgement support setting is set to true during the upgrade.

The HandleAlarmAckRequest() method will be called in response to an alarm acknowledgement (or unacknowledgement) request, only if the CA server for the domain was instantiated from the Application Manager (AM) with Acknowledgement Supported set to true.





If the Plugin Device Adapter (DA) doesn't implement this method, the default ADK method MDRAdapter::HandleAlarmAckRequest() will respond to the request. The Acknowledgment Information within the ADK is non persistent.

If the DA needs to be notified when an alarm acknowledge request occurs, you must specialize the MDRAdapter::HandleAlarmAckRequest() method in the DA and acknowledge the alarm specified in its parameter when the function is called:

When the DA finishes the request, it should invoke the MDRAdapter::PushAttributeValueEvent() method.

The DA may choose to unacknowledge instead of acknowledging an alarm, which can be done by the method AdapterAlarm::setAcknowledgementStatus()

void MDRAdapter::HandleAlarmAckRequest (AdapterAlarm* alarm_handle, ActionTypeEnum action_type);

void MDRAdapter::HandleAlarmAckRequest (AdapterAlarm* alarm_handle,ActionTypeEnum action_type){ alarm_handle->setAcknowledgementStatus(FALSE);

}





Note: Optionally, if you want to add a new Alarm vendor-specific attribute or change an existing one, after the Alarm is raised, use the method addAddedVendorSpecificInfo(), as follows:

Note: While the ADK provides an API for you to change certain Alarm attributes, it is your responsibility to ensure that the Framework-based solution is capable of processing the change.

Note: Vendor Specific Information and Technology must be pushed up as a whole.


■ AvaType

■ MDRAdapter::HandleAlarmAckRequest()

■ AdapterAttributeValueEvent

Note: Caution should be exercised in deciding if vendor-specific information is to be included in messages that are initiated in a DA and sent to NSP platforms. If such messages contain ANY vendor-specific information, this information will over-write

alarm_handle->addAddedVendorSpecificInfo( myAva = new AvaType("VendorSpecific2", "DEF"));delete myAva;







ALL existing vendor-specific information. If it is decided to include vendor-specific information, then ALL vendor-specific information must be included.





Handle service grade alarms

Alarms can be flagged to indicate whether the alarm is service affecting or not.

To add service grade information to an alarm, you call the following function of the AdapterAlarm before the alarm is raised, specifying “SA” (for service affecting alarms), and “NSA” (non-service affecting alarms):

AvaType *vendorInfo = new AvaType(alarmImpact, "NSA"); myAlarm->addAddedVendorSpecificInfo(vendorInfo); delete vendorInfo;


Developing


6

Developing a Model Conversion File

As part of developing the resource and alarm capabilities of an Adapter plugin, a Model Conversion File (MCF) is required. This chapter contains information on converting an alarm from an NE object model to the NSP object model. This is a mapping of objects from the network element naming schema to the platforms naming schema.

a Model Conversion File 148

Introduction to the Model Conversion File




An example of how the Model Conversion File (MCF) works is that the object ID of the PushAlarm() method and the managed element object of the PushNeEnrol() and PushNeDeEnrol() methods go through naming changes according to the information contained in the MCF file. The “network object” that is described by these object models can be as general as a network or as specific as a port. A few lines from a Model Conversion File, which is always named inm.map, are shown below.

Figure 6-1 Sample entries from a Model Conversion File

Each line in the MCF is a single entry, and each entry consists of two main parts separated by a hyphen:

■ a Distinguished Name (DN), to the left of the hyphen, is a hierarchical name in the NE object model, that begins at the highest level (the network) and lists as many levels as is required to uniquely identify the object

■ a list of comma-separated Attribute-Value Assertions (AVA), to the right of the hyphen, maps the NE object model to the NSP object model.

It is not required that the NE or EMS objects exactly match the NSP objects (as is seen in the third line of the example).

NW EM Shelf - network $NW, managedElement $EM, equipmentHolder $ShelfNW EM AtmIf Vcc - network $NW, managedElement $EM, vpTTPBidirectional $AtmIf, vcCTPBidirectional $VccNW EM Shelf Card Port - network $NW, managedElement $EM, equipmentHolder $Shelf, circuitPack $Card

Developing a Model Conversion File 149




Each of these concepts is explained in detail in the following pages of this chapter.

For more information, see the ADK API Reference coverage of AvaType.





Distinguished name The purpose of a Distinguished Name (DN) is to identify an object unambiguously. This applies to both the NE or EMS object model, and to the NSP Object Model. However, the ordering of the object elements, from which a DN is composed, is based upon the NSP Object Model's hierarchy, which is termed the “name binding tree”.

On the right side, or object mapping side, of each MCF entry, the DN consists of a series of Attribute Value Assertions (AVA). Each comma-delimited AVA consists of an attribute ID (an NSP object) and its associated value (the equivalent NE/EMS object). The first AVA attribute in a Distinguished Name is always “network”, which represents the highest level of the name binding tree. The subsequent AVA attributes in a Distinguished Name represent the descending layers of the name binding tree, down to the level where the object is uniquely identified.

Figure 6-2 on page 155 shows a segment of the name binding tree that will clarify this downward progression from the highest level “network” down to the lower levels of increasing specificity.





NSP Object Model The Framework Object Model has two segments: resource (for NE discovery) and fault management (to represent physical and logical network objects). NE discovery involves managedElement level objects. Alarms are raised against objects in the levels below the managedElement object.

It is not necessary to understand the entire NSP platforms object model (which is very large) to use the ADK. For the purposes of integration, you need to understand only the supported managed object classes to which your alarm-generating components correspond. See the Standard Object Model class list for a list of the supported managed object classes used in the inm.map file. If the needs of your NE or EMS go beyond the standard objects, see the Non-Standardized Attributes page.

Although a unified NSP Object Model reference has not yet been written, an effort is currently underway to create such a document.

It is not necessary for your network element objects to match the NSP model. The MCF provides a means of translating an object based on your NE naming schema to a DN based on the Framework naming schema.





In the MCF, you list the naming hierarchy of each object you use in your plugin, and the corresponding naming recognized by the Framework (even if they are the same).

The Device Adapter utilizes the mapping information in the MCF to correspond between objects named according to your NE information model and the associated objects recognized by the Framework. Specifically, the object ID of the PushAlarm() method and the managed element object of the PushNeEnrol() and PushNeDeEnrol() methods go through naming changes according to the information contained in the MCF file.





Name binding tree The NSP platform refers to managed objects through hierarchical naming. The naming hierarchy is expressed in the form of a name binding tree, as illustrated by Figure 6-2 on page 155. You can enrol NEs up to the managedElement level; however, you can raise alarms to the level below the managedElement such as circuitPack. Table 6-1 on page 156 shows the supported managed object classes.

Note: Figure 6-2 on page 155 shows a segment of the name binding tree. The curved arrow above some of the objects in the figure indicates that there may be multiple levels of the object. For example, a network of managed elements may be subdivided into regions, and a region into smaller areas, and you may need to reflect this in the naming hierarchy (see “Mapping a multi-level network object” on page 171).





Figure 6-2 Managed object name binding tree

network

electicalSPITTPBidirectional and

rsTTP

msTTPBidirectional

augBidirectional

au4CTPBidirectionalau4CTPBidirectional

vc4TTPBidirectional

tug3Bidirectional

tu3CTP

tug2Bidirectional

tu2CTP

tu11CTPBidirectional

vc3TTPBidirectional

vc2TTP

vc11TTPBidirectional

vc12TTPBidirectional

ds1LineTTPBidirectional


e3TTPBidirectional

e1TTPBidirectional

Uni

IntraNNI

interNNIvpTTPBidirectional

vcCTPBidirectional

tcAdaptorTTPBidirectional

vpCTPBidirectional

msTTPBidirectionalvc4TTPBidirectional

vcTTP


ds1PathTTPBidirectionalds3LTTPBidirectional

ds3PathTTPBidirectional

sdhMSprotectionGroup

sdhMSprotectionUnit

sdhBLSRProtectionGroupBCR

sdhBLSRProtectionUnitBCR

managedElement

equipmentHolder

circuitPack

equipment

Bidirectional

tu12CTPBidirectional

Bidirectional

Bidirectional

optical SPITTPBidirectional

Bidirectional

Bidirectional





Table 6-1 Supported standard object classes

Managed Object Class—used in the inm.map file

network circuitEndPointSubgroup

equipment equipmentHolder

managedElement networkR1

software managedElementComplex

connectionTerminationPointBidirectional au3CTPBidirectional

connectionTerminationPointSink au3CTPSink

connectionTerminationPointSource au3CTPSource

terminationPoint au4CTPBidirectional

crossConnection augSink

fabric augSource

gtp electricalSPITTPBidirectional

mpCrossConnection electricalSPITTPSink

namedCrossConnection electricalSPITTPSource

namedMpCrossConnection msCTPBidirectional

tpPool msCTPSink

alarmSeverityAssignmentProfile msCTPSource

connectionR1 msTTPBidirectional

pipe msTTPSink

fabricR1 opticalSPITTPBidirectional

managedElementR1 opticalSPITTPSink

equipmentR1 opticalSPITTPSource

softwareR1 rsTTPBidirectional

circuitPack rsTTPSink

rsTTPSource vc12TTPSink

rsCTPBidirectional vc12TTPSource

rsCTPSink vc2TTPBidirectional

rsCTPSource vc2TTPSink





sdhNE vc2TTPSource

tu11CTPBidirectional vc3TTPBidirectional

tu11CTPSink vc3TTPSink

tu11CTPSource vc3TTPSource

tu12CTPBidirectional vc4TTPBidirectional

tu12CTPSink vc4TTPSink

tu12CTPSource vc4TTPSource

tu2CTPBidirectional protectedTTPBidirectional

tu2CTPSink protectedTTPSink

tu2CTPSource protectedTTPSource

tu3CTPBidirectional protectionGroup

tu3CTPSink protectionUnit

tu3CTPSource sdhMSProtectionGroup

tug2Bidirectional sdhMSProtectionUnit

tug2Sink unprotectedCTPBidirectional

tug2Source unprotectedCTPSink

tug3Bidirectional unprotectedCTPSource

tug3Sink connectionProtectionGroup

tug3Source connectionProtection

vc11TTPBidirectional mpConnectionProtection

vc11TTPSink sncpFabric

vc11TTPSource ds1CTPBidirectional

vc12TTPBidirectional ds1CTPSink

ds1CTPSource objectDeletionRecord

ds1LineTTPBidirectional relationshipChangeRecord

ds1LineTTPSink securityAlarmReportRecord

ds1LineTTPSource stateChangeRecord

Table 6-1 Supported standard object classes (Continued)






ds1PathTTPBidirectional system

ds1PathTTPSink top

ds1PathTTPSource problemRecord

ds3CTPBidirectional thresholdData

ds3CTPSink historyData

ds3CTPSource LayerNetwork

ds3LineTTPBidirectional Subnetwork

ds3LineTTPSink SubnetworkConnection

ds3LineTTPSource Link

ds3PathTTPBidirectional LinkConnection

ds3PathTTPSink ManagedNetwork

ds3PathTTPSource Matrix

ringMapBCR NetworkTTP_Source

sdhBLSRProtectionGroupBCR NetworkGroupSource

sdhBLSRProtectionUnitBCR NetworkCTP_Source

alarmRecord NetworkTTP_Sink

attributeValueChangeRecord NetworkGroupSink

discriminator NetworkCTP_Sink

eventForwardingDiscriminator NetworkTTP_Bi

eventLogRecord NetworkGroupBi

log NetworkCTP_Bi

logRecord NetworkCTP

objectCreationRecord NetworkTTP

nxE0CTPBid vpTTPBidirectional

atmAccessProfile atmLink

atmCrossConnection atmLinkConnection

atmFabric atmLinkTP







atmMpFabric atmNetworkAccessProfile

cellHeaderAbnormalityLogRecord atmNetworkCTP

cellLevelProtocolCurrentData atmNetworkTTP

cellLevelProtocolHistoryData atmNetworkTrafficDescriptorProfile

ds3PLCPPathCTPBidirectional atmRoutingProfile

ds3PLCPPathCTPSink atmSubnetwork

ds3PLCPPathCTPSource atmSubnetworkConnection

ds3PLCPPathTTPBidirectional atmSubnetworkTP

interNNI vcLayerNetworkDomain

intraNNI vpLayerNetworkDomain

latestOccurrenceLog pPITTPBidirectional

multipointBridge pPITTPSink

tcAdaptorCurrentData pPITTPSource

tcAdaptorHistoryData ePDHTTPSink

tcAdaptorTTPBidirectional ePDHTTPSource

uni ePDHTTPBidirectional

upcNpcCurrentData e4CTPSink

upcNpcHistoryData e4CTPSource

vcCTPBidirectional e4CTPBidirectional

vcTTPBidirectional e4TTPSink

vpCTPBidirectional e4TTPSource

e4TTPBidirectional g855network

e3CTPSink g855adminDomain

e3CTPSource g855basicLayerNetworkDomain

e3CTPBidirectional g855basicSubNetwork

e3TTPSink g855link

e3TTPSource g855linkConnection







e3TTPBidirectional g855networkCTPBidirectional

e2CTPSink g855networkCTPSink

e2CTPSource g855networkCTPSource

e2CTPBidirectional g855networkTTPBidirectional

e2TTPSink g855networkTTPSink

e2TTPSource g855networkTTPSource

e2TTPBidirectional g855node

e1CTPSink g855subNetworkConnection

e1CTPSource g855topologicalPoint

e1TTPSink p12CTPSource

e1TTPSource p12CTPBidirectional

e1TTPBidirectional p31CTPSink

jt2TTPBidirectional p31CTPSource

frsCarrierAccess p31CTPBidirectional

frsDLCCTPBid p4CTPSink

frsIciL2PathTTPBid p4CTPSource

frsSubscriberAccess p4CTPBidirectional

frsUniL2PathTTPBid p12CTPSink

nxDs0CTPBid msTTPBidirectional

troubleTicketReport ds1LineCTPBid

e1CTPBid

interface







Generic attributes Additional attributes beyond those defined in the standards may be required for effective integrated management or to allow network element specific value-added extensions. Table 6-2 on page 161 lists non-standard attributes required by the Preside platforms.

Table 6-2 Supported generic object attributes

Object Attribute Purpose

managedElement EMLAddress Represents the EML network management entities’ IP address. Useful for pass-through.

NEAddress Represents the IP address of the actual switch. Useful for direct trouble-shooting access to the switch.

all objects NativeName Representing the native name of the object on the native EML system. Useful for queries on the EML system.





Network object mapping

This release implements mapping for the network object. If you wish to use the network object in your mapping, then you must:

■ Use the inm.map file supplied with this release.

■ Fill in the network ID for all object IDs. In other words, your object IDs must have at least two AVAs—one for the network and one for the managed element.

If you do not wish to use the network object in your mapping, then you must:

■ Use an inm.map file without network mapping.

■ NOT fill in the network ID for any object IDs. A default network ID of “Ottawa” will be supplied by the ADK.





MCF restrictions and limitations

The NSP object model used for resource and alarm management support, on which the MCF is based, has the following restrictions and limitations:

■ Attribute value changes are only supported on the attributes of the managedElement object class. They are not supported for the following attributes of this class:

■ NE Type ■ Object ID (key attribute)

■ State changes are only supported for the managedElement object class.

■ Object Enrol and Object De-Enrol are only supported for the managedElement object class.

■ Only one model conversion file is provided1. If multiple plugins are running on the same run-time platform, then the mappings for each of the plug-ins must be concatenated into one model conversion file. Therefore object model mappings of multiple plug-ins running on the same run-time platform must not conflict.

■ Only “stringified” object identifiers (for example, “EM crest1 Shelf3 card7 mapper2”) are supported. Object identifiers using integers or arrays of integers such as

1. This works with the SampleDeviceAdapter. If you wish to develop your own DA, that is not based on the SampleDevice-Adapter, you will also need to develop your own MCF.





“1.3.5.6.8.1.32.41.2.3.3” or “42 crest1 43 3 118 mapper2” are not supported.


Create the Model Conversion File for your plugin




You must customize the model conversion file to map the objects used in your EMS (or NE) into the Framework.

Where to create the MCF

The default model conversion file is found in the cfg/generic subdirectory of the development environment. The file is called inm.map, and you modify it for use with your plugin.

A sample version of the inm.map file is provided in the src subdirectory of the development environment. You must use this file if you want to use the sample plugin that is shipped with the ADK release. Before using the sample inm.map file with the sample plugin, save the default inm.map file under another name and then copy the sample inm.map file from the src directory to the cfg/generic subdirectory. When you are ready to modify or use the default inm.map file, return it to the cfg/generic subdirectory under its original name.

If DA is not based on SampleDeviceAdapter, you will need to make sure to make a copy to the generic directory, rename it and then put it in the inm_map file.





Note: The environment variable MOAFW_CONFIG_DIRECTORY can be used to change the location of the map files. This variable is set to the cfg directory by default but can be configured via the moafw.profile file.

The contents of the sample inm.map file are shown in Figure 6-7 on page 173 and page 174.

Note: At run time, only one instance of the inm.map file is allowed, even if multiple Adapter processes are running. If multiple Adapter processes managing NEs with different name mappings are running on the same platform, then you must concatenate the mappings for all of the plug-ins into one MCF.

➤ To identify the NSP Object Model DN for an object

For each object in your plugin, use the following procedure:

1. Find the object you want to map to in the name binding tree. Figure 6-2 on page 155 shows only a segment of the name binding tree.

2. Find name for each component of the object’s DN in Table 6-1 on page 156.

3. Determine if there is a mapping line for this object in the sample MCF, to use as a model in the MCF you are creating.





The plugin object’s DN has to be mapped into the platforms object’s DN. Each AVA in the plugin object’s naming structure is a parameter to be passed into the platforms object’s DN.

4. Create a mapping line in your MCF.

Creating a Mapping Line in the MCF

A mapping line consists of the plugin object’s name structure followed by the parameterized platform object’s name structure, separated by a hyphen. For example:

plugin object’s name structure—is a series of parameterized AVAs, each separated by a space.

For example:

NW EM LP DS3

Note: When you map objects used in your EMS (or NE) into the platform, you must enter the plugin object's name structure using unique tokens, each separated by a space. That is, the mapping on the left-hand side must have unique tokens; for example NW EM Eq Eq1 Eq2, and not as NW EM Eq Eq Eq.

NW EM Eq - network $NW, managedElement $EM, equipment $Eq





As an example of this, the following tokens are valid:

Whereas the following tokens are not valid:

parameterized NSP platforms object’s name structure—consists of a series of two-part AVAs. Each AVA is separated by a comma. The two-part AVA consists of:

■ The full name of the attribute

■ One or more parameters, separated by spaces, where each parameter consists of:

■ The $ character■ The corresponding attribute value of your

plugin’s object.

For example:

NW EM Eq Eq1 Eq2 - network $NW, managedElement $EM, equipment $Eq, equipment $Eq1, equipment $Eq2

NW EM Eq Eq Eq - network $NW, managedElement $EM, equipment $Eq, equipment $Eq, equipment $Eq

network $NW, managedElement $EM, ds3LineTTPBidirectional $LP $DS3





An example mapping line

If a bidirectional DS3 Line Trail Terminating Point is defined in your plugin as “NW EM LP DS3”:

■ In the name binding tree you will find an object called ds3LTTPB. There are three AVAs in its DN, which are:

■ There is one more AVA in your plugin’s object than there is in the corresponding NSP object.

■ Using Table 6-1 on page 156 the full names of the AVAs are:

■ In the sample MCF there is a mapping line for this object, shown below:

Figure 6-3 Sample mapping line

Note that the last two AVAs of the plugin object are combined as parameters of the third AVA of the NSP object.

Another example is shown in Figure 6-4 on page 170.

network managedElement ds3LTTPBidirectional

network, managedElement, ds3LineTTPBidirectional

NW EM LP DS3 - network $NW, managedElement $EM, ds3LineTTPBidirectional $LP $DS3





Figure 6-4 Mapping a line in the MCF to the Object Model

Mapping by default

If no exact match is found then the object is by default mapped to an object under managedElement; the first component value is mapped to the value of managedElementId and the rest of the components are mapped to the default mapping. The default mapping is indicated by a source_name of “DEFAULT”.

NW EM Shelf Card - network $NW, managedElement $EM, equipmentHolder $Shelf, circuitPack $Card

This example maps from an NE information model object named:NW net_id EM em_id Shelf shelf_id Card card_id

to an internal information model object named:network NW/net_id managedElement EM/em_id equipmentHolder Shelf/shelf_id circuitPack Card/card_id

An actual example would map an NE information model object named:EM crest1 Shelf 3 Card mapper2

to an internal information model object named:managedElement EM/crest1 equipmentHolder Shelf/3 circuitPack Card/mapper2





Figure 6-5 Default mapping of an object not specified in the MCF

Mapping a multi-level network object

To support a multi-level network object, code similar to that in Figure 6-6 on page 171 can be added to the inm.map file.

Figure 6-6 Multi-level network object mapping

These mappings indicate three network levels (which could be, for example, the overall network, one of its regions, and a sales area in that region):

For example, if no mapping is specified for “EM X Y Z” and the default mapping is:

DEFAULT - SOFTWARE $DEFAULT

then “EM NODER16 X 1 Y 2 Z 3” would be mapped to:

managedElement $EM/NODER16 SOFTWARE $X/1 SOFTWARE $Y/2 SOFTWARE $Z/3

NW DN SNW EM Lp DS1 - network $NW, network $DN, network $SNW, managedElement $EM, ds1LineTTPBidirectional $LP $DS1

NW DN SNW EM Shelf Card Port - network $NW, network $DN, network $SNW, managedElement $EM, equipmentHolder $Shelf, circuitPack $Card $Port

NW network $NW DN network $DN SNW network $SNW





The object instance for the managed element is:

Setting the token environment variables—To support multi-level network objects you must set the value of the MOAFW_NETWORK_OBJECT_TOKEN environment variable to the last network token. For example, if the mapping is:

The last network token is “SSNW”, so you would set the MOAFW_NETWORK_OBJECT_TOKEN environment variable as follows:

You can also, optionally, override the network element token as follows:

AVA Name [1] (I) :1030: (networkId) AVA Value [1] (S) :Vancouver: AVA Name [2] (I) :1030: (networkId) AVA Value [2] (S) :fw1288: AVA Name [3] (I) :1030: (networkId) AVA Value [3] (S) :47.63.66.16: AVA Name [4] (I) :1028: (managedElementId) AVA Value [4] (S) :RNE5:

"NW SNW SSNW EM - network $NW, network $SNW, network $SSNW, managedElement $EM,",

MOAFW_NETWORK_OBJECT_TOKEN="SSNW" ; export MOAFW_NETWORK_OBJECT_TOKEN

MOAFW_NETWORK_ELEMENT_TOKEN="EM" ; export MOAFW_NETWORK_ELEMENT_TOKEN





Sample inm.map file (MCF)

Target components are delimited by commas.

Comment lines begin with a ‘#’ and the file is case insensitive.

Figure 6-7 Sample inm.map file (1 of 2)

## ---------------------------------------------------------------------------------------#NW EM Lp DS1 - network $NW, managedElement $EM, ds1LineTTPBidirectional $LP $DS1NW EM LP DS3 - network $NW, managedElement $EM, ds3LineTTPBidirectional $LP $DS3NW EM LP E1 - network $NW, managedElement $EM, e1TTPBidirectional $LP $E1NW EM LP E3 - network $NW, managedElement $EM, e3TTPBidirectional $LP $E3NW EM LP DS1 Chan - network $NW, managedElement $EM, ds1LineTTPBidirectional $LP $DS1,

ds1LineCTPBid $ChanNW EM LP E1 Chan - network $NW, managedElement $EM, ds1LineTTPBidirectional $LP $E1, e1CTPBid

$ChanNW EM LP Jt2 - network $NW, managedElement $EM, msTTPBidirectional $LP $Jt2NW EM LP V35 - network $NW, managedElement $EM, msTTPBidirectional $LP $V35NW EM LP X21 - network $NW, managedElement $EM, msTTPBidirectional $LP $X21NW EM Lp Sonet - network $NW, managedElement $EM, msTTPBidirectional $Lp $SonetNW EM Lp Sonet Path - network $NW, managedElement $EM, vc4TTPBidirectional $Lp $Sonet $PathNW EM Lp Sdh - network $NW, managedElement $EM, msTTPBidirectional $Lp $SdhNW EM Lp Sdh Path - network $NW, managedElement $EM, vc4TTPBidirectional $Lp $Sdh $PathNW EM Shelf - network $NW, managedElement $EM, equipmentHolder $ShelfNW EM Shelf Card - network $NW, managedElement $EM, equipmentHolder $Shelf circuitPack $CardNW EM Shelf Bus - network $NW, managedElement $EM, equipmentHolder $Shelf $BusNW EM Trk Unacked Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk

$Unacked $FramerNW EM Trk Unacked Atm- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk $Unacked

$AtmNW EM Trk Pa Atm - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk $Pa $AtmNW EM Trk Atm - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk $AtmNW EM DpnGate Utp Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $DpnGate

$Utp $FramerNW EM Vs Framer - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Vs $FramerNW EM Btds Framer - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Btds $FramerNW EM Htds Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Htds $Fra





Figure 6-7 Sample inm.map file (2 of 2)

NW EM FrUni - network $NW, managedElement $EM, uni $FrUniNW EM FrUni Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $FrUni $FramerNW EM FrUni Dlci - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $FrUni

vpTTPBidirectional $DlciNW EM FrNni - network $NW, managedElement $EM, intraNNI $FrNniNW EM FrNni Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $FrNni $Framer#NW EM AtmIf - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $AtmIf NW EM AtmIf UNI - network $NW, managedElement $EM, uni $AtmIf NW EM AtmIf PPI - network $NW, managedElement $EM, intraNNI $AtmIf #NW EM AtmIf Vcc - network $NW, managedElement $EM, vpTTPBidirectional $AtmIf, vcCTPBidirectional

$VccNW EM AtmIf Vpc - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $AtmIf,

vpCTPBidirectional $Vpc#NW EM AtmIf Vcc Vcd - network $NW, managedElement $EM, vpTTPBidirectional $AtmIf $Vcc,

vcCTPBidirectional $Vcc $VcdNW EM AtmIf Vpc Vpd - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $AtmIf,

vpCTPBidirectional $Vpc $Vpd## default mapping for components not specified in above list#NW - network $NWEM - managedElement $EMDEFAULT - software $DEFAULT## END OF FILE


Compiling a


7

Compiling and packaging your Device Adapter

This chapter describes the final stages of developing a device adapter: compiling and packaging it. Each of the two major sections in this chapter guide you through the steps that are required to successfully accomplish these tasks. It is assumed that you have completed the development tasks described in the chapters:

■ Developing the basic Device Adapter

■ Developing resource and alarm capabilities

■ Developing a Model Conversion File

These instructions also assume that you have completed the tasks described in the section “Configuring and sanitizing the test environment” in Chapter 2, Installation and configuration.

nd packaging your Device Adapter 175



Chapter overview “Directory Structure“describes the recommended method of organizing your files related to your DA.

“Compiling your Device Adapter“ is mostly concerned with the changes that you must make to the makefile to successfully compile the Adapter binary from the Adapter libraries and the Adapter plugin code that you have developed.

“Packaging your Device Adapter“ guides you through the steps required to create an installation tar file that includes all of the files required for your Device Adapter package.

“Installing your packaged Device Adapter“ provides guidelines on how and where the developed adapter goes and how to run it.

Compiling and packaging your Device Adapter 176

Directory Structure



Directory Structure

The recommended file structure for your DA is designed to provide for ease of packaging and deployment, for streamlined upgrades and for coexistence of multiple adapters and versions on the same system. It will also reduce the chance of installation conflicts with other FW / ADK packages.

Create a directory with the name of your adapter (i.e. myDA) in /opt/nortel/adapters and a subdirectory for specific versions (i.e. /opt/nortel/adapters/myDA/myDA_1.1.0).

In your top level directory, make use of the symbolic link current_myDA to point to the recent version of the adapter (i.e. myDA/current_myDA --> ./myDA_1.1.0). This will eliminate the need to modify any scripts and will always point to the most recent version of the adapter (or the one you want to use).

This directory structure is also recommended for the deployment of your device adapter, and will allow the co-existence of multiple adapters on the same system.

Recommended subdirectories to the base directory /opt/nortel/adapters/<your DA>/

current_<your DA>/ are:

bin - adapter executable and shell scripts·

lib - additional libraries required by the adapter·

jars - additional java jar files required by the adapter·


Directory Structure



resources/inc - additional include files ·

resources/cfg - adapter configuration files·

resources/src/plugin - your adapter source files

You can branch additional directories from the resources directory as required.


Compiling your Device Adapter




The compilation of your Device Adapter should be done with a copy of the sample.makefile provided in current_adk/resources/src/plugin directory. Copy the sample makefile to your plugin directory, and make the modification that is needed to reflect your Device Adapter specific local environment.

In particular, you will need to update:

■ EXECUTABLE■ ALLINCLUDES■ PLUGIN_SRCS■ PLUGIN_OBJS■ PLUGIN_LIBS

You have already seen how to compile the provided SampleDeviceAdapter using the sample.makefile in “Sanitize the development environment” on page 45. The only variations here are specific to your Device Adapter (such as name, libraries, and include files). For information on the specific statements requiring modification, please refer to the sample makefile.

If additional development components are required for the particular NE or EMS for which you are developing a Device Adapter, these components must be installed and configured before you compile your adapter.

■ cd to /opt/nortel/adapters/<Your DA>/current_<Your DA>/resources/src/plugin





■ cp /opt/nortel/adapters/adk/current_adk/resources/src/plugin/ sample.makefile ./Makefile·

■ update the "C_DIR" variable in the Makefile to point to the compiler installed on your system.·

■ Update EXECUTABLE, PLUGIN_SRCS, PLUGIN_OBJS variable to your adapter's name.·

■ Update ALLINCLUDES and EXTRA_LIBRARIES to include additional required headers and libraries·

■ Include the path to the extra libraries "-L/../../lib"·

■ Within the same directory, issue a make on the Makefile.

Note: If you have successfully compiled the Sample Device Adapter, as described in the “Sanitize the development environment“ section, and can't compile your adapter successfully, it is likely that the problem is with the path to your additional libraries and header files.

Please refer to the included sample.makefile for additional details.


Packaging your Device Adapter



Packaging your Device Adapter

Packaging your device adapter involves bundling the various adapter components from the development system. Using your favorite packaging tools, collect the following files from the development system:

<Your DA>/current_<Your DA>/resources/src/plugin/<Your DA> <Your DA>/current_<Your DA>/resources/src/plugin/<Your DA>Launch.sh <Your DA>/current_<Your DA>/resources/cfg/ <Your DA>/current_<Your DA>/lib/* AMTemplate inm.map (if modified)


Installing your packaged Device Adapter



Installing your packaged Device Adapter

On the target system, create the directory structure as outlined in the Directory Structure section.

Port the adapter bundle over to the target system and place the components in the bundle as follows:

:<Your DA>/current_<Your DA>/bin/<Your_DA> <Your DA>/current_<Your DA>/bin/<Your_DA>Launch.sh <Your DA>/current_<Your DA>/resources/cfg/ <Your DA>/current_<Your DA>/lib* AMTemplate inm.map (if modified) will go in the ADK runtime directory adk/current_adk/resources/cfg.


Appendix —


A

Allocation policy

This appendix shows the classes, number of instances and the associated allocation policy that you should use when developing your Adapter plugin.

Table A-1 ADK allocation policy

Class Number of instances Allocation policy

MDRAdapterFactory One Created by init_mdr_factory()

Specialization of MDRAdapter

One Created by calling createMDRAdapter()

AdapterAlarm One transient instance per alarm raise or clear

Created when an alarm is generated: can be destroyed after alarm is pushed

AdapterNeEnrol One transient instance per NE enrol

Created when an NE is discovered: can be destroyed after NE enrol has been pushed

AdapterDeEnrol One transient instance per NE de-enrol

Created when an NE is deleted: can be destroyed after NE de-enrol has been pushed

AdapterOsiStateEvent One transient instance per state change event

Created when managedElement has a state change: can be destroyed after state change has been pushed

AdapterAttributeValueEvent

One transient instance per attribute value change

Created when managedElement has an attribute value change: can be destroyed after attribute value change has been pushed

183

http://crestdoc.ca.nortel.com/FRAMEWORK/BookFeedback/feedback_obtain.php


You can allocate the helper classes on either the heap or the stack. The memory should be freed as soon as the helper instance has been used, for example, after calling PushNeEnrol() or PushAlarm().

AdapterConfig One instance in the SetupInitialConfig() callbackOne instance in the Reconfigure() callbackOne instance when calling GetConfig()

Created and destroyed by the Adapter plugin for the SetupInitialConfig() and Reconfigure() callbacks

Must be created before calling GetConfig() and deleted afterwards

RWTPtrSlist<AvaType> One transient instance per NE enrol, NE de-enrol, OSI State Event, Attribute Value Event, alarm, and NE Unknown Status

Created before calling a Push method (i.e. PushNEUnknownStatus, PushEnrol, PushDeEnrol, PushAlarm, PushOsiStateEvent, PushAttributeValueEvent).Can be destroyed after calling a Push method.

AvaType for ObjectId

One transient instance per component of a distinguished name, i.e. RWTPtrSlist<AvaType>

Created before calling a Push method (i.e. PushNEUnknownStatus, PushEnrol, PushDeEnrol, PushAlarm, PushOsiStateEvent, PushAttributeValueEvent).Can be destroyed after calling a Push method.

AvaType for VendorSpecificInfo and TechnologySpecificInfo

One transient instance per VendorSpecificInfo or TechnologySpecificInfo.

Created before calling addAddedVendorSpecificInfo() or addAddedTechnologySpecificInfo().Can be destroyed after calling addAddedVendorSpecificInfo() addAddedTechnologySpecificInfo().

Table A-1 ADK allocation policy (Continued)

Class Number of instances Allocation policy

Appendix — 184


Purify is an optional third-party tool you can use to notify you of errors in memory usage, particularly in memory allocation.

Appendix — 185


B

Engineering information

This appendix contains the following ADK 4.3 engineering information:

■ “ADK platform requirements” on page 187

■ “ADK engineering limits” on page 188

Data on NE enrollment and alarm processing performance is located in the Engineering considerations chapter of the Framework Engineering Guide.

186



ADK platform requirements

The following are the minimum platform requirements for a system to run the ADK software at the currently supported full scalability:

■ Sun Fire 4800

■ Solaris 8

■ 1.8GB of disk space for ADK installation

■ 512MB of memory available for ADK operation

187



ADK engineering limits

The following table describes the engineering limits for the ADK 4.3 run-time platform.

Table B-1 ADK Engineering LimitsEngineering Limits

Number of network elements supported 3,500

Number of alarms supported 24,000

Number of instances of the CORBA Adapter 1 per DA

Number of instances of Device Adapters (DA) 4

188


Glossary

The glossary contains definitions of all major terms and acronyms used in this guide, throughout Network Services Platform (NSP) and all Development Kits.

Networks Services Platform (NSP) & Development Kis 189


Glossary

A

AC Access Control is a feature used to limit the rights of groups of users on the services offered by building blocks. A building block offers services, be it through CORBA interfaces, RMI interfaces, IP based messaging or any other type of messaging system. Before access control, it was assumed that all users accessing a building block had the same access rights. The access control feature is a way to recognize the fact that not all users are the same. There are different types of users that can have different access rights to services

Accelerators Java term for Ctrl + keystroke shortcut to implement a menu item.

Access List Access control list. A collection of all access rights for one object in computer security.

AC Lib Access Control Library. This library is found in the Access Control database. It provides User and User Group privileges.

ACT Access Control Tool

ACT GUI Access Control Tool Graphical User Interface used to configure User and User Group privileges.

ADK Device Adapter Development Kit - a development kit used by integrators to develop their specific device adapter. It comprises the device adapter software (minus the plugin), the required third-party software, libraries, and API documentation.

ADK CORBA Adapter The upward-looking interface of a Device Adapter that communicates with the Framework fault and resource management clients over a standards-based CORBA interaction model.

Network Services Platform (NSP) & Development Kits 190


Glossary

Administrative Property In the Event Port, a property that is related to channel administration policies, as opposed to message Quality of Service (QoS).

AL Application Launch

ALF Application Launch Facility

Alarm A message from a network element indicating a problem in the monitored network.

AL Server Application Launch CORBA Server

ALPHA A project life-cycle milestone used to clarify with the customer / market that the product contains the required functionality, and that the UIs are usable.

AM Application Management. The application management component provides a means for a system administrator to control and configure applications and interfaces in a distributed system. The control functions consist of starting and stopping applications and their interfaces. Configuring applications consists of setting configuration information about the managed application and its interfaces.

AMBB Application Management Building Block. Starts, stops, and restarts CC Server and AL Servers.

AMGUI Application Management Graphical User Interface. Used to maintain application parameters.

AML Application Management Library

AM Server Application Management CORBA Server



Glossary

AP Application Platform

API Application Programming Interface are a set of standard software interrupts, calls, and data formats that application programs use to initiate contact with network services, mainframe communication programs, telephone equipment or program-to-program communications.

There are two types of API: public API which allows 3rd parties to write applications to interface with Nortel components, and private APIs which are provided to other Nortel development groups allowing them to write applications to interface with Nortel components.

Applet Java program that runs in a web browser; similar to an application but subject to the security restrictions of the browser.

Application Instance A realization of an Application Type on a specific host, possibly associated with one specific domain.

ATM Asynchronous Transfer Mode

Attribute A data property of an object class. An attribute has a value that defines characteristics of, or process for, an instance of an object in a class.

Attribute/Value Assertion A system of modeling management information using objects that have hierarchical names composed of attributes and values. The attribute is an integer or string representing the naming component, and the value is an integer of string representing the naming value.

AVA see Attribute/Value Assertion



Glossary

AWT Abstract Window Toolkit. A collection of graphical user interface (GUI) components implemented using native-platform versions of the component.

B

BB Building Block. A set of processes that has zero or more interfaces; specifically, a CORBA server that groups several CORBA objects. Functionality is accessible through the objects’ interfaces. The two main objects providing functionality to the BB are the managed interface and the managed process.

Basic Object Adapter The CORBA specification defines the BOA pseudo object in PIDL. The BOA’s main purpose is to allow an object server to interact with the Object Request Broker (ORB). A server process uses the BOA to tell the ORB when an object is ready to perform operations.

BOA See Basic Object Adapter

Blackboard Pattern Design pattern that includes a shared data area.

C

CA See ADK CORBA Adapter

CC Custom Commands

C++ language The object-oriented programming language in which NSP modules are written

CCBB Custom Commands Building Block

CCGUI Custom Commands Graphical User Interface used to maintain custom commands.



Glossary

CC Server Custom Commands CORBA Server.

CCUI Custom Commands User Interface.

Class A type that defines the implementation of a particular kind of object. A class definition defines instance and class variables and methods, as well as specifying the interfaces the class implements and the immediate superclass of the class. If the superclass is not explicitly specified, it is implicitly an object.

CLFI Common Language Facility Identifier

Client, thin A system that runs a very light operating system with no local system administration and executes applications delivered over the network.

Client/Server Application A LAN application that uses the resources or services of servers on the same or different LAN. The client is the application or hardware using the centralized services. The server is the application or hardware providing the centralized service.

A cooperative or distributed processing environment that collectively provides a single system or application view to the user.

Cluster A group of several menu items under the menu bar.

CM Configuration Management

CMISE Common Management Information Service Element, a component of Open Systems Interconnection (OSI)



Glossary

Compiler A program that converts programs in a high-level programming language into a language the computer understands

Configuration A set of options which can be dynamically for a process or an interface. For example, the number of clients allowed simultaneously.

Connection Reliability In the Event Port, a QoS property that specifies the reliability of the logical connections between the event channel and its clients. Possible settings are:

Best Effort: Upon restart from a failure of the process wihin which the event channel is executing, the logical connections to the event channel will not be retored.

Persistent: Upon restart from a failure of the process wihin which the event channel is executing, the logical connections between the event channel and the clients connected to the event channel at the time the failure occurred will be re-established.

Consumer A logical entity that receives events.

Coordinated Universal Time (UTC) The reference for official time used by all countries. Replaces Greenwich Mean Time (GMT)

CORBA Common Object Request Broker Architecture

CORBA Adapter (see ADK CORBA Adapter)

COS CORBA Common Object Services

CR Change Request

CWD Current Working Directory



Glossary

D

DA See Device Adapter

DBI Database Interface

Debugger A programme that identifies code errors

Dependency A relationship between two database objects where the existence of one object is necessary before the second object can be added.

Design Pattern A commonly recurring structure of communicating components that solves a general design problem within a particular context; smaller in scale than architectural pattern; independent of programming language.

Device Adapter a software package that includes the MDR Adapter (with a network element specific plugin implemented) It integrates new network elements into the Framework.

Device Adapter Development Kit a development kit used by integrators to develop their specific device adapter. It comprises the device adapter software (minus the plug-in), the required third party software, libraries and API documentation.

DIR Directory Service (LDAP)

Distinguished name A name that unambiguously identifies an object within an object hierarchy.

DLC Data Link Connection

DN Distinguished Name

DNS Directory Name Service



Glossary

Domain A set (possibly geographic) of resources associated with a family of building blocks (e.g., Fault management). A specific resource can only be in one domain at a time.

Doors Requirement Repository

E

EFD See Event Forwarding Discriminator

Environment A comprehensive integrated set of services that supports the development, use and maintenance of applications

Event Channel An intervening object that conveys events from suppliers to consumers without requiring suppliers to know about consumers or vice versa.

Event Delivery Model The model by which events are delivered in an event system using the “publish/subscribe” pattern.

Push/Pull Suppliers push events to the event channel, where events are pulled by consumers. The event channel stores events pushed by suppliers until consumers have pulled them. This is also known as Hybrid Push/Pull Model.

Push/Push Suppliers push events to the event channel and the event channel in turn pushes events to all registered consumers. This is also known as Canonical Push Model.

Pull/Push The event channel pulls events from the suppliers and then pushes events to the consumers. This is also known as Hybrid Pull/Push Model.

Pull/Pull Consumers pull events from the event channel and the event channel in turn pulls events from suppliers. This is also known as Canonical Pull Model.



Glossary

Event Forwarding Discriminator (EFD) Filter operation that returns the delta of information since the last query. For example, in the case of an alarm-based interface, if you get alarm information from a first EFD operation and you want to perform another EFD operation, only the new alarms since the last query are forwarded to you. The job of this event discriminator is to forward events to clients according to the discriminator as defined so that the user sees only the events wanted.

Event Port Interface An interface for consumers to request an event channel for receiving events. Each event port interface instance is associated with a maximum of one event channel.

Event Reliability In the Event Port, a QoS property that specifies the reliability of a transport for events between clients of the event channel and the channel. Possible setting are:

BestEffort Upon restart from a failure of the process within which the event channel is executing, no

attempt will be made to retransmit any events that had been buffered at the time of the failure occurred.

Persistent Upon restart from a failure of the process within which the event channel is executing, attempts will be made to retransmit any events that had been buffered at the time of the failure occurred.

The combination of “persistent” event reliability and “best effort” connection reliability has no meaning, as events cannot be delivered without logical connections to the clients being restored.

The combination of “persistent” event reliability and “persistent” connection reliability means each event is guaranteed to be delivered to all consumers registered to receive it at the time the event was delivered to the channel, within expiry limits.

EMS Element Management System. Allows addition of an element (such as Equinox) after deployment.



Glossary

ES Event System. The notification channel component is based on the definition of the CORBA event service defined by the Object Management Group (OMG). This definition is a response to the requirements by many applications for a more de-coupled inter-object communication model. Essentially, this model, which is based on the ‘publish/subscribe’ pattern, permits asynchronous communication between many suppliers and many consumers.

Export The act of placing an advertisement in the CORBA Trader

F

Factory Pattern Defines an interface for creating an object but lets subclasses decide which class to instantiate.

Fault A defect that causes a reproducible or catastrophic malfunction. (A malfunction is considered reproducible if it occurs consistently under the same circumstances.)

FCAPS Fault, Configuration, Accounting, Performance, and Security

FM Fault Management

FMBB Fault Management Building Block. A building block that provides a single point of access to fault management, and monitors and controls interfaces for alarm and event retrieval, as well as, providing protection status and control of interfaces for client applications.

fmMOA Fault Management Managed Object Agent. This was replaced in Framework 3.0 / ADK 4.1 by the ADK CORBA Adapter (see ADK CORBA Adapter)



Glossary

FQDN Fully Qualified Domain Name

FR Frame Relay

Framework A set of cooperating classes that makes up a reusable design for a specific class of software. A framework provides architectural guidance by partitioning the design into abstract classes and defining their responsibilities and collaborations. A developer customizes the framework to a particular application by subclassing and composing instances of framework classes.

G

GMT Greenwich Mean Time, the predecessor to Coordinated Universal Time

GNB Graphical Network Browser

GND Graphical Network Display (provides a resource browser and a layout editor)

GNDE Graphical Network Display Editor

GNE Graphical Network Editor

GMT Greenwich Mean Time

GUI Graphical User Interface. Refers to the techniques involved in using graphics, along with a keyboard and a mouse, to provide an easy-to-use interface to a program.

H

Help ID Help IDs are references to specific topics in a Help Volume. The available Help IDs are defined when the Help System is authored.



Glossary

Help IDs are volume specific, which means that they are not compatible with other named Help Volumes.

Help IDs and their mapping are defined in the JavaHelp map (.jhm) file, and can be associated with an application’s GUI components and used to provide context-sensitive help.

Help Volume An aggregation of files that constitutes the collection of help information for one or more plugins or subject areas. Typically, however, a Help Volume is a superset of the JavaHelp helpset concept. Essentially, a Help Volume is a jar file that contains one JavaHelp helpset and a text file (volumeName.txt) that contains the name of the Help Volume.

I

Implicit invocation Rather than invoking a procedure directly, a component announces an event. Other components in the system register interest in the event by associating its occurrence with a procedure. When the event is announced, the system invokes all procedures associated with the event.

IDL Interface Definition Language. CORBA abstract notation language used to define server Application Programmer Interfaces.

IIOP Internet Inter-ORB Protocol. A communications protocol developed by the OMG (Object Management Group) to extend the capabilities of CORBA-based Object Request Brokers (ORBs).



Glossary

The protocol allows ORBs created by different vendors to interoperate, and it supports the use of the Internet as its communication medium.

Implicit invocation Rather than invoking a procedure directly, a component announces an event. Other components in the system register interest in the event by associating its occurrence with a procedure. When the even is announced, the system invokes all procedures associated with the event.

Import The act of searching the CORBA Trader for a service provider that meets certain criteria

Inheritance The concept that a class automatically contains the variables and methods defined in its supertypes. The supertypes of a type are all the interfaces and classes that are extended or implemented by that type.

Interface A publicly advertised CORBA IDL which has a configuration (that is, a set of options which can be changed dynamically).

Interface Service Provider The object that provides the service advertised in the trader.

IOR Interoperable Object References

IP Internet Protocol

Internet Protocol

ITU-T A division of the International Telecommunications Union that specializes in setting standards for telecommunications. (Formerly CCITT—Consultative Committee on International Telephone and Telegraph.)



Glossary

J

JMS Java Message Service

JNI Java Native Interface

JTGO Java Telecom Graphic Objects (ILOG product)

JTGO Java Telecom Graphic Objects (ILOG product)

JWS Java Web Start

L

LA Launcher

Layout A tree representation of a particular hierarchical grouping of the network. Each node of a layout contains layout rendering information for displaying the group that it represents.

Logging and Tracing The ability to track the occurrence of certain events (such as loss and restoration of communications with a network element) and record them in a log file.

M

MFT Management Framework Technology group (formerly known as SES)

Managed Object Agent an interface between managed network elements and the Framework-based Management Solution. (older terminology - use Device adapter)



Glossary

Management Data Router Adaptor A software device that adapts NE-specific protocols into NSP.

Method A function defined in a class

MDR Management Data Router

MOA see Managed Object Agent

MOB Managed Object Base

MVC Model-View-Controller

MMVC Multi-level Model-View-Controller

MDI Multi-Document Interface

N

NDS Netscape Directory Server (used for password / user ID authentication)

NE See Network Element

Network Element (NE) a piece of equipment used in telecommunications networks, such as (for example) a switch, terminal, or router.

NM Network Model

Network Operations Center A centralized operations center that can manage a large number of widely dispersed NEs by means of links with a number of regional operations centers. Sometimes known as a NOC collector.

NMS Network Management System



Glossary

NNI Network Node Interface

NOC See Network Operating Center.

NPI New Product Introduction

NSP Network Services Platform

NTD Network Tree Display

O

OAM&P Operations, Administration, Maintenance and Provisioning

Object The principal building block of object-oriented programs. Each object is a programming unit consisting of data (instance variables) and functionality (instance methods).

Object Reference A CORBA object reference is a handle for a particular CORBA object implemented by a server. A CORBA object reference identifies the same CORBA object each time the reference is used to invoke a method on the object. A CORBA object may have multiple, distinct object references. Object references:

n are used by a client to make a request

n may be received in a response or obtained from the ORB

Object Request Broker (ORB) A CORBA software component used to connect a client application with the objects it wishes to use. The ORB does the following:

n sets up connection between client and server

n fires up servers if necessary

n provides for interoperability



Glossary

Observer Pattern Defines a one-to-many dependency between objects so that when one object changes state, all its dependencies are notified and updated automatically.

OMG Object Management Group

OPC Operations Controller Card

Orbixd A process which monitors and controls CORBA servers. Provided by IONA as a component of Orbix.

OSI Open Systems Interconnection

P

PEA Personal Event Assistant

Persistent Data is stored in a database independent of the server so that when the service availability is disrupted, the data is not lost.

PIOR Persistent Interoperable Object References

Plugin Module, code, or small application that adds functionality to a program.

POR Plan of Record

Properties Attributes of a resource. Not all resources have properties.

Q

QoS Quality of Service. In the Event Port feature, a set of performance parameters which can be set to indicate the delivery characteristics of event messages



Glossary

R

Regional Operations Center A centralized point from which a number of NEs in a region may be managed

Resource Type Previously known as matrix. A set of resources, their functions and permissions associated with one or more building blocks. It is possible for a building block to manage several resource types (e.g., SUMBB manages layouts and network elements)

Resources Whatever is managed by a building block (e.g., network elements, layouts, command sets, etc.). Resources can be defined in the network or in a Building Block. For example, if the resource is defined as a Network Element then it's existence is defined in the network, if the resource is a custom command set then it's existence is defined in the Custom Command Building Block.

RMBB Resource Management Building Block (old terminology ñ provided fault information on optical networks). This is now a component of TUMSBB.

RMI Remote Method Invocation. A protocol that defines communication between components in the client area and those in the server area. Allows one plug-in to be replaced with another that implements the same interface thus allowing the functionality to continue.

rmMOA Resource Management Managed Object Agent. This was replaced in Framework 3.0 / ADK 4.1 by the ADK CORBA Adapter (see ADK CORBA Adapter).

ROC See Regional Operations Center

RPC Remote Procedure Calls



Glossary

S

SA Service Activation

Sandbox A private namespace in which plugins run. Classes within a sandbox are local to the sandbox and may have the same name as a class outside of the sandbox without causing conflict.

SDE Software Development Environment

SDH Synchronous Digital Hierarchy. A group of fiber-optic transmission rates that provide the flexibility required to transmit many digital signals with different capacities. The SDH is equivalent to the ANSI SONET standard, and provides all the novel characteristics outlined for the SONET standard.

Service Enabling Solutions The organization responsible for Network Services Platform.

SES See Service Enabling Solutions.

Skeleton A minimal software infrastructure to which functionality can be added.

SMTP Simple Mail Transfer Protocol

SONET Synchronous Optical Network

SR Service Request

Subclass A class that is a special case of another class



Glossary

Subdomain Relationships between applications are defined in subdomains. All applications that reside in the subdomain of another application report to that application. (See Trading Domain.) Once the domain names have been set properly, you can define subdomains. Not all building blocks require the same subdomains. In fact, some applications do not have subdomains.

Subscribe The act of enabling event channel for sinking events

SUM Summary

SUMBB Summary Building Block

Supplier A logical entity that produces events

Swing A collection of graphical user interface (GUI) components that run uniformly on any native platform that supports the Java virtual machine. Because they are written entirely in the Java programming language, these components may provide functionality above and beyond that provided by native-platform equivalents.

System Help Library A directory containing all installed Help Volumes for the system, a master helpset file, a map file, and several configuration files. The System Help Library is generated the first time you run the Help Volume Installation tool.

T

Teaming Agreement An agreement between the Framework Advantage group and a solution delivery group for use of Framework-based Management Solutions.



Glossary

Thread The basic unit of program execution. A process can have several threads running concurrently, each performing a different job, such as waiting for events or performing a time-consuming job that the program doesn't need to complete before going on. When a thread has finished its job, the thread is suspended or destroyed.

TM Trail Management

TMBB Trail Management Building Block

TMCA Trail Management CORBA Adapter

TMN Telecommunications Management Network

Tracing See entry on Logging and Tracing

Trading Domain In order for applications to communicate with each other in a distributed platform using Orbix Trader, each application must have an identity. Each application’s identity is called a domain and has a unique name which the trader uses to identify the application.

The building blocks are functional units that can be installed and activated separately. A typical set of building blocks is one of each functional type. In a typical set, the different building blocks can all have the same domain name, or they can each have their own unique name. However, in the case of multiple instances of the same functional type, you must assign unique domain names to each instance. (See Subdomain.)

For a client to get to one of these domains, they must go to Orbix Trader. There may be a single instance of Orbix Trader on every single hardware box.



Glossary

So how does the client know which Trader to use? The Trading Domain encompasses all domains which are controlled by that Trader (usually all domains on a single box). The client then is pointed at the correct Trader from which the correct domain can be accessed.

Try/Catch (Java term) The "try" part tries to execute a statement. If the statement executes successfully, the next statement is tried. If a statement does not execute successfully, an exception is thrown. This is caught ("catch") and may then be written to a log.

TUMS Topology Universal Modeling Service (building block)

TUMSBB Topology Universal Modeling Service Building Block (provides nodal discovery and elementary network topology)

U

UI User Interface.

UAM Unified Alarm Manager

UDT Universal Date and Time

UML Universal Modeling Language

UNI User Network Interface

UNIX The operating system used by both the Sun and HP platforms of Framework.

Unpublish The act of disabling the event channel for producing events.

Unsubscribe The act of disabling the event channel for sinking events



Glossary

URL Uniform Resource Locator

User Group Any level in a user hierarchy above individual users. Users are members of user groups. All users in a user group have identical access control permission. Valid Users and User Groups are defined in the Certificate Authority (CA).

UTC See Coordinated Universal Time (UTC)

V

Versant Object Oriented database

VO Verification Office

XDR External Data Representation

X

xNI All Network Interfaces (i.e., both UNI and NNI)

.


Documents

ADK Developer Guide