ADK Developer Guide

Odyssey 3 Device Adapter Development Kit (ADK) Developers Guide
Issue 1.0 Draft May 2006 ADK Release 4.4
Management Integration Platform (MIP) Developer Guide
Notice
20012006 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/ .
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) Developers Guide is divided into the following chapters: Chapter 1, Introductiondescribes 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 configurationdescribes 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 tasksdescribes the development options and the scenarios for which the ADK can be used, provides an overview of the
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 capabilitiesdescribes 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 Adapterdescribes the steps you must perform to compile, package, and test the Device Adapter that you have developed. Appendix A, Allocation policyshows the classes, number of instances and the associated allocation policy that you should use when developing your Adapter plug-in.
Appendix B, Engineering informationhas been removed. For this information, see the Framework Engineering Guide, Engineering Considerations chapter. Glossarydefines the major terms and abbreviations used in this guide and throughout NSP.
Conventions and Feedback
Conventions The Device Adapter Development Kit (ADK) Developers 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.
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/
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 Functionality Architecture Engineering Limits
Location ADK Device Adapter Features on page 30 Architecture on page 22 Refer to the Engineering Considerations chapter in the Framework Engineering Guide For Further Information on page 8 Develop special alarm handling on page 138 Release Notes
Architect
Designer
Design & Integration Testing
X X X X
List of Operational Considerations Client request: Manual Alarm Clear; acknowledgement Development Environment requirements including Platform and 3rd party software and compiler requirements
X X
What elements are required to compile a DA Compiling and packaging your Device Adapter on page 175 plug-in?
Area of Interest What is available from the ADK API?
Location For Further Information on page 8 (see ADK API Reference) Downloading and installing the ADK on page 35 Configuring and sanitizing the test environment on page 47 and Developing the basic Device Adapter on page 73 Developing a Model Conversion File on page 148 Use the Compliance Tools on page 51 Developing resource and alarm capabilities on page 105 Refer to Partner Application Development Team (see the NSP Developers Guide - Chapter NSP Fault reference in For Further Information on page 8 Run the Device Adapter on page 53 Use the Compliance Tools on page 51 Architecture on page 22 Logging and tracing on page 103
Architect
Designer
Where to get support How to get started
Model Conversion Files and how to construct, package and deploy. How to test the plug-in Fault Information: How to model it Fault Information: What is the minimum information needed for the northside client? Fault Information: What information is expected from the various Framework components? How to run ADK components from the command line, bypassing AM. How to use the compliance tools. How do the DA components work? Overview of the various logs and how to control the logging level
X X X X X X
When we test a DA, what should the plug-in Logging and tracing on log? page 103
10
Area of Interest Resource information: How to model it
Location Developing a Model Conversion File on page 148
Architect
Designer
Resource Information: What is the minimum Establish communications with information needed for the northside the NE/EMS on page 114 client? Resource Information: What information is expected from the various Framework components? Plug-in sequence, initialization and event loop Handle OSI state changes on page 132 Developing the basic Device Adapter on page 73 and Developing resource and alarm capabilities on page 105
EMS resynchronization and plug-in recovery Developing resource and considerations alarm capabilities on page 105 How to convert your existing plug-in to use the latest ADK/FW features What source files should be included? Application Management of a plug-in For Further Information on page 8 (see ADK Release Notes) Compiling your Device Adapter on page 179 Specialize Init() on page 84 to Specialize Shutdown() on page 93 Packaging your Device Adapter on page 181
X
How to package and deliver a DA
11
Framework ADK Developers Guide
Table of Contents
Contents
1
Introduction
Architecture 22
ADK CORBA Adapters 24 Integration Server 26 Device Adapter 27
Configuring and sanitizing the test environment 47

Managing the Device Adapter 54 Starting and stopping the background processes 54
Configuring multiple Device Adapters 56

Process view 57 Component view 59 Assigning domains in a multi-DA environment 60
Advantages of using the ADK 29 ADK Device Adapter Features 30 Network element requirements 32 Platform and compiler requirements 33
Configuring multiple sub-domains 61

Configuration 63 Sample configuration file 63 Changing the number of subdomains 64 Synchronization with multiple subdomains 64 Replacing Device Adapters 64 Assigning Model Service domains 65
2
Installation and configuration
Downloading and installing the ADK 35
Release-specific installation or upgrade issues 37 Installing ADK 37 Installing a lightweight ADK 41 Third-Party Software Packages 42
Upgrading ADK 66 Uninstalling ADK 68
3
Development tasks
New NE Types 70
ADK files and directories 42 Sanitize the development environment 45
14

Contents
Develop an NE-specific Device Adapter 71 Develop a Model Conversion File 72
General development considerations 99

Required attributes 100 Error handling and exception policy 101 Logging and tracing 103
4
Developing the basic Device Adapter
Overview of Device Adapter basics development 74
Device Adapter base classes 79 Write a global function to create an MDRAdapterFactory instance 80 Specialize the MDRAdapterFactory class 81 Specialize the MDRAdapter class 82 Implement the constructor 84 Specialize Init() 84 Specialize SetupInitialConfig() 86 Specialize Reconfigure() 88 Using GetConfig() 91 Specialize Start() 91 Specialize Stop() 92 Specialize Shutdown() 93 Specialize Resynchronize() 95 Providing Automatic Restart 97 Adding capabilities to your plugin 98
Synchronization 104
5
Developing 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 116
Adding support for Easy.ON support bits 117
Perform initial alarm discovery 125 Call StartCB() 126 Develop the event loop 127
Handle NE events 129
15

Contents
Handle alarm events 130 Handle OSI state changes 132 Handle NE attribute changes 133 Fault/Resource Synchronization scenarios 134 Check for shutdown calls 137
7
Compiling and packaging your Device Adapter
Chapter overview 176
Develop special alarm handling 138

Handle manual alarm clear requests 139 Handle alarm acknowledge request 143 Handle service grade alarms 147
Directory Structure 177 Compiling your Device Adapter 179 Packaging your Device Adapter 181 Installing your packaged Device Adapter 182
6
Developing a Model Conversion File
Introduction to the Model Conversion File 149
Distinguished name 151 NSP Object Model 152 Name binding tree 154 Generic attributes 161 Network object mapping 162 MCF restrictions and limitations 163
A
Allocation policy 183
B
Engineering information 186
ADK platform requirements 187 ADK engineering limits 188
Glossary 189
Create the Model Conversion File for your plugin 165

Sample inm.map file (MCF) 173
16

List of Figures
List of Figures
Figure 1-1 Figure 2-1 Figure 2-2 Figure 2-3 Figure 4-1 Figure 4-2 Figure 4-3 Figure 4-4 Figure 4-5 Figure 4-6 Figure 4-7 Figure 4-8 Figure 4-9 Figure 4-10 Figure 4-11 Figure 4-12 Figure 5-1 Device Adaptation architecture 23 Multi-DA - Logical/Process View 57 Multi-DA - Component View 59 Multiple sub-domain configuration 62 Device Adapter lifestyle message sequence diagram 75 MDR factory and adapter class diagram 79 Sample code for init_mdr_factory() 80 Code example for inheriting the MDRAdapterFactory class 81 Code example for implementing the createMDRAdapter() method 81 Code example for implementing the MDRAdapter constructor 84 Sample code for specializing Init() 84 Code example for specializing SetupInitialConfig() 87 Code example for specializing Reconfigure() 90 Code example for specializing Stop() 93 Code example for Shutdown() 94 Code example for retrieving an invalid argument exception string 102 Simplified resource and alarm class diagram 108 17

List of Figures
Figure 5-2 Figure 5-3 Figure 5-4 Figure 5-5 Figure 5-6 Figure 5-7 Figure 6-1 Figure 6-2 Figure 6-3 Figure 6-4 Figure 6-5 Figure 6-6 Figure 6-7 Figure 6-7
Basic resource and alarm interactions diagram 110 Resynchronization diagram (following failure of JBoss or Model Service) 111 Code example for declaring a global variable 112 Code example for handling OSI state changes 132 Code example for handling NE Attribute changes 133 Code example for checking shutdown calls 137 Sample entries from a Model Conversion File 149 Managed object name binding tree 155 Sample mapping line 169 Mapping a line in the MCF to the Object Model 170 Default mapping of an object not specified in the MCF 171 Multi-level network object mapping 171 Sample inm.map file (1 of 2) 173 Sample inm.map file (2 of 2) 174
18
Framework - ADK Developers Guide

List of Tables
List of Tables
Table 4-1 Table 5-1 Table 5-2 Table 5-3 Table 5-4 Table 5-5 Table 6-1 Table 6-2 Table A-1 Table B-1 Specialization of the MDRAdapter base class methods 82 Required specialization for resource and alarm management capabilities 109 Support Bits Constraints 118 Events, objects, and methods in the event loop 128 Definition of event times 131 SupportBitConstants for manual alarm clear requests 139 Supported standard object classes 156 Supported generic object attributes 161 ADK allocation policy 183 ADK Engineering Limits 188
19
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 Frameworkbased 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.
Introduction
20
1
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
Any mention of Device Adapter in this document refers to Device Adapters created using the ADK.
Note:
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 NEs 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
AP
XDR CORBA G a te w a y CORBA
NSP
A D K C o rb a A d a p te r X M L -J M S
I n t e g r a t io n S e r v e r
X M L -J M S D e v ic e A d a p te r m a n a g e m e n t p ro to c o l
MCF
N E /E M S
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 recompositionattributes 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 servicesITU 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 NEs 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 southbound 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 librariesThese 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 pluginThis 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 BinaryThis is the component that is built when you compile the Adapter libraries from the ADK and the Adapter plug-in that you develop. MCFThe 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 Frameworkcompliant 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 reestablishment 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: Roguewaves SourcePro and Ionas 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

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.
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.
35
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.
36
Release-specific installation or upgrade issues Installing ADK
For any issues relating to installation or upgrades for specific releases, see the List of Operational Considerations document for the applicable Framework release. 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. 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).
Note:
37
To install the ADK development environment in the Default directory

1.
If you have not done so yet, install Framework on the target system. Login to the target system as the root user. 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
2. 3.
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.
38
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. Login as the loadbuild administrator. Enter the following script: pkgtrans -o /opt/nortel/packages/ NNadkdev.PKG /myloadbuild NNadkdev
2. 3.
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
39
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
40
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 This option changes the ADK dependency on the Orbix package: Framework does not install Orbix by default on this system.
Note:
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: /opt/nortel/PresideNSP/ current_NSPcommon/resources
41
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 42
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
43
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.
44
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
45
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.
46
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. 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.
Note:
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.
47
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 handson 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
Alternatively, you can use the SampleDeviceAdapter executable provided in the bin sub-directory.
Note: 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
48
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) Developers 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.
49
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)
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) Developers
Note:
50
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
51
run: ./current_adk/bin/fm_compl_tool -d <domainname>
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.
Note:
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>
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
Note:
52
-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.
53
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. If for any reason, you need to stop the ADK background processes, perform the following steps:
1.
Starting and stopping the background processes
From within the Application Management (AM) system, stop the ADK CORBA adapter. Invoke the script current_adk/bin/stopClean.sh
2.
To start the background processes, perform the following steps:

1.
Invoke the script current_adk/bin/startJProcs.sh Start the ADK CORBA adapter from the Application Management (AM) system.
2.
54
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 Resynchronizationsee 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. Then, wait 30 seconds after the Model Service starts (or restarts) before starting (or restarting) any Adapters (CA/DA).
2.
In the case of rapid successive restarts, follow the startup order in the above recommendation.
55
Configuring multiple Device Adapters
The Multi-DA feature allows two or more DAs to be coresident 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.
56
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
FM BB
( J a v a p ro c e s s )
TUMSBB
( C + + p ro c e s s ) 1 CORBA 1 ..*
one
CORBA
one
m any A D K C O R B A
m any
A d a p te r
(J a v a p ro c e s s ) m a n y X M L -J M S 1 ..*
In te g ra tio n S e rv e r
(J a v a p ro c e s s )
one
one
X M L -J M S 1 ..* m a n y < < d e v e lo p e d u s in g > >
D e v ic e A d a p te r
(J a v a o r C + + p r o c e s s )
ADK
m any m any
1 ..*
m any
1 ..*m a n y 1 ..*
EM S
NE
57
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
58
Component view
Figure 2-2
Figure 2-2 provides a component view of the multi-DA feature and illustrates the package dependencies.
Multi-DA - Component View

N a kd v Nd e d ve p d w e lo e ith h a e file edr s d cu e ta n o m n tio sa p D so rce m le A u
D elo ent Packag ev pm e
D A
N a krt Nd C R AA a te ja O B dp r r In g tio S rve ja te ra n e r r C + sh re lib rie + a d ra s scrip ts co p n to ls m lia cy o
R untim P age e ack
d p y dw e lo e ith F ew rk ram o S ftw o are P ackages
N o ix N rb
N jre N
N jb ss N o
N n co N sp re
N n cm N sp n
N ro w ve N g a
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,
59
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 subdomain. 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 subdomain (for south bound association with the Device Adapter) say "dal". You cannot change the domain for the duration of this DA instance existence.
Note:
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.
60
Configuring multiple sub-domains
Configuring multiple subdomains
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.
61
Figure 2-3
Multiple sub-domain configuration
Building Blocks
CA 1
CA 2
CA 3
MS 1
MS 2
MS 3
DA 1
DA 2 DA 3
DA 4
CACORBA Adapter MS Model Service DADevice Adapter BBBuilding Block
62
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 subdomains 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.
63
Changing the number of subdomains
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. In this multiple sub-domain configuration, the CA domain will not be synchronized until all individual subdomains 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.
Synchronization with multiple subdomains
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.
64
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.
65
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.
66
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.
67
Uninstalling ADK
Uninstalling ADK
To uninstall ADK (development, runtime, or both), invoke the following Framework uninstall script: /opt/nortel/PresideNSP/ 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)
68
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
Development 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 NEspecific 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 NEspecific 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. Developing resource and alarm capabilities, covers: specialization of the Start() method, including:

2.
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
Development tasks
71
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 Frameworkbased Management Solution, which is covered in chapter, Developing a Model Conversion File.
Development tasks
72

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.
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.
74
Figure 4-1
Device Adapter lifestyle message sequence diagram
*Resynchronize() and ResynchronizeStart() in Figure 4-1are part of the DA life cycle only following a JBoss or Model Service (MS) failure.
Note:
75
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. Application Manager calls the DA library. DA library calls the init_mdr_factory() method in the DA, which instantiates the specialized MDRAdapterFactory. DA library calls createMDRAdapter() of the specialized MDRAdapterFactory which instantiates the specialized MDRAdapter. DA library calls the Init() method, giving the specialized MDRAdapter object access to command line arguments. 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. DA library calls the Reconfigure() method, which validates the values and implements any configuration parameters set in the Application Manager. User clicks on the Activate button in the Application Manager GUI with the interface of the DA process highlighted. Application Manager calls the DA library.
2. 3.
4.
5.
6.
7.
8.
9.
76
10.
DA library calls the MDRAdapter::Start() method. DA performs initial resource and alarm discovery. DA calls MDRAdapter::StartCB() method before entering an event loop. 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.) 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. Once resynchronization is ready to begin, the user adapter implementation calls MDRAdapter::ResynchronizeStart to reenable the flow of events. User clicks the Deactivate button in the Application Manager GUI with the interface of the DA process highlighted. Application Manager calls the DA library. DA library calls the Shutdown() method, which communicates to the resource and alarm event loop that it must exit, then performs any required cleanup.
11. 12.
13.
14.
15.
16.
17. 18.
77
19.
DA calls the MDRAdapter::EndCB() method to communicate to the DA library that the event loop has exited. User clicks on the Stop button in the Application Manager GUI while the DA instance is highlighted. Application Manager calls the DA library. DA library calls the Shutdown() method. The Shutdown() method communicates to the Start() methods event loopsif they are still runningthat they must exit, then performs any required cleanup. DA calls the MDRAdapter::EndCB() method to communicate to the DA library that the event loop has exited.
20.
21. 22.
23.
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 Develop a specialization of the MDRAdapterFactory class that creates an instance of the specialized MDRAdapter class. Develop a specialization of the MDRAdapter class that implements lifecycle and message handling methods.
2.
3.
78
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
MDRProcAdminFactory
MDRProcessAdmin
<<Singleton>> MDRAdapterFactory
<<instantiate>>
MDRAdapter
MyMDRAdapterFactory
MyMDRAdapter
79
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.
void init_mdr_factory() { new MyMDRAdapterFactory(); }
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.
80
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
class MyMDRAdapterFactory: public MDRAdapterFactory { public: MyMDRAdapterFactory() { cout << "MyMDRAdapterFactory constructor" << endl; } ~MyMDRAdapterFactory() { cout << "MyMDRAdapterFactory destructor" << endl; } private: virtual MyMDRAdapterFactory*
2.
In the source code file, provide implementation for the createMDRAdapter method.
Figure 4-5
Code example for implementing the createMDRAdapter() method
MDRAdapter* MyMDRAdapterFactory::createMDRAdapter() { ALG_TRACER(gAlgCLogger_,"MDRAdapter::createMDRAdapter()"); return new MyMDRAdapter(); }
81
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
Method Init()
Specialization of the MDRAdapter base class methods

Purpose Called by the DA library to provide command line arguments used to start the DA process. Specialization Optional. Provides implementation to parse and process command line options (if any). Can perform any onetime initialization processing.
SetupInitialConfig Called by the DA library to retrieve Mandatory.Provides implementation () initial configurations that are sent to to return application-specific initial Application Management. configurations to be sent to Application Management client. Reconfigure() Called by the DA library when the application is reconfigured by Application Management. Called by the DA library when a user clicks on the Activate button in AMGUI with the Adapter process interface selected. Mandatory. Provides implementation to accept or reject the parameters reconfigured by a user in Application Manager client. Mandatory. Contains resource and alarm discovery and event-based reporting. This is covered in the chapter, Developing resource and alarm capabilities on page 105. Mandatory. Provides implementation to suspend the reporting of events. The Stop() method must send a signal to the Start() method to halt reporting.
Start()
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.
82
Table 4-1
Method
Specialization of the MDRAdapter base class methods (Continued)

Purpose Called by the DA library when a user clicks on the Stop button in AMGUI. Specialization 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.
Shutdown()
Resynchronize()
Called when the ADK Library Optional. Provides implementation to detects a resynchronization resynchronize the network Model condition (failure of JBoss or Model used by the ADK. Service).
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
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.
83
Implement the constructor

Figure 4-6
See Figure 4-6 below for an example of the implementation of the MDRAdapter constructor.
Code example for implementing the MDRAdapter constructor
MyMDRAdapter::MyMDRAdapter() { myAdapter_ = this; // initialize stop_ and shutdown_ stop_ = FALSE; shutdown_ = FALSE; }
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()
void MyMDRAdapter::Init( int argc, char * argv[]) { for( int i = 0; i < argc ; i++) cout << "argv[" << i << "] is: " << argv[i] << endl; }
84
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()
85
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.
86
Figure 4-8
Code example for specializing SetupInitialConfig()
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); } }

MDRProcessAdmin::SetupInitialConfig() MDRAdapter::SetupInitialConfig() AdapterConfig
87
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. 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 restarted for the change to take effect.
4.
88
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.
89
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 attributes 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); } }
90
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.
91
Specialize Stop()
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.
Note:
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.
92
Figure 4-10 Code example for specializing Stop()
void MyMDRAdapter::Stop() { // Inform main event loop to stop stop_ = TRUE; EndCB(); }

MDRAdapter::Start() MDRAdapter::EndCB()
Specialize Shutdown()
For DAs developed using ADK 4.x, this is the only method used to initiate the stop process.
Note:
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
93
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()
void MyMDRAdapter::Shutdown() { // Inform main event loop to shut down. shutdown_ = TRUE; EndCB(); }

MDRAdapter::Shutdown() MDRAdapter::Start() MDRAdapter::EndCB()
94
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. 2. 3.
Perform clean-up action, if necessary. Acquire the current state of the network (resources). Call ResynchronizeStart() when you are ready to propagate the complete state of the network. Send resource and alarm events. Call PushDomainSynchronized() (see Figure 5-3 on page 111 for an overall view of the resynchronization lifecycle).
4. 5.
95
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.
96
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
97
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.
98
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
An additional general development issue is allocation policy, which is documented in the Appendix, Allocation policy on page 183.
Note:
99
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
100
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
101
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
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! }
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
102
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
103
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 Developers Guide.
104

This chapter describes the steps required to add resource and alarm management support to your Device Adapter (DA). 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.
Note:
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 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.
107
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()
AdapterNeEnrol
(from Model Binding Classes)
AdapterNeDeEnrol
AdapterAlarm
AdapterOsiStateEvent
AdapterAttributeValue Event
MyMDRAdapter
108
Table 5-1
Method Start()
Required specialization for resource and alarm management capabilities

Purpose 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. Specialization Provides implementation for initial NE discovery, and the NE event and fault management loop. 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. 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.
HandleAlarm Called by the DA library in response to a ClearRequest() manual alarm clear request, if the NE/EMS needs to be notified of the clear request and consequently has to handle the request. HandleAlarmAck Called by the DA library in response to an Request() alarm acknowledgement, if the NE/EMS needs to be notified of the request and consequently has to handle the request.
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
109
Figure 5-2
Basic resource and alarm interactions diagram
110
Figure 5-3
Resynchronization diagram (following failure of JBoss or Model Service)
Adapter Libraries
Adapter plugin
NE/EMS
Resynchronize() Clean up and prepare to resynchronize ResynchronizeStart() (ready to resynchronize) Retrieve NE data NE data from network PushEnrol() PushDeEnrol() PushNeUnknownStatus() Alarm messages from network PushAlarm() PushDomainSynchronized()
111
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.
// Initialize class variables RWBoolean MyMDRAdapter::stop_ = FALSE; RWBoolean MyMDRAdapter::shutdown_ = FALSE;
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.
112
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. 2. 3. 4.
Establishes connections to the NE or EMS. Performs initial NE discovery. Performs initial alarms discovery. Calls StartCB() to inform the DA library that the plugins resource and alarm event loop is starting. Starts the main event loop.
5.
For more information, see the ADK API Reference:

MDRAdapter::Start() MDRAdapter::StartCB()
For an example of specializing the Start() Method, please refer to the SampleDeviceAdapter (adk*/resources/src/plugin/SampleMDRAdapter.cxx)
Note:
113
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.
114
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. 2.
Allocate an AdapterNeEnrol instance. Fill in the AdapterNeEnrol object by calling the appropriate set method. For detailed information on how to set those values, refer to the AdapterNeEnrol class in the ADK API Reference.
Note:
3.
Push the AdapterNeEnrol object up to the DA library by calling PushEnrol(). Deallocate the AdapterNeEnrol object.
4.

AdapterNeEnrol MDRAdapter::PushNEUnknownStatus() MDRAdapter::PushEnrol() SupportBitConstants.hxx
115
Add vendor-specific information
Add vendorspecific 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
116
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
117
Table 5-2
Bit # XDR Definition
XDR_NE_SUPP ORT_PROTECT ION
Support Bits Constraints

Characteris tics when OFF
Autodiscovered links will not appear.
Characteristics when ON
Auto-discovered links will appear.
Ba sic
Comments/ Exceptions
Enables traffic display.
No
XDR_NE_SUPP ORT_SHELF_VI EW
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.. Login to NE menu entries appear black (enabled) Query Performance Statistics item within the Performance menu of gnbrowse appears black (enabled)
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.
XDR_NE_SUPP ORT_DIRECT_ NE_LOGIN
XDR_NE_SUPP ORT_PM
XDR_NE_SUPP ORT_INVENTO RY
Query Equipment Inventory item within the Configuration menu appears black (enabled).
Login to NE menu entries appear gray (disabled) Query Performance Statistics item within the Performance menu of gnbrowse appears gray (disabled) Query Equipment Inventory item within the Configuration menu appears gray (disabled).
Yes
Used by OPC based products. Should be part of basic support.
No
When ON bit #12 should be ON. No This needs NE bit #6 to be enabled as well.
118
Table 5.2 continued...

Bit # XDR Definition Characteristics when ON
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). Disables x session for network elements. Not used by OPC based products. Disables character session for network elements. Not used by OPC based products. Show Connections item within the Configuration , link and nodal menus of gnbrowse appear gray (disabled).
Basic
XDR_NE_SUPP ORT_SLG
No
When ON bit #12 should be ON.
XDR_NE_SUPP ORT_X_SESSIO N
Enables x session for network elements. Not used by OPC based products.
Yes
Basic login for non-OPC products
XDR_NE_SUPP ORT_CMT_SES SION
Enables character session for network elements. Not used by OPC based products.
Yes
XDR_NE_SUPP ORT_CONNECT ION_MGMT
Show Connections item within the Configuration, link and nodal menus of gnbrowse appear black (enabled).
No
10
XDR_NE_SUPP ORT_INA_DATA
No
Not used within the context of the gnbrowse/gnconf ig.
119

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). Used within remote inventory. The PSC dialog will open in a read-only mode where switch commands are not allowed (i.e. the combo boxes are disabled). Show PM Thresholds item within the Performance menu of gnbrowse appears gray (disabled). Disables x session for network elements. Not used by OPC based products.
Basic
The XDR_MOPC_SU PPORT_FACILI TY_PROVISION ING must be ON as well to enable facility provisioning. Used within remote inventory. Should be ON if bit #5 or #6 is ON.
11
XDR_NE_SUPP ORT_FACILITY_ PROVISIONING
No
12
XDR_NE_SUPP ORT_CASE_INS ENSITIVE_INVE NTORY_FILTER
Used within remote inventory.
No
13
XDR_NE_SUPP ORT_PROTECT ION_CONTROL
The PSC dialog will open allowing switch commands to be sent to the OPC.
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_SUPP ORT_PM_THRE SHOLD
Show PM Thresholds item within the Performance menu of gnbrowse appears black (enabled).
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_SUP PORT_X_SESSI ON
Enables x session for network elements. Not used by OPC based products.
Yes
120
Bit #
XDR Definition

Disables character session for network elements. Not used by OPC based products. Disables Web UI support.
Basic
16
XDR_SNC_SUP PORT_CMT_SE SSION
Enables character session for network elements. Not used by OPC based products.
Yes
17 18 19
XDR_NE_SUPP ORT_WEB_UI XDR_NE_SUPP ORT_ADAPTER XDR_NE_SUPP ORT_UE9K XDR_NE_SUPP ORT_TROUBLE _TICKETING XDR_NE_SUPP ORT_ALARM_S TATE XDR_NE_SUPP ORT_MANUAL_ CLEAR XDR_NE_SUPP ORT_UE9R
Enables Web UI support.
No Enables UE9000 support. Disables UE9000 support. No
Non-OPC based.
20
No Enables alarm state. Enables alarm manual clear Enables UE9000 support. Disables alarm state. Disables alarm manual clear Disables UE9000 support.
This bit is not used. non-OPC based network elements. non-OPC based network elements.
21
No
22
No
23
No
121

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. Power management menu items within OSV appear black (enabled)
Basic
24
XDR_NE_SUPP ORT_OSV
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_SUPP ORT_OPM
26
XDR_NE_SUPP ORT_RMINV_CI
Allows request for the inventory i/f of RMBB.
27
XDR_NE_SUPP ORT_RMTTP_C I
Allows request for the TTP i/f of RMBB.
Power management menu items within OSV appear gray (disabled) Disallows requests for the inventory i/f of RMBB. (exception is thrown) Disallows requests for the TTP i/f of RMBB. (exception is thrown)
No
Since this application is launched within OSV, OSV must be enabled to run this. Applicable as of XDR major version 14 only.
No
No
Applicable as of XDR major version 14 only.
122
Bit #
XDR Definition
XDR_NE_SUPP ORT_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) Disallows requests for the TTP i/f of PMBB. (exception is thrown) Disallows requests for the threshold i/f of PMBB. (exception is thrown)
Basic
28
No
29
XDR_NE_SUPP ORT_PMTTP_CI
Allows request for the TTP i/f of PMBB.
No
30
XDR_NE_SUPP ORT_PMT_CI
Allows request for the threshold i/f of PMBB.
No
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&sor t=name
123

SupportBitConstants.hxx AdapterNeEnrol::addAddedVendorSpecificInfo AvaType
Please refer to the SampleDeviceAdapter for examples of vendor-specific information. This may be found at:
Note: Note:
adk*/src/plugin/SampleMDRAdapter.exx
124
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. 2.
Allocate an AdapterAlarm instance. Fill each AdapterAlarm object by calling the appropriate set method. Push each AdapterAlarm object up to the Adapter libraries by calling PushAlarm(). Deallocate each AdapterAlarm instance.
3.
4.

AdapterAlarm MDRAdapter::PushAlarm()
Additional optional handling of alarms is described in the section Develop special alarm handling on page 138.
125
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().
126
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.
127
Table 5-3
Event NE added NE deleted
Events, objects, and methods in the event loop

Object AdapterNeEnrol AdapterNeDeEnrol AdapterOsiStateEvent Method PushEnrol() PushDeEnrol() PushOsiStateEvent()
Change in NE operational state Add new attribute(s) or change existing attribute(s) Lost or restored communications Alarm raised Alarm cleared
AdapterAttributeValueEv PushAttributeValueEvent ent () NE object ID (a list of PushNEUnknownStatus() AvaType objects) AdapterAlarm AdapterAlarm PushAlarm() PushAlarm()
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. For more information, please refer to the SampleDeviceAdapter.
Note:
128
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. 2.
Allocate an AdapterNeDeEnrol instance. Fill in the AdapterNeDeEnrol object by calling the appropriate set method. Push the AdapterNeDeEnrol object up to the DA library by calling PushDeEnrol(). Deallocate the AdapterNeDeEnrol object.
3.
4.

AdapterNeDeEnrol MDRAdapter::PushNEUnknownStatus() MDRAdapter::PushDeEnrol()
129
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. 2. 3.
Create an AdapterAlarm object. Fill it with the alarm information. Call pushAlarm() method on the MDRAdapter class.
For alarm clearing events For each alarm clear event, you must do the following:
1. 2.
Create an AdapterAlarm object Fill it with the alarm information. In particular, set the correlated notification Ids for clear alarms using the setCorrelatedIds method to ensure that when
130
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
Event time raise
Definition of event times

Definition 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. 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. 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. The time of the state change usually obtained from the NE or EMS
clear
attribute value change state change
131
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. 2.
Allocate an AdapterOsiStateEvent instance. Fill each AdapterOsiStateEvent object by calling the appropriate set method. Register each AdapterOsiStateEvent object with the DA library by calling PushOsiStateEvent(). Deallocate each instance.
3.
4.
The code example below illustrates this behavior.

Figure 5-5 Code example for handling OSI state changes
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);

AdapterOsiStateEvent MDRAdapter::PushOsiStateEvent()
132
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 *myAVCEvent = new AdapterAttributeValueEvent(); AvaType* vendorAva = new AvaType("manualClearNeedsEMS", TRUE); myAVCEvent->addNewAdditionalAttribute(ntNTDefined AttributeIds_vendorSpecificInfo_C,vendorAva); _myAdapter->PushAttributeValueEvent(myAVCEvent);

AdapterAttributeValueEvent addNewAdditionalAttribute() addNewAttribute() MDRAdapter::PushAttributeValueEvent()
133
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.
134
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. 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.
Note:
For further information on the re-synchronization process, please refer to the NSP Developers Guide.
Regaining communications with an NE When the DA process regains communications with the NE:
1.
Call PushNEUnknownStatus(ne_name, time, FALSE). Call pushAlarm() for all active alarms against that NE.
2.
135
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. Call pushAlarm() for all active alarms for all NEs managed by that EMS.
2.

MDRAdapter::PushNEUnknownStatus() MDRAdapter::pushAlarm()
136
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 loop while(!( shutdown_ )) { try { ...
137
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
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.
Note:
138
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.
Table 5-5
SupportBitConstants for manual alarm clear requests

Explanation
ADK SupportBitConstant
ADK_NE_SUPPORT_MANUAL_CLEAR_NE Manual Clear of alarm from the framework and EMS EDS_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
The above support bits are found in "SupportBitsConstants.hxx"

Note:
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
139
MDRAdapter::HandleAlarmClearRequest(AdapterAlar m * 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:
myEnrol = new AdapterNeEnrol(); . . . AvaType *vendorInfo = newAvaType(ADK_NE_SUPPORT_MANUAL_CLEAR , TRUE); myEnrol->addAddedVendor SpecificInfo(vendorInfo); delete vendorInfo;
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:
myEnrol = new AdapterNeEnrol(); . . . AvaType *vendorInfo = new AvaType(ADK_NE_SUPPORT_MANUAL_CLEAR_NEEDS_EMS, TRUE); myEnrol->addAddedVendorSpecificInfo(vendorInfo);
This specifies that the plugin will not be notified:
140
AvaType *vendorInfo = new AvaType(ADK_NE_SUPPORT_MANUAL_CLEAR_NEEDS_EMS, FALSE); 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.
AvaType *vendorInfo = new AvaType (ADK_ALARM_SUPPORT_MANUAL_CLEAR , TRUE); myAlarm->addAddedVendorSpecificInfo (vendorInfo); delete vendorInfo;
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:
void MDRAdapter::HandleAlarmClearRequest (AdapterAlarm* alarm_handle, ActionTypeEnum action_type);
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. 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:
Note:
141
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);
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. 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.
Note:

AvaType MDRAdapter::HandleAlarmClearRequest()
142
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. 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.
Note:
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.
143
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:
void MDRAdapter::HandleAlarmAckRequest (AdapterAlarm* alarm_handle, ActionTypeEnum action_type);
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){ alarm_handle->setAcknowledgementStatus(FALSE); }
144
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:
alarm_handle->addAddedVendorSpecificInfo( myAva = new AvaType("VendorSpecific2", "DEF")); delete myAva;
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.

Note:

AvaType MDRAdapter::HandleAlarmAckRequest() AdapterAttributeValueEvent
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 vendorspecific information, this information will over-write
Note:
145
ALL existing vendor-specific information. If it is decided to include vendor-specific information, then ALL vendor-specific information must be included.
146
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;
147

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.
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
NW EM Shelf - network $NW, managedElement $EM, equipmentHolder $Shelf NW EM AtmIf Vcc - network $NW, managedElement $EM, vpTTPBidirectional $AtmIf, vcCTPBidirectional $Vcc NW EM Shelf Card Port - network $NW, managedElement $EM, equipmentHolder $Shelf, circuitPack $Card
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). 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.
150
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.
151
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 NonStandardized 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.
152
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.
153
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. 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).
Note:
154
Figure 6-2
Managed object name binding tree
network managedElement
vcTTP Bidirectional interNNI IntraNNI Uni
tcAdaptorTTPBidirectional vpTTPBidirectional vpCTPBidirectional vcCTPBidirectional
vc4TTPBidirectional msTTPBidirectional e3TTPBidirectional e1TTPBidirectional ds3LineTTPBidirectional ds1LineTTPBidirectional electicalSPITTPBidirectional and optical SPITTPBidirectional rsTTP Bidirectional vc11TTPBidirectional ds3LTTPBidirectional vc12TTPBidirectional vc2TTP Bidirectional sdhMSprotectionGroup sdhMSprotectionUnit sdhBLSRProtectionGroupBCR ds1PathTTPBidirectional tug3Bidirectional ds3PathTTPBidirectional tug2Bidirectional ds1LineTTPBidirectional tu12CTPBidirectional msTTPBidirectional augBidirectional sdhBLSRProtectionUnitBCR au4CTPBidirectional au4CTPBidirectional tu2CTP Bidirectional tu3CTP Bidirectional equipmentHolder equipment
circuitPack
vc3TTPBidirectional vc4TTPBidirectional
tu11CTPBidirectional
155
Table 6-1
Supported standard object classes
Managed Object Classused in the inm.map file network equipment managedElement software connectionTerminationPointBidirectional connectionTerminationPointSink connectionTerminationPointSource terminationPoint crossConnection fabric gtp mpCrossConnection namedCrossConnection namedMpCrossConnection tpPool alarmSeverityAssignmentProfile connectionR1 pipe fabricR1 managedElementR1 equipmentR1 softwareR1 circuitPack rsTTPSource rsCTPBidirectional rsCTPSink rsCTPSource circuitEndPointSubgroup equipmentHolder networkR1 managedElementComplex au3CTPBidirectional au3CTPSink au3CTPSource au4CTPBidirectional augSink augSource electricalSPITTPBidirectional electricalSPITTPSink electricalSPITTPSource msCTPBidirectional msCTPSink msCTPSource msTTPBidirectional msTTPSink opticalSPITTPBidirectional opticalSPITTPSink opticalSPITTPSource rsTTPBidirectional rsTTPSink vc12TTPSink vc12TTPSource vc2TTPBidirectional vc2TTPSink
156
Table 6-1
Supported standard object classes (Continued)
Managed Object Classused in the inm.map file sdhNE tu11CTPBidirectional tu11CTPSink tu11CTPSource tu12CTPBidirectional tu12CTPSink tu12CTPSource tu2CTPBidirectional tu2CTPSink tu2CTPSource tu3CTPBidirectional tu3CTPSink tu3CTPSource tug2Bidirectional tug2Sink tug2Source tug3Bidirectional tug3Sink tug3Source vc11TTPBidirectional vc11TTPSink vc11TTPSource vc12TTPBidirectional ds1CTPSource ds1LineTTPBidirectional ds1LineTTPSink ds1LineTTPSource vc2TTPSource vc3TTPBidirectional vc3TTPSink vc3TTPSource vc4TTPBidirectional vc4TTPSink vc4TTPSource protectedTTPBidirectional protectedTTPSink protectedTTPSource protectionGroup protectionUnit sdhMSProtectionGroup sdhMSProtectionUnit unprotectedCTPBidirectional unprotectedCTPSink unprotectedCTPSource connectionProtectionGroup connectionProtection mpConnectionProtection sncpFabric ds1CTPBidirectional ds1CTPSink objectDeletionRecord relationshipChangeRecord securityAlarmReportRecord stateChangeRecord
157
Table 6-1
Managed Object Classused in the inm.map file ds1PathTTPBidirectional ds1PathTTPSink ds1PathTTPSource ds3CTPBidirectional ds3CTPSink ds3CTPSource ds3LineTTPBidirectional ds3LineTTPSink ds3LineTTPSource ds3PathTTPBidirectional ds3PathTTPSink ds3PathTTPSource ringMapBCR sdhBLSRProtectionGroupBCR sdhBLSRProtectionUnitBCR alarmRecord attributeValueChangeRecord discriminator eventForwardingDiscriminator eventLogRecord log logRecord objectCreationRecord nxE0CTPBid atmAccessProfile atmCrossConnection atmFabric system top problemRecord thresholdData historyData LayerNetwork Subnetwork SubnetworkConnection Link LinkConnection ManagedNetwork Matrix NetworkTTP_Source NetworkGroupSource NetworkCTP_Source NetworkTTP_Sink NetworkGroupSink NetworkCTP_Sink NetworkTTP_Bi NetworkGroupBi NetworkCTP_Bi NetworkCTP NetworkTTP vpTTPBidirectional atmLink atmLinkConnection atmLinkTP
158
Table 6-1
Managed Object Classused in the inm.map file atmMpFabric cellHeaderAbnormalityLogRecord cellLevelProtocolCurrentData cellLevelProtocolHistoryData ds3PLCPPathCTPBidirectional ds3PLCPPathCTPSink ds3PLCPPathCTPSource ds3PLCPPathTTPBidirectional interNNI intraNNI latestOccurrenceLog multipointBridge tcAdaptorCurrentData tcAdaptorHistoryData tcAdaptorTTPBidirectional uni upcNpcCurrentData upcNpcHistoryData vcCTPBidirectional vcTTPBidirectional vpCTPBidirectional e4TTPBidirectional e3CTPSink e3CTPSource e3CTPBidirectional e3TTPSink e3TTPSource atmNetworkAccessProfile atmNetworkCTP atmNetworkTTP atmNetworkTrafficDescriptorProfile atmRoutingProfile atmSubnetwork atmSubnetworkConnection atmSubnetworkTP vcLayerNetworkDomain vpLayerNetworkDomain pPITTPBidirectional pPITTPSink pPITTPSource ePDHTTPSink ePDHTTPSource ePDHTTPBidirectional e4CTPSink e4CTPSource e4CTPBidirectional e4TTPSink e4TTPSource g855network g855adminDomain g855basicLayerNetworkDomain g855basicSubNetwork g855link g855linkConnection
159
Table 6-1
Managed Object Classused in the inm.map file e3TTPBidirectional e2CTPSink e2CTPSource e2CTPBidirectional e2TTPSink e2TTPSource e2TTPBidirectional e1CTPSink e1CTPSource e1TTPSink e1TTPSource e1TTPBidirectional jt2TTPBidirectional frsCarrierAccess frsDLCCTPBid frsIciL2PathTTPBid frsSubscriberAccess frsUniL2PathTTPBid nxDs0CTPBid troubleTicketReport e1CTPBid interface g855networkCTPBidirectional g855networkCTPSink g855networkCTPSource g855networkTTPBidirectional g855networkTTPSink g855networkTTPSource g855node g855subNetworkConnection g855topologicalPoint p12CTPSource p12CTPBidirectional p31CTPSink p31CTPSource p31CTPBidirectional p4CTPSink p4CTPSource p4CTPBidirectional p12CTPSink msTTPBidirectional ds1LineCTPBid
160
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
Object
Supported generic object attributes

Attribute EMLAddress NEAddress Purpose Represents the EML network management entities IP address. Useful for pass-through. Represents the IP address of the actual switch. Useful for direct trouble-shooting access to the switch. Representing the native name of the object on the native EML system. Useful for queries on the EML system.
managedElement
all objects
NativeName
161
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 AVAsone 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.
162
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 plugins 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 SampleDeviceAdapter, you will also need to develop your own MCF.
163
1.3.5.6.8.1.32.41.2.3.3 or 42 crest1 43 3 118 mapper2 are not supported.
164
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.
165
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.
Note:
The contents of the sample inm.map file are shown in Figure 6-7 on page 173 and page 174. 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.
Note:
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. Find name for each component of the objects DN in Table 6-1 on page 156. 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.
2.
3.
166
The plugin objects DN has to be mapped into the platforms objects DN. Each AVA in the plugin objects naming structure is a parameter to be passed into the platforms objects DN.
4.
Create a mapping line in your MCF.
Creating a Mapping Line in the MCF A mapping line consists of the plugin objects name structure followed by the parameterized platform objects name structure, separated by a hyphen. For example:
NW EM Eq - network $NW, managedElement $EM, equipment $Eq
plugin objects name structureis a series of parameterized AVAs, each separated by a space. For example: NW EM LP DS3 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.
Note:
167
As an example of this, the following tokens are valid:

NW EM Eq Eq1 Eq2 - network $NW, managedElement $EM, equipment $Eq, equipment $Eq2 equipment $Eq1,
Whereas the following tokens are not valid:

NW EM Eq Eq Eq - network $NW, managedElement $EM, equipment $Eq, equipment $Eq, equipment $Eq
parameterized NSP platforms objects name structureconsists 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 plugins object.
For example:
network $NW, managedElement $EM, ds3LineTTPBidirectional $LP $DS3
168
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:
network managedElement ds3LTTPBidirectional
There is one more AVA in your plugins object than there is in the corresponding NSP object. Using Table 6-1 on page 156 the full names of the AVAs are:
network, managedElement, ds3LineTTPBidirectional
In the sample MCF there is a mapping line for this object, shown below:
Figure 6-3
Sample mapping line

- network $NW, managedElement $EM, ds3LineTTPBidirectional $LP $DS3
NW EM LP DS3
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.
169
Figure 6-4
Mapping a line in the MCF to the Object Model

- network $NW, managedElement $EM, equipmentHolder $Shelf, circuitPack $Card
NW EM Shelf 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
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.
170
Figure 6-5
Default mapping of an object not specified in the MCF
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
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
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
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):
NW DN SNW network $NW network $DN network $SNW
171
The object instance for the managed element is:

AVA AVA AVA AVA AVA AVA AVA AVA Name [1] (I) :1030: (networkId) Value [1] (S) :Vancouver: Name [2] (I) :1030: (networkId) Value [2] (S) :fw1288: Name [3] (I) :1030: (networkId) Value [3] (S) :47.63.66.16: Name [4] (I) :1028: (managedElementId) Value [4] (S) :RNE5:
Setting the token environment variablesTo 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:
"NW SNW SSNW EM - network $NW, network $SNW, network $SSNW, managedElement $EM,",
The last network token is SSNW, so you would set the MOAFW_NETWORK_OBJECT_TOKEN environment variable as follows:
MOAFW_NETWORK_OBJECT_TOKEN="SSNW" ; export MOAFW_NETWORK_OBJECT_TOKEN
You can also, optionally, override the network element token as follows:
MOAFW_NETWORK_ELEMENT_TOKEN="EM" ; export MOAFW_NETWORK_ELEMENT_TOKEN
172
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 $DS1 NW EM LP DS3 - network $NW, managedElement $EM, ds3LineTTPBidirectional $LP $DS3 NW EM LP E1 - network $NW, managedElement $EM, e1TTPBidirectional $LP $E1 NW EM LP E3 - network $NW, managedElement $EM, e3TTPBidirectional $LP $E3 NW EM LP DS1 Chan - network $NW, managedElement $EM, ds1LineTTPBidirectional $LP $DS1, ds1LineCTPBid $Chan NW EM LP E1 Chan - network $NW, managedElement $EM, ds1LineTTPBidirectional $LP $E1, e1CTPBid $Chan NW EM LP Jt2 - network $NW, managedElement $EM, msTTPBidirectional $LP $Jt2 NW EM LP V35 - network $NW, managedElement $EM, msTTPBidirectional $LP $V35 NW EM LP X21 - network $NW, managedElement $EM, msTTPBidirectional $LP $X21 NW EM Lp Sonet - network $NW, managedElement $EM, msTTPBidirectional $Lp $Sonet NW EM Lp Sonet Path - network $NW, managedElement $EM, vc4TTPBidirectional $Lp $Sonet $Path NW EM Lp Sdh - network $NW, managedElement $EM, msTTPBidirectional $Lp $Sdh NW EM Lp Sdh Path - network $NW, managedElement $EM, vc4TTPBidirectional $Lp $Sdh $Path NW EM Shelf - network $NW, managedElement $EM, equipmentHolder $Shelf NW EM Shelf Card - network $NW, managedElement $EM, equipmentHolder $Shelf circuitPack $Card NW EM Shelf Bus - network $NW, managedElement $EM, equipmentHolder $Shelf $Bus NW EM Trk Unacked Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk $Unacked $Framer NW EM Trk Unacked Atm- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk $Unacked $Atm NW EM Trk Pa Atm - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk $Pa $Atm NW EM Trk Atm - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Trk $Atm NW EM DpnGate Utp Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $DpnGate $Utp $Framer NW EM Vs Framer - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Vs $Framer NW EM Btds Framer - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Btds $Framer NW EM Htds Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $Htds $Fra
173
Figure 6-7
Sample inm.map file (2 of 2)
NW EM FrUni - network $NW, managedElement $EM, uni $FrUni NW EM FrUni Framer- network $NW, managedElement $EM, tcAdaptorTTPBidirectional $FrUni $Framer NW EM FrUni Dlci - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $FrUni vpTTPBidirectional $Dlci NW EM FrNni - network $NW, managedElement $EM, intraNNI $FrNni NW 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 $Vcc NW 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 $Vcd NW EM AtmIf Vpc Vpd - network $NW, managedElement $EM, tcAdaptorTTPBidirectional $AtmIf, vpCTPBidirectional $Vpc $Vpd # # default mapping for components not specified in above list # NW - network $NW EM - managedElement $EM DEFAULT - software $DEFAULT # # END OF FILE
174

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.
175
7
Directory Structuredescribes 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.
Chapter overview
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
177
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.
178
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
179
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.
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.
Note:
Please refer to the included sample.makefile for additional details.
180
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)
181
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.
182
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
Class
ADK allocation policy

Number of instances One One One transient instance per alarm raise or clear One transient instance per NE enrol One transient instance per NE de-enrol One transient instance per state change event Allocation policy Created by init_mdr_factory() Created by calling createMDRAdapter() Created when an alarm is generated: can be destroyed after alarm is pushed Created when an NE is discovered: can be destroyed after NE enrol has been pushed Created when an NE is deleted: can be destroyed after NE de-enrol has been pushed Created when managedElement has a state change: can be destroyed after state change has been pushed Created when managedElement has an attribute value change: can be destroyed after attribute value change has been pushed
MDRAdapterFactory Specialization of MDRAdapter AdapterAlarm AdapterNeEnrol
AdapterDeEnrol
AdapterOsiStateEvent
AdapterAttributeValue One transient instance per Event attribute value change
Appendix
183
Table A-1
Class
ADK allocation policy (Continued)

Number of instances One instance in the SetupInitialConfig() callback One instance in the Reconfigure() callback One instance when calling GetConfig() One transient instance per NE enrol, NE de-enrol, OSI State Event, Attribute Value Event, alarm, and NE Unknown Status Allocation policy Created and destroyed by the Adapter plugin for the SetupInitialConfig() and Reconfigure() callbacks Must be created before calling GetConfig() and deleted afterwards Created before calling a Push method (i.e. PushNEUnknownStatus, PushEnrol, PushDeEnrol, PushAlarm, PushOsiStateEvent, PushAttributeValueEvent). Can be destroyed after calling a Push method. Created before calling a Push method (i.e. PushNEUnknownStatus, PushEnrol, PushDeEnrol, PushAlarm, PushOsiStateEvent, PushAttributeValueEvent). Can be destroyed after calling a Push method. Created before calling addAddedVendorSpecificInfo() or addAddedTechnologySpecificInf o(). Can be destroyed after calling addAddedVendorSpecificInfo() addAddedTechnologySpecificInf o().
AdapterConfig
RWTPtrSlist<AvaType>
AvaType for ObjectId
One transient instance per component of a distinguished name, i.e. RWTPtrSlist<AvaType>
AvaType for VendorSpecificInfo and TechnologySpecificInf o
One transient instance per VendorSpecificInfo or TechnologySpecificInf o.
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().
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
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

Table B-1 ADK Engineering Limits Engineering Limits
The following table describes the engineering limits for the ADK 4.3 run-time platform.
Number of network elements supported Number of alarms supported Number of instances of the CORBA Adapter Number of instances of Device Adapters (DA)
3,500 24,000 1 per 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
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.
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.
ADK CORBA Adapter The upwardlooking 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
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.
Alarm A message from a network element indicating a problem in the monitored network.
AMBB Application Management Building Block. Starts, stops, and restarts CC Server and AL Servers.
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.
AMGUI Application Management Graphical User Interface. Used to maintain application parameters.
AML Application Management Library
AM Server Application Management CORBA Server
191
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-toprogram 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.
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.
Applet Java program that runs in a web browser; similar to an application but subject to the security restrictions of the browser.
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
192
Glossary
AWT Abstract Window Toolkit. A collection of graphical user interface (GUI) components implemented using native-platform versions of the component.
BOA See Basic Object Adapter
Blackboard Pattern Design pattern that includes a shared data area.
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.
C
CA See ADK CORBA Adapter
CC Custom Commands
C++ language The object-oriented programming language in which NSP modules are written
Basic Object Adapter The CORBA specification defines the BOA pseudo object in PIDL. The BOAs 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.
CCBB Block
Custom Commands Building
CCGUI Custom Commands Graphical User Interface used to maintain custom commands.
193
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.
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.
CLFI Common Language Facility Identifier
CM Configuration Management
Client, thin A system that runs a very light operating system with no local system administration and executes applications delivered over the network.
CMISE Common Management Information Service Element, a component of Open Systems Interconnection (OSI)
194
Glossary
Compiler A program that converts programs in a high-level programming language into a language the computer understands
Consumer A logical entity that receives events.
Configuration A set of options which can be dynamically for a process or an interface. For example, the number of clients allowed simultaneously.
Coordinated Universal Time (UTC) The reference for official time used by all countries. Replaces Greenwich Mean Time (GMT)
CORBA Common Object Request Broker Architecture
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:
CORBA Adapter Adapter)
(see ADK CORBA
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.
COS CORBA Common Object Services
CR Change Request
CWD
Current Working Directory
195
Glossary
D
DA See Device Adapter
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.
DBI
Database Interface
Debugger A programme that identifies code errors
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.
Dependency A relationship between two database objects where the existence of one object is necessary before the second object can be added.
DIR Directory Service (LDAP)
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.
Distinguished name A name that unambiguously identifies an object within an object hierarchy.
DLC Data Link Connection
DN Distinguished Name
DNS
Directory Name Service
196
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.
Event Delivery Model The model by which events are delivered in an event system using the publish/subscribe pattern.
Doors
Requirement Repository
E
EFD See Event Forwarding Discriminator
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.
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.
197
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.
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.
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:
EMS Element Management System. Allows addition of an element (such as Equinox) after deployment.
BestEffort Upon restart from a failure of the process within which the event channel is executing, no
198
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.
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
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.
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)
199
Glossary
FQDN Fully Qualified Domain Name
GND Graphical Network Display (provides a resource browser and a layout editor)
FR Frame Relay GNDE Editor Graphical Network Display
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.
GNE
Graphical Network Editor
GMT Greenwich Mean Time
G
GMT Greenwich Mean Time, the predecessor to Coordinated Universal 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.
GNB Graphical Network Browser
200
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 applications GUI components and used to provide context-sensitive help.
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.
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.
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 CORBAbased Object Request Brokers (ORBs).
201
Glossary
The protocol allows ORBs created by different vendors to interoperate, and it supports the use of the Internet as its communication medium.
Interface A publicly advertised CORBA IDL which has a configuration (that is, a set of options which can be changed dynamically).
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.
Interface Service Provider The object that provides the service advertised in the trader.
IOR
Interoperable Object References
IP Internet Protocol Internet Protocol
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.
ITU-T A division of the International Telecommunications Union that specializes in setting standards for telecommunications. (Formerly CCITTConsultative Committee on International Telephone and Telegraph.)
202
Glossary
J
JMS Java Message Service
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.
JNI Java Native Interface
JTGO Java Telecom Graphic Objects (ILOG product)
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.
JTGO Java Telecom Graphic Objects (ILOG product)
M
MFT Management Framework Technology group (formerly known as SES)
JWS Java Web Start
L
LA Launcher
Managed Object Agent an interface between managed network elements and the Framework-based Management Solution. (older terminology - use Device adapter)
203
Glossary
Management Data Router Adaptor A software device that adapts NEspecific protocols into NSP.
N
NDS Netscape Directory Server (used for password / user ID authentication)
Method A function defined in a class
MDR
Management Data Router NE See Network Element
MOA see Managed Object Agent Network Element (NE) a piece of equipment used in telecommunications networks, such as (for example) a switch, terminal, or router.
MOB Managed Object Base
MVC Model-View-Controller NM Network Model MMVC Multi-level Model-ViewController 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.
MDI
Multi-Document Interface
NMS
Network Management System
204
Glossary
NNI
Network Node Interface
NOC See Network Operating Center.
NPI
New Product Introduction
NSP Network Services Platform
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
NTD Network Tree Display

n
O
OAM&P Operations, Administration, Maintenance and Provisioning
are used by a client to make a request 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
Object The principal building block of object-oriented programs. Each object is a programming unit consisting of data (instance variables) and functionality (instance methods).
n n
sets up connection between client and server fires up servers if necessary provides for interoperability
205
Glossary
Observer Pattern Defines a one-tomany dependency between objects so that when one object changes state, all its dependencies are notified and updated automatically.
Persistent Data is stored in a database independent of the server so that when the service availability is disrupted, the data is not lost.
OMG
Object Management Group
PIOR Persistent Interoperable Object References
OPC Operations Controller Card
Plugin Module, code, or small application that adds functionality to a program.
Orbixd A process which monitors and controls CORBA servers. Provided by IONA as a component of Orbix.
POR
Plan of Record
OSI
Open Systems Interconnection
Properties Attributes of a resource. Not all resources have properties.
P
PEA Personal Event Assistant
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
206
Glossary
R
Regional Operations Center A centralized point from which a number of NEs in a region may be managed
RMBB Resource Management Building Block (old terminology provided fault information on optical networks). This is now a component of TUMSBB.
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)
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.
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.
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
207
Glossary
S
SA Service Activation
Service Enabling Solutions The organization responsible for Network Services Platform.
SES See Service Enabling Solutions.
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.
Skeleton A minimal software infrastructure to which functionality can be added.
SMTP SDE Software Development Environment
Simple Mail Transfer Protocol
SONET Network
Synchronous Optical
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.
SR
Service Request
Subclass A class that is a special case of another class
208
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.
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.
Subscribe The act of enabling event channel for sinking events
SUM Summary
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.
SUMBB
Summary Building Block
T
Teaming Agreement An agreement between the Framework Advantage group and a solution delivery group for use of Framework-based Management Solutions.
Supplier A logical entity that produces events
209
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 timeconsuming 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.
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 applications 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.
TM
Trail Management
TMBB Block
Trail Management Building
TMCA Trail Management CORBA Adapter
TMN Telecommunications Management Network
Tracing See entry on Logging and Tracing
210
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.
U
UI User Interface.
UAM
Unified Alarm Manager
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.
UDT Universal Date and Time
UML Universal Modeling Language
UNI
User Network Interface
TUMS Topology Universal Modeling Service (building block)
UNIX The operating system used by both the Sun and HP platforms of Framework.
TUMSBB Topology Universal Modeling Service Building Block (provides nodal discovery and elementary network topology)
Unpublish The act of disabling the event channel for producing events.
Unsubscribe The act of disabling the event channel for sinking events
211
Glossary
URL Uniform Resource Locator
X
xNI All Network Interfaces (i.e., both UNI and NNI) .
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
212

ADK Developer Guide

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

ADK Developer Guide

Încărcat de

Drepturi de autor:

Formate disponibile

Odyssey 3 Device Adapter Development Kit (ADK) Developers Guide

Issue 1.0 Draft May 2006 ADK Release 4.4

Management Integration Platform (MIP) Developer Guide

Management Integration Platform Device Adapter Development Kit

May 2003 Preliminary release for ADK 4.3. Updates include:

Management Integration Platform Device Adapter Development Kit

About this guide

Management Integration Platform Device Adapter Development Kit

Management Integration Platform Device Adapter Development Kit

Management Integration Platform Device Adapter Development Kit

Conventions and Feedback

Management Integration Platform Device Adapter Development Kit

For Further Information

Additional documentation is available for developers, as follows:

Management Integration Platform Device Adapter Development Kit

RETURN TO DOCUMENT ROADMAP

Area of Interest Functionality Architecture Engineering Limits

Design & Integration Testing

Management Integration Platform Device Adapter Development Kit

Area of Interest What is available from the ADK API?

Design & Integration Testing

Where to get support How to get started

Management Integration Platform Device Adapter Development Kit

Area of Interest Resource information: How to model it

Location Developing a Model Conversion File on page 148

Design & Integration Testing

How to package and deliver a DA

Framework ADK Developers Guide

Configuring and sanitizing the test environment 47

Configuring multiple Device Adapters 56

Configuring multiple sub-domains 61

Upgrading ADK 66 Uninstalling ADK 68

ADK files and directories 42 Sanitize the development environment 45

Framework ADK Developers Guide

Develop an NE-specific Device Adapter 71 Develop a Model Conversion File 72

General development considerations 99

Framework ADK Developers Guide

Develop special alarm handling 138

Create the Model Conversion File for your plugin 165

Framework ADK Developers Guide

Framework ADK Developers Guide

Framework - ADK Developers Guide

Framework ADK Developers Guide

Desktop UI Device Adapter Development Kit (ADK)

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP

This chapter describes:

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP

Device Adaptation architecture

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP

ADK CORBA Adapters

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP

Framework ADK Developers Guide

RETURN TO DOCUMENT ROADMAP