framewrk.mif

CHAPTER

CISCO CONFIDENTIAL

2-1

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Understanding Northbound API Framework

The NBAPI Framework consists of:

• A framework to deploy Web Services Simple Object Access Protocol (SOAP) Framework

• A framework to send the events using SOAP to the clients (Event Framework)

The SOAP Framework will be an SRC component which means that each application has to ship the

necessary files with it.

Event Framework will be registered as a process. So, there will be one R component and one process for

each machine or system. The Event Framework will be an R component which means that there is one

process for each system.

• Understanding SOAP Framework

• Understanding Event Framework

• Integrating with the Event Framework

Understanding SOAP Framework

The functionalities of the SOAP Framework are:

• SOAP Engine— Communicates using SOAP. There will be one SOAP Server per web application.

A SOAP Server can host many web services. We will be using "Apache Axis" version 1.4 as the

SOAP Engine.

• SecurityHandler— Handler that performs AAA operations such as Authentication, Authorization

and Accounting. It also provides a hook to check the license.

• RequestValidator— Provides handler for limiting the number of concurrent requests and limiting the

size of the incoming SOAP request.

This section discusses the following topics:

• SOAP Server

• SecurityHandler

• Method To Task Mapping File

• RequestValidator

• Integrating with SOAP Framework

• Utility / Helper Functions

• Enabling Debug

CISCO CONFIDENTIAL

2-2

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

• SDK Kits

• Java Doc

SOAP Server

The SOAP server handles incoming SOAP requests and generate corresponding SOAP responses. It also

provides utility classes for generating WSDL from Java code and generating Java stubs from WSDL.

“Apache Axis” version 1.4 will be used as the SOAP Server (SOAP Engine).

The following jars are a part of Axis that is shipped with NBAPI Framework.

• axis.jar

• axis-ant.jar

• commons-discovery.jar

• commons-logging.jar

• saaj.jar

• wsdl4j.jar

• jaxrpc.jar

• log4j.jar

SecurityHandler

A handler is unique piece of code that can be configured to run before or after a SOAP request or a

response is processed. Axis provides several handler interface which can be implemented and extended

to provide required functionality.

The invoke() method of the handler will be called before the SOAP request or a response is processed.

The NBAPI framework extends “org.apache.axis.handler.BasicHandler” abstract class to perform all the

AAA and license checks.

“com.cisco.nm.nbi.cwcs.nbifw.SecurityHandler” class implements this BasicHandler. This class and the

necessary utility classes are packaged into csnbifw.jar.

Method To Task Mapping File

The NBAPI framework performs Authentication, Authorization and Accounting check (AAA) before

running a method. The methods needed for the framework to do AAA checks are:

• Authentication

• Authorization

• Accounting

• Customizing SecurityHandler

CISCO CONFIDENTIAL

2-3

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

Authentication

Authentication check is performed before running the method. Only if the HTTP session is valid, will

this method be run. For methods such as login() and initiateSession() this value will be set as false since

these are methods that create the valid session. The <Authentication> XML tag corresponds to this.

Authorization

Authorization checks are performed before running a specific method. The framework uses CAM APIs

for authorization. The CAM APIs need Task ID for authorization. So the corresponding Task ID for the

method should be supplied to the framework.

If there are many Task IDs, all of them should be provided. The method starts executing only if all the

Task IDs are authorized. The <Authorization> tag corresponds to this. If there is no authorization needed

for a method, specify a blank XML tag.

Accounting

If this value is set, this method of execution is audited. Accounting can be enabled for a specific method

or for all the service methods in a web application. The <Accounting> tag in the XML file enables

accounting for a specific method.

The accounting for all the services in a web applications can be enabled by adding a key in CCR with

MDC Name as the root element WS-ACCOUNTING as the resource name and YES as the value.

Enter this information in a XML and register it in CCR.

The DTD of the XML file is:

<?xml version=”1.0” encoding=”UTF-8”?>

<!ELEMENT Product (Method+)>

<!ATTLIST Product

NAME CDATA #REQUIRED

SERVICE CDATA #REQUIRED

VERSION CDATA #REQUIRED >

<!ELEMENT Method (Name,Description?,Authentication , Tasks?, Accounting)>

<!ELEMENT Name (#PCDATA) #REQUIRED>

<!ELEMENT Description (#CDATA)>

<!ELEMENT Authentication (#CDATA)>

<!ELEMENT Tasks (TaskId*)>

<!ELEMENT TaskId (#CDATA) #REQUIRED>

<!ELEMENT Accounting (#CDATA)>

See section Appendix A, “Sample XML File for Accounting” for a sample XML file.

After an XML is written, it needs to be registered with CCR with "MDC Name" as the root element,

“MethodToTaskMappingFile” as the resource name, and the fully qualified name of the file as the value.

For example, the MethodToTaskMapping file of CS Web Services is registered with CCR by running the

following command:

ccraccess -addResource cwhp Custom Custom

$NMSROOT/MDC/tomcat/webapps/cwhp/WEB-INF/CWHPMethodToTaskMapping.xml ““

MethodToTaskMappingFile

CISCO CONFIDENTIAL

2-4

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

Customizing SecurityHandler

All the functionalities of the SecurityHandler can be customized or overwritten by applications. The

APIs available for SecuirtyHandler are listed in Table 2-1.

Applications can create a new Class that extends this SecurityHandler and customizes their behavior. See

Writing server-config.wsdd for more information about how to plug-in the customized SecurityHandler

with the Framework.

RequestValidator

This handler controls the number of concurrent requests and the size of the incoming SOAP requests.

The number of concurrent connections is configurable and the default value is 20. The number of

concurrent connections can be controlled by adding a key in CCR with “Core” as the root element,

“Custom” as the subelement, “NBIMaxConnection” as the resource name, and the number as the value.

The number of concurrent connections are calculated for the whole system not per service or webapp.

For example if you want to configure 10 as the maximum number of connection, run:

ccraccess -addResource Core Custom Custom 10 "" NBIMaxConnection

The size of the incoming SOAP request is also configurable parameter and the default value is 50000

byte. This can be controlled by adding a key in CCR with “Core” as the root element, “Custom”

“Custom” as the sub-element, “MaxSOAPSize” as the resource name, and the number as the value.

If the value is set as -1 this check will not be performed. For example if you want to set the SOAP size

as 10000 byte, run:

Table 2-1 Methods to Customize SecurityHandler Functionalities

Return Method Description

void

isValidSession(MessageContex

t msgContext, UserContext

usrContext)

Checks for the valid session. If the session is not

valid and if the method requires the valid session to

run, the error, InvalidSessionException appears.

void

isAuthorized(MessageContext

msgContext, UserContext

userContext, SourceContext

srcContext)

Checks whether the user has appropriate privileges

to run the method. If the user is not privileged, the

error AuthorizationException appears.

void

doAccounting(MessageContext

msgContext, UserContext

usrContext, SourceContext

srcContext)

Audits the current operation. If accounting is

enabled for a specific method or for all the services

this method displays an audit message.

void

isLicensed(MessageContext

msgContext , SourceContext

srcContext)

Checks for the valid license. There is no license

needed to access the services exposed by Common

Services. Hence this method returns True.

If the applications need a specific license check, they

can override this function to achieve the

functionality you need.

void

invoke(MessageContext

msgContext)

Internally calls all the methods described above in

sequence. This is the main method that is called

before processing any SOAP requests.

CISCO CONFIDENTIAL

2-5

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

ccraccess -addResource Core Custom Custom 10000 "" MaxSOAPSize

The RequestValidator has invoke() method where these checks are performed. Applications can override

this and customize their functionality.

All these necessary classes are part of csnbifw.jar

Integrating with SOAP Framework

In order to deploy to a Web Service, you need to create a web application or you can use the existing

web application. This section does not cover creating a web applications.

Deploying to a Web Service involves:

• Copying Framework Jars

• Copying Service Specific Classes and Jars

• Updating web.xml

• Updating Apache Configuration

• Writing server-config.wsdd

• Verifying Web Services

• Generating WSDL and Java Stubs

• Importing Certificates

• Accessing Web Services

Copying Framework Jars

All the necessary jars from the framework have to be copied to the lib directory of the application. All

the framework related jars, configuration files are packaged into csnbifw.war file. Applications need to

extract the WAR file during their build time. They need to copy all the jars in their web applications lib

directory.

You need to copy all the property files and the configuration files. The WAR file has the relative path of

these files and the files need to be copied into the web application directory of the application.

Copying Service Specific Classes and Jars

All the methods that are exposed by a single service, must be part of a single class. The methods can

internally call multiple classes.

However, all the methods that are north bound must be defined in one class file. If there are multiple

services, each service should have its own class. Implement the methods and place the jars or classes in

the web application's WEB-INF/classes or WEB-INF/jars directory.

Updating web.xml

All the web services can be accessed by contacting the AxisServlet. So the definition of the servlet needs

to be updated in web.xml. This servlet will be used as the endpoint location and all the SOAP clients will

contact this servlet to access the web services.

CISCO CONFIDENTIAL

2-6

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

Add the following entries in the web.xml

<servlet-name>AxisServlet</servlet-name>

<display-name>Apache-Axis Servlet</display-name>

<servlet-class>

org.apache.axis.transport.http.AxisServlet

</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>AxisServlet</servlet-name>

<url-pattern>/servlet/AxisServlet</url-pattern>

</servlet-mapping>

<servlet-mapping>

<servlet-name>AxisServlet</servlet-name>

<url-pattern>/services/*</url-pattern>

</servlet-mapping>

This means the endpoint for the service deployed in cwhp web application will be

https://server-name/cwhp/servlet/AxisServlet or

https://server-name/cwhp/services/ServiceName

Applications can customize the end point URL by adding more servlet mapping.

Updating Apache Configuration

There is a requirement that the Web Services should be accessed only in HTTPS (SSL) mode. So even

if SSL is not enabled in the server, the web service should be accessible in HTTPS. In addition, the

servlets defined in the section Updating web.xml will be accessed without a valid session.

Apache WebServer comes with Common Services and has the necessary provisions for this. You can

create a single URL (endpoint) that can be accessed only through HTTPS by adding necessary SetEnvIf

hooks.

For example if you want to allow /cwhp/servlet/AxisServlet only in https mode, you need add the

following entries:

SetEnvIf Request_URI /cwhp/servlet/AxisServlet allow_https

SetEnvIf Request_URI /cwhp/servlet/AxisServlet deny_http

in the httpd.conf file.

The first entry allows the AxisServlet to access in https mode and the second entry denies when the

servlet is accessed through HTTP. So these entries need to be added for all the servlet mapping defined

in the section Updating web.xml.

The installation framework provided by Common Services allows you to add the entries. You need to

write all such URLs into a file “addSetEnvIf.txt” and this file should be in the disk1 directory of the

installable. If the file is present, Install Framework automatically adds entries in the Apache conf file.

All the endpoints (servlet mapping) defined in the section Updating web.xml need to be accessed without

a valid session. Apache the web server that ships with Common Services allows you to do this. All the

entries in allow_files.conf file are allowed without performing a valid session check.

The installation framework provided by Common Services allows you to automatically add the entries.

You need to write all such URLs and endpoints into a file “addUrls.txt” and this file should be in the

disk1 directory of the installable.

If these files are present , the install framework adds the entries in the apache conf file.

CISCO CONFIDENTIAL

2-7

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

Writing server-config.wsdd

Web Service Deployment Descriptor (WSDD) is a deployment descriptor that contains information

about the list of services to be exposed and all the necessary parameters.

For more information about WSDD, see

http://ws.apache.org/axis/java/user-guide.html#CustomDeploymentIntroducingWSDD .

The axis engine reads the server-config.wsdd file under the WEB-INF directory and deploys all the

services configured in it. All the handlers written in previous section are configured here. The

server-config.wsdd mainly contains:

• A list of services

• Service related definition such as the class name, scope and the parameters

• Mapping of the Java objects

• Handlers (Request & Response) which will be invoked before / after processing SOAP request /

response

Each service definition starts with <service> tag and has <parameter> tags for specifying the classname,

allowed methods in the service and scope of the service. For example if there are two services to be

deployed, there are separate service tags for each one.

Axis sends the objects over wire only if there is a corresponding serializer registered for it. A serializer

converts the java objects into XML and a deserializer converts the XML into java object.

So all object types that need to be sent or received over wire must be registered with Axis. Axis provides

a set of serializer for the bean object, array etc. So each object definition starts with the corresponding

mapping tag and the necessary parameters to it.

Handlers can be categorized into Request and Response Handlers. Request Handlers are invoked before

a SOAP request is processed and Response Handler(s) are invoked before a SOAP response is sent out.

All the AAA functionalities provided by the framework are implemented using the handlers.

These handlers can be configured for each service or global to the server-config.wsdd. That is, if a

handler is defined as a global handler in the WSDD file, the handler is applicable to all the services

defined in the WSDD file. SecurityHandler must be configured as request handler and the

RequestValidator must be configured as both request and response handler.

The following sample code snippet from the server-config.wsdd file defines the SecurityService:

<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="http://xml.apache.org/axis/wsdd/"

xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

….

</handler>

</handler>

</requestFlow>

</handler>

</responseFlow>

</globalConfiguration>

CISCO CONFIDENTIAL

2-8

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

<beanMapping qname="myNS:CSUser" xmlns:myNS="urn:SecurityService"

languageSpecificType="java:com.cisco.nm.nbi.cwcs.security.CSUser"/>

</service>

Verifying Web Services

After all the above steps are done, Tomcat has to be restarted for the changes to be in effect. After Tomcat

is up, access https://<server-name>:SSL port/<mdcname>/servlet/AxisServlet or the alias you have

created in the web.xml. For example to access using a default port (443), you can access at

https://localhost/cwhp/servlet/AxisServlet.

This should list all the services and methods defined in server-config.wsdd. If it does not appear, check

tomcat's stdout.log to see the corresponding error. The common errors are syntax errors in the

server-config.wsdd XML file or some of the classes related to framework or services may be missing.

All the SOAP requests are sent over SSL only, so if the listener web service is using a self-signed

certificate, it must be added in the Common Services trust store.

The following sections describe the basic features needed to use Webservices, such as WSDL2Java

Generation, Java2WSDL Generations. It also describes how to deploy services.

Generating WSDL and Java Stubs

Web Service Description Language (WSDL) describes Web Services in a structured way. A WSDL

description of a service explains (in a machine-understandable way) the interface to the service, the data

types it uses, and where the service is located.

All the services are exposed to the end user in a WSDL file. Axis provides

“org.apache.axis.org.wsdl.Java2WSDL” class to generate the WSDL from a class file. All the WSDLs

are generated during the build time. They are available in the WEB-INF/WSDL directory.

• Java to WSDL Generation

• WSDL to Java Generation

Java to WSDL Generation

You will find the Axis WSDL-to-Java tool org.apache.axis.wsdl.WSDL2Java in axis.jar. The basic

invocation form looks like this:

java org.apache.axis.wsdl.Java2WSDL

For more information on this tool, see

http://ws.apache.org/axis/java/reference.html#Java2WSDLReference)

This will generate only those bindings necessary for the client.

For example:

java -classpath (Classes Needed for your Services, Axis related jars)

org.apache.axis.wsdl.Java2WSDL -o dcr.wsdl -l

"http://localhost:1741/cwhp/servlet/AxisServlet" -n "DCRService" -u LITERAL -A OPERATION

-p com.cisco.nm.nbi.cwcs.info=CSInformationService com.cisco.nm.nbi.cwcs.dcr.DCRService

Table 2-2 explains the above command.

CISCO CONFIDENTIAL

2-9

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

WSDL to Java Generation

Prior to converting the WSDL to Java files, replace the server name (bydefault a localhost) with desired

port number in all the WDSL files. Else, default port (443) is used for converting WSDL to Java files.

Axis provides “org.apache.axis.wsdl.WSDL2Java” utility classes for converting WSDL into Java Stubs.

You can find the Axis Java-to-Java tool org.apache.axis.wsdl.Java2WSDL in axis.jar. The basic

invocation form looks like this:

java org.apache.axis.wsdl.WSDL2Java

For more information on this tool see

http://ws.apache.org/axis/java/reference.html#WSDL2JavaReference)

This generates the client code. For example,

java org.apache.axis.wsdl.WSDL2Java --NStoPkg DCRService=com.cisco.nm.nbi.cwcs.dcr -w -o

wsdl-stub dcr.wsdl

Table 2-3 explains the above command.

Table 2-2 Java2WSDL Generation

Command Description

-o dcr.wsdl

Output WSDL filename

-l

https://localhost/cwhp/serv

let/AxisServlet

Service location url or endpoint.

-n DCRService

Indicates the name of the target namespace of the WSDL.

-u LITERAL

The XML Schema defines the representation of the XML for the

request.

-A OPERATION

OPERATION forces SOAP action to the name of the operation

-p

com.cisco.nm.nbi.cwcs.info=

CSInformationService

Maps the Package to your Name space.

com.cisco.nm.nbi.cwcs.dcr.

CRService

Represents the Service Class

Table 2-3 WSDL2Java Generation

Command Description

- --NStoPkg

DCRService=com.cisco.n

m.nbi.cwcs.dcr

Maps your Name space to Package.

-w

Used in wrapping your Collection Classes. For example,

DeviceCollection

-o wsdl-stub

Output directory for generated files.

dcr.wsdl

wsdl describes your service

CISCO CONFIDENTIAL

2-10

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding SOAP Framework

Importing Certificates

The Web Services can be accessed only in HTTPS mode. Since Common Services uses Self Signed

Certificate by default, these certificates need to be imported in the NBAPI client to trust it. If you are

using third party issued certificates, you should ensure that the root Alert is trusted by your client.

Importing Certificates is a one-time activity and this can be done using either of these methods:

The certificate NMSROOT\MDC\Apache\conf\SSL\server.crt from the Ciscoworks server can be copied

and added in the trust store of Client side JRE. "keytool -import" command can be used for this.

• The Information Service provides a NBAPI for getting the CS certificate. So initially, the client side

should make a NBAPI call to this Information Service with trust disabled, get the certificate and add

it to its trust store.

Accessing Web Services

To access the web service.

Step 1 Deploy the Web Services

Step 2 Generate WSDL

Step 3 Import Certificates in the Client Side

Step 4 Transfer the WSDL and the axis jars to the client side and generate Java Stubs

Step 5 Initialize the Services by calling appropriate ServiceLocators and get the appropriate AxisServlet

Step 6 Call the login() or initiateSession() methods in SecurityService to create session

Step 7 Attach the resulting cookies in the Services and access Service specific methods.

The code snippets are available in the following CS Services section. The test and sample code is also

available at vob in the /vob/enm_cmf/share/cwapps/nbsvc/src/com/cisco/nm/nbi/cwcs/test directory.

You need to set cs_nbi1_1_ch view to see these code snippets and test programs.

Utility / Helper Functions

The Framework provides several utility functions to query CCR, get NMSROOT and get the

SourceContext and UserContext object from the session. The utility functions are part of

"com.cisco.nm.nbi.cwcs.nbifw.util.NBIUtil" class. This class is part of csnbifw.jar.

There are two important functions in this class

• getSourceContext() — Static method in NBIUtil, which is a helper method to access the

SourceContext object. If you call this method without having a valid session object, it returns a Null

value.

• getUserContext() — Static method in NBIUtil, which is a helper method to access the UserContext

object. If you call this method without having a valid session object, it returns a Null value.

More information about these methods is available in the Java Doc. The Java Doc is part of CS NBAPI

build.

CISCO CONFIDENTIAL

2-11

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding Event Framework

Enabling Debug

The framework uses log4j for logging. The framework picks up the categories from log4j-nbi.properties

from WEB-INF/classes. So the debug levels can be increased to DEBUG to enable debug in the

framework.

SDK Kits

All the framework related jar files and property files are available in a war file. This WAR file

(csnbifw.war) is part of nbsvc (for Solaris it is CSCOnbsvc) sdk kit. Applications need to extract this

war file and include the necessary jars in part of their proto packages.

Java Doc

The Java Doc for the framework are part of the cs_nbi1_1_ch image itself. The java doc is in the javadoc

folder in the image. For example, NT_CS_NBI1_1_CH_INTEGRATION_READY\javadoc directory

Understanding Event Framework

Event Framework helps to dispatch the internal application’s events to an interested external

application's web service. The events are sent as Objects (EventObjects) using SOAP. The framework

provides the platform for plugging in the application Event Handlers that help to convert the JMS

Message to an event object format that is understood by the external web service.

The format of the event object should be decided by the applications. The WSDL of the event should be

exposed to the external applications. Framework maintains the lifecycle of the plugged handlers and

helps to dispatch the events to the appropriate Web Services.

The event framework is registered as a process EventFramework with Daemon Manager. So when

Daemon Manager starts, the process reads the list of EventHandlers registered and starts all of them. So,

when a particular event is received, the appropriate event handler is called. This converts the event into

EventObject and the framework sends a SOAP message to the registered listeners.

Integrating with the Event Framework

There are two types of consumers for Event framework.

One type of consumers are internal applications (such as, CS components and RME's components).

These consumers need to expose their generated events.

The other type of consumers are the external Management station applications. These consumers must

listen to these events. This section describes the two types of consumenrs for Event Framework

• Internal Applications

• External Applications

CISCO CONFIDENTIAL

2-12

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding Event Framework

Internal Applications

To expose the events pertaining to a topic (For example, cisco.mgmt.cw.cmf.dcr) out of the current

management station, the applications (such as DCR) should:

• Define Event Object

• Define a Pluggable EventHandler

• Plug the Handler to the Event Framework

• Register the Handler Classpath with CCR

Define Event Object

You can create the EventObject specific to their topic by extending

com.cisco.nm.nbi.cwcs.nbifw.efw.event.EventObject and including fields specific to the topic's event.

For example, DCREventObject.

For code sample, see Appendix A, “EventObject”.

This is the negotiated event object format which the external web service should be aware of in order to

listen to these events. Application also need to define WSDL for this EventObject and need to expose to

external customers.

Define a Pluggable EventHandler

The purpose of the event handler is to convert the JMS event into the application specific EventObject

and pass it to the framework. Framework provides the JMS Message pertaining to the topic and expects

a formatted EventObject from the handler. This EventObject can be dispatched to the interested web

service listeners.

Handler should be created by extending

com.cisco.nm.nbi.cwcs.nbifw.efw.handler.EventHandler

and implementing the abstract

convertEvent(Message msg) method. convertEvent() should receive

the generic JMS Message from the framework and it should construct and return the application's topic

specific EventObject.

It can choose to return Null if it wants to filter the event to prevent it from reaching the remote listener.

After the instantiation of the application specific EventObject and before setting its fields,

EventHandlers can optionally preprocess the EventObject by calling the utility function,

com.cisco.nm.nbi.cwcs.nbifw.efw.util.EventFrameworkHelper.preprocessEventObject

(EventObject, javax.jms.Message,EventHandler)

This function will set:

• EventObject’s EventID to JMSMessageID

• EventType to JMSMessageType

• SourceMachineName as host on which the Framework is running, and

• Topic to the topic for which the Handler is listening.

If application chooses to set by itself it should set the above mentioned fields as prescribed. However, it

can set SourceMachineName to reflect a different host name if the host on which the framework is

running is different from the event source.

For code samples see Appendix A, “EventHandler”

CISCO CONFIDENTIAL

2-13

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding Event Framework

Plug the Handler to the Event Framework

During the application installation call

com.cisco.nm.nbi.cwcs.nbifw.efw.HandlerRegister.registerHandler (String topic, String

handlerclassname) with the application topic and the fully qualified classname of the handler.

For example, com.cisco.nm.nbi.cwcs.nbifw.efw.HandlerRegister.registerHandler

(“cisco.mgmt.cw.cmf.dcr”, com.cisco.nm.dcr.DCREventHandler);

More information about the methods are available in the Java Doc. The Java Doc is part of CS NBAPI

build.

The classpath of the handlers their EventObjects and their dependent classes (excluding framework

specific classes) should be registered with CCR under the resource name EventHandlerClasspath.

Classpath should be separated by semicolon ‘;’ . There should be one classpath entry for each webapp.

We recommend that you combine all the handlers and their EventObject into one jar file and store it in

one location. You must register with CCR the classpath by mentioning the jar and the dependent classes.

For example, for CS Scenario.

The entire handler such as, DCREventHandler, JRMEventHandler, etc and all the event objects such as,

DCREventObject, JRMEventObject can be jarred as CSEventHandler.jar and dropped at

[NMSROOT]/lib/classpath.

The classpath can be registered with CCR as:

[NMSROOT]/lib/classpath/CSEventHandlers.jar;[NMSROOT]/www/classpath where it is assumed

that the dependent classes are at [NMSROOT]/www/classpath.

ccraccess -addResource cwhp Custom Custom

"${NMSROOT}/MDC/tomcat/webapps/cwhp/WEB-INF/lib/ogs-client.jar;${NMSROOT}/MDC/tomcat/webap

ps/cwhp/WEB-INF/lib/ogs-util.jar;${NMSROOT}/MDC/tomcat/webapps/cwhp/WEB-INF/lib/CSEventHan

dlers.jar" "" EventHandlerClasspath

External Applications

If an external application wants to receive events generated by the internal application, it should know

the topic and the predefined format of the EventObject prescribed by the application. It should create a

web service that can receive the EventObject.

This web service listener should be registered to the Event Framework by specifying the topic of interest.

To register a webservice listener to the Event Framework you should:

• Create the Web Service Listener

• Deploy the Web Service Listener

• Register the Listener with the EventFramework

Create the Web Service Listener

Create a Web Service and a method which will accept the specific EventObject as the parameter and

return true or false reflecting the status of reception. If the webservice method is written using Java, the

WSDL of the EventObject can be used to generate Java source. For a sample code, see Appendix A,

“Remote Listener Service”.

CISCO CONFIDENTIAL

2-14

SDK Developers Guide for CiscoWorks Common Services 3.2 Northbound API 1.1

OL-16255-01

Chapter 2 Understanding Northbound API Framework

Understanding Event Framework

Deploy the Web Service Listener

Web service deployment should use bean serialization with the bean Mapping qname as "NameSpace:

EventObject" , Name Space as "urn:EventReceiver" and provider as "java:RPC". See Appendix A,

“Remote Listener Service” for a sample deployment descriptor of a sample Listener service which

receives DCREventObject.

This can be done by either of these methods:

• Local Registration

registerListener (String topic, String targetendpoint, String operation name, String username, String

password) where username and password will be null if basic authentication is not use. If the

webservice requires authentication, only basic authentication is supported. Local Access to the

Management station is required to call this API.

• Remote Registration

For the above API call, Web service wrappers which the external application can call and register

their WebService listeners are available. For subscribing and unsubscribing to events see Chapter 7,

“Using Event Service”