How to ... Create an HCS Assurance APIs Client Application

This sample application demonstrates how to create a Prime Central for HCS web service consumer client using the Apache CFX framework. The CFX framework can be used generate stub classes from the Prime Central Web Service WSDL.

You can then use these generated classes to connect to the Cisco Prime Central Web Service interfaces. You can download the code for this example. The following article walks through how to generate the consumer classes and how to create a web client that performs the following tasks:

• Authenticate and retrieve a session token
• Retrieve the number of archived events of type 1

Before You begin

To complete this exercise, you will need access to the following tools.

• Access to an HCS deployment
• The Prime Central Admin username and password
• The Apache CFX framework (http://cxf.apache.org)

Download and Install the CXF Framework

1. Go to http://cxf.apache.org and download and install CFX.
2. After, you have downloaded CFX, you may need to set up your environment to use CFX. You can do so by entering the following on the command line. Use the version of CFX that corresponds to the version you downloaded.

Generating the consumer classes

In this example, we will use the CFX framework to generate classes from the Prime Central Web Service WSDL. We will then use these generated classes to call the APIs.

Get the WSDL's

For this application, we need get the Event Management wsdl from the Prime Central deployment.

Event Management WSDL

https://your-prime-central-server:9090/EventManagement?wsdl

1. Create a directory for your project.
2. Create a directory inside of your project directory for the wsdl files.
3. Save all of the wsdl files in the wsdl directory.

Generate the Classes

Create a directory for the generated classes.

Next, we will use wsdl2java to generate the classes.

You may hit a java.lang.OutOfMemoryError while generating the code. To fix this you will need to increase the maximum heap size of wsdl2java. To increase the heap size do the following:

• open /Your_CXF_Download_Location/apache-cxf-2.X.X/bin/wsdl2java in an text editor.
• Change $JAVA_HOME/bin/java -Xmx128M <SNIP>
• to $JAVA_HOME/bin/java -Xmx256M <SNIP>
• Close and save the wsdl2java file.

Run the following commands to generate the stub classes. These commands make take a few minutes to complete. After they have finished, you should see the generated classes in the autogen/src and autogen/build directories.

Create the Web Client

Next, we will add the code that connects to the Prime Central Web Services and uses some of the APIs.

Create a directory for the source files

First, we will create a directory to contain our business logic source.

We will also create a directory for the compiled business logic class files.

Create a Connector

To complete the web client, we are going to create three classes. You can download these sample classes.

• HCSConnector.java - a simple base connector client that helps you connect to to the Prime Central SOAP Interface. Handles setting up the remote host, credentials, logging and certificate management.
  You should store this file as /home/alice/myProject/src/com/example/HCSConnector.java.
• HCSConnectorImpl.java - extends the HCSConnector base client and implements a version specific Prime Central Web Service Connector. Uses settings from the base class and the CXF autogenerated stubs to connect to the Prime Central SOAP interface.
  You should store this file as /home/alice/myProject/src/com/example/HCSConnectorImpl.java.
• AssuranceWebClient.java - uses the version specific connector and automates a sample workflow.
  You should store this file as /home/alice/myProject/src/com/example/AssuranceWebClient.java.

Using the Prime Central Web Service APIs

The AssuranceWebClient.java demonstrates how to implement the following workflow:

• Authenticate and retrieve a session token
• Retrieve the number of archived events of type 1 (active)

You can see the code that performs this workflow in the following segment.

Build the web client

The sample code download includes an ant build.xml file that you can use to build this project.

The build.xml file performs the following tasks:

• Compile the autogenerated code stubs.
• Archive all the autogenerated code and class files into a jar file (call this jar file "HCSWebClientGeneratedClasses.jar").
• Compile the business logic class files.
• Archive the business logic code and the class files into a jar file. (This jar file will depend on the HCSWebClientGeneratedClasses.jar, and will be called AssuranceWebClient.jar.)
• Archive the downloaded WSDL files.
• Use the main class of AssuranceWebClient as the class that is executed when the jar is run.

You can store the build.xml file from the sample code download in /home/alice/myProject/build.xml.

Be sure to set your CXF_HOME environment variable as follows:

You can build the client as follows:

Run the web client

To run the web client, use the following command. Enter the appropriate server address, username and password for your system.