Chapter 2 Understanding Northbound API Framework
Download this chapter
Chapter 2 Understanding Northbound API FrameworkChapter 2 Understanding Northbound API Framework
 Feedback

Table Of Contents

Understanding Northbound API Framework

Understanding SOAP Framework

SOAP Server

SecurityHandler

Method To Task Mapping File

Authentication

Authorization

Accounting

Customizing SecurityHandler

RequestValidator

Integrating with SOAP Framework

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

Java to WSDL Generation

WSDL to Java Generation

Importing Certificates

Accessing Web Services

Utility / Helper Functions

Enabling Debug

SDK Kits

Java Doc

Understanding Event Framework

Integrating with the Event Framework

Internal Applications

Define Event Object

Define a Pluggable EventHandler

Plug the Handler to the Event Framework

Register the Handler Classpath with CCR

External Applications

Create the Web Service Listener

Deploy the Web Service Listener

Register the Listener with the EventFramework


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

•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

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

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.

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.


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:

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.

Add the following entries in the web.xml 

<!-- Entry for Axis Servlet -->

   <servlet>

      <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 for Axis 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.

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

 <globalConfiguration>

     ....

  <requestFlow>

        <handler type="java:com.cisco.nm.nbi.cwcs.nbifw.handler.RequestValidator">

                <parameter name="scope" value="session" />

        </handler>

        <handler type="java:com.cisco.nm.nbi.cwcs.nbifw.handler.SecurityHandler">

                <parameter name="scope" value="session"/>

        </handler>

  </requestFlow>

  <responseFlow>

        <handler type="java:com.cisco.nm.nbi.cwcs.nbifw.handler.RequestValidator">

                <parameter name="scope" value="session" />

        </handler>

  </responseFlow>

 </globalConfiguration>

<!-- SecurityService related definitions -->

 <service name="SecurityService" provider="java:RPC">

    <parameter name="allowedMethods" value="*"/>

    <parameter name="className" value="com.cisco.nm.nbi.cwcs.security.SecurityService"/>

    <parameter name="scope" value="Application" />


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

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


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


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.

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

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"

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.

Register the Handler Classpath with CCR

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

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.

Register the Listener with the EventFramework

This can be done by either of these methods:

•Local Registration

Register your listener by calling com.cisco.nm.nbi.cwcs.nbifw.efw.ListenerRegister. 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"