sxml > Downloads > RisPort Sample App

How to ... Create an Serviceability Java Client using JAX-WS

Introduction

This sample application demonstrates how to create an Serviceability XML (Serviceability) web service consumer client using the wsimport command that is part of Java 6. You can download the project and open it directly in Eclipse. The following article walks through how to generate the consumer classes and call the Serviceability selectCmDevice API from the RisPort service.

This sample application performs the following:

  • prompts the user for the Cisco Unified Communications Manager host url or IP address
  • prompts the user for the admin user name and password
  • calls the Serviceability "selectCmDevice" API of the RisPort service to select devices that match the criteria specified in the code
  • displays the device name and IP address for each device returned.

Serviceability Sample Application

1
2
3
4
5
6
7
$ Welcome to the Cisco Serviceability Sample application.
Host: yourUCserver.cisco.com
OS Admin Account: admin
OS Admin Password: password
TotalNumberFound=1
DeviceName=testPhone
IPAddress=xx.xx.x.xx

Before You begin

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

  • Eclipse
  • Access to a Cisco Unified Communications Manager installation
  • Admin username and password for Cisco Unified Communications Manager
  • Java 6

Generating the consumer classes

Serviceability provides WSDLs that describe the requests and details of each of the Serviceability web services. The WSDLs can be consumed via wsimport to create native Java classes for making Serviceability requests.

Get the Serviceability WSDLs

The Serviceability WSDLs can be downloaded from Cisco Unified CM. The How To...Get the WSDLs article describes how to retrieve all of the Serviceability WSDLs.

For this example, we only need the RisPort wsdl.
You can download the RisPort WSDL from https://ServerName:8443/realtimeservice2/services/RISService?wsdl. Save the wsdl file locally on your system.

Create a Java Project in Eclipse

Next, we will create a new Java in Eclipse. This project will contain the classes that are generated by the wsimport command and our code that calls the Serviceability selectCmDevice API.

  1. In Eclipse go to, File | New | Java Project
  2. Give your project a name. For this sample, we will use sxml-demo.
  3. In the package explorer, you should see your new project, and there should be a src folder inside of your new project.
  4. Create a new folder named "wsdl" in your project at the same level as the data-src folder.
  5. Copy the Risport.wsdl file into the "wsdl" directory in your project.
  6. You should now see the Risport.wsdl file in your project in the wsdl folder inside of your new project.
  7. From the command line, cd to the directory of your project (sxml-demo).
  8. Run the following command to generate the consumer classes.
    1
    $ wsimport -keep -Xnocompile -s src -d bin -verbose wsdl/Risport.wsdl

    The parameters are as follows:

    • - keep keeps the generated files
    • -Xnocompile specifies to NOT compile the generated sources. If you do not specify this option, you may run out of memory during the wsimport command.
    • -s specifies where to put the source files
    • -d where to place generated output files
    • -verbose Output messages about what the compiler is doing The last parameter is the location of the wsdl file.
  9. After running this command, you will see messages about parsing the wsdl and generating the classes.
  10. This will take a few minutes to complete.
  11. Now you should see a new generated package (com.cisco.schemas.ast.soap) in the data-src folder of your project.
  12. The generated consumer classes are in these packages.

We will create code in the next section that calls the generated classes and accesses the Serviceability selectCmDevice API.

Demo.java

Next, we need to the code that will interact with the user and call the Serviceability selectCmDevice API.

  1. Click on the src folder, and choose New | Package
  2. Name the new package com.cisco.sxml.demo
  3. Right Click on the com.cisco.sxml.demo package and choose New | Class
  4. Name the new class Demo.java
  5. Put the code from attached Demo.java into your class.

Calling the Serviceability selectCmDevice API

The following code in Demo.java uses the generated classes to connect to the Risport service and make the selectCmDevice request. You can use a similar pattern for calling any of the Serviceability APIs.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
/*** Select devices using Risport selectCmDevice */
private void selectDevices() {
// Instantiate the wsimport generated Serviceability API Service client --
// see the wsimport comments in the class javadocs above
RISService risportService = new RISService();
RisPortType risportPort = risportService.getRisPort();
// Set the URL, user, and password on the JAX-WS client
String hostUrl = "https://" + Demo.ucHost
+ ":8443/realtimeservice2/services/RISService";
((BindingProvider) risportPort).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY, hostUrl);
((BindingProvider) risportPort).getRequestContext().put(
BindingProvider.USERNAME_PROPERTY, Demo.ucAdmin);
((BindingProvider) risportPort).getRequestContext().put(
BindingProvider.PASSWORD_PROPERTY, Demo.ucPswd);
// create and populate the selectCmDevice request
SelectCmDevice sxmlParams = new SelectCmDevice();
CmSelectionCriteria criteria = new CmSelectionCriteria();
long maxNum = 200;
long modelNum = 255;
ArrayOfSelectItem items = new ArrayOfSelectItem();
//create a select item criteria to retrieve devices with names matching "test"
SelectItem item = new SelectItem();
item.setItem("test");
items.getItem().add(item);
criteria.setMaxReturnedDevices(maxNum);
criteria.setModel(modelNum);
criteria.setDeviceClass("Phone");
criteria.setStatus(""Any");
criteria.setSelectBy("Name");
criteria.setSelectItems(items);
sxmlParams.setCmSelectionCriteria(criteria);
//make selectCmDevice request
SelectCmDeviceReturn selectResponse = risportPort.selectCmDevice("",
criteria);
//display the number of devices returned
long totalNumber = selectResponse.getSelectCmDeviceResult()
.getTotalDevicesFound();
Demo.informUser("TotalNumberFound=" + totalNumber + "%n");
//return the name of each device returned
for (int i = 0; i < totalNumber; i++) {
ArrayOfCmDevice deviceArray = selectResponse
.getSelectCmDeviceResult().getCmNodes().getCmNode().get(i)
.getCmDevices();
int numDevices = deviceArray.getCmDevice().size();
for (int j = 0; j < numDevices; j++) {
String deviceName = deviceArray.getCmDevice().get(j).getName();
String deviceIPAddress = deviceArray.getCmDevice().get(j).getIpAddress();
Demo.informUser("DeviceName=" + deviceName + " IP Address= " + deviceIPAddress + "%n");
}
}
}

Running the Sample Project

After you have generated the classes and added the code to Demo.java in your project, you are ready to run the sample and connect to your Cisco Unified CM.

You will need to have the following information:

  • The IP address or hostname for your Cisco Unified CM
  • The admin user id and password.

Adding the Cisco Unified CM SSL certificate to your keystore

Serviceability uses HTTPS, so you need to install the UC applications SSL certificate into your local keystore in order to run the sample app.

Download the Cisco Unified CM SSL Certificate

You can download the certificate from the UC manager using your browser. Here are the steps to do so using Firefox.

  1. In Firefox, go to https://<cucm-host>:8443
  2. Login with the Unified CM admin credentials.
  3. In your browser address window, you will see a small lock icon
  4. Click on the lock.
  5. Click more information.
  6. Click View Certificate
  7. Click Details
  8. Click Export.
  9. Save the certificate into a known place on your local machine.

Add the certificate to your java keystore

You can run the following command from the command line to add the certificate file to your local keystore.

1
$ JAVA_HOME/bin/keytool -import -alias <some descriptive name> -file <file name> -keystore

 

For Windows/Linux

 

The keystore is located here: $JAVA_HOME/jre/lib/security/jssecacerts

 

For Mac OS

 

The keystore is located here: $JAVA_HOME/lib/security/jssecacerts

 

and JAVA_HOME is located here: /System/Library/Frameworks/JavaVM.framework/Versions/<your version>/Home

 

Run the Sample Project

From the command line:

  1. Change to the bin directory in the directory that you created for this project (sxml-demo)
  2. Run the following command:
    3. 1
    $ java -cp . com.cisco.sxml.demo.Demo
  3. Enter the IP or host name for your Cisco Unified CM.
  4. Enter the Admin user id.
  5. Enter the Admin password.
  6. The program will display the Product information for that registered device.

If you encounter issues running the sample project, you may want to examine the Serviceability logs from Cisco Unified Communications Manager.

Next Steps

  • You can expand the sample and experiment by calling additional Serviceability APIs.

Back to Top