This document is a step-by-step guide for developers on how to generate MBeans from an existing Web service. The Automation Engine supports Web services through the usage of MBeans in combination with the JMX Agent. Many vendors offer Web services rather than MBeans as interfaces that provide access to their applications.
Notes:
- Knowledge of Java and Web services is required in order to be able to fully understand this guideline.
- AE provides support neither for Web services nor for MBeans.
- MBeans can only be created for synchronous Web services. Using asynchronous Web services is much more difficult and must be handled individually.
- Thoroughly test the generated MBean.
This page includes the following:
Requirements
- JMX Agent
- Access to the Web service (WDSL, URL, parameters)
- Apache Axis (available for free)
Installation
Setting up Apache Axis
- Download the Apache Axis files from http://ws.apache.org/axis.
- Install them as described in the Apache Axis documentation.
Generating Java Classes for Calling the Web Service
-
Start the Apache Axis tool "WSDL2Java". This is a Web service wrapper generator. You can also use the IDE Eclipse as your development environment. Specify the WSDL address http://www.webservicex.com/CurrencyConvertor.asmx?wsdl" as the input parameter.
The following Java classes are generated:
Creating an MBean for using the Java classes
- This step describes the creation of an MBean that uses the generated Java classes to call the Web service via JMX.
A few initiatory notes on MBeans programming guidelines: - A standard MBean pattern consists of an interface and a class which implements it.
- The interface has the same name as the class plus the ending "MBean".
- In the following example, the class is called "Converter" and the interface "ConverterMBean.java". Create both files in the package "com.uc4.ws". This is followed by the full interface code and class:
ConverterMBean.java:
package com.uc4.ws;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
public interface ConverterMBean {
double convertCurrency(String fromCurrency, String toCurrency)
throws ServiceException, RemoteException, IllegalArgumentException;
}
Converter.java:
package com.uc4.ws;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import NET.webserviceX.www.Currency;
import NET.webserviceX.www.CurrencyConvertorLocator;
import NET.webserviceX.www.CurrencyConvertorSoap;
public class Converter implements ConverterMBean {
public double convertCurrency(String fromCurrency, String toCurrency)
throws ServiceException, RemoteException, IllegalArgumentException {
CurrencyConvertorLocator locator = new CurrencyConvertorLocator();
CurrencyConvertorSoap soap = locator.getCurrencyConvertorSoap();
return soap.conversionRate(
Currency.fromString(fromCurrency),
Currency.fromString(toCurrency));
}
}
The method "convertCurrency" contains the Web service call. Therefore, it uses the generated Java classes. It creates a service-locator instance and calls the method "getCurrencyConvertorSoap" in order to obtain a SOAP stub. This pattern (locator-stub) is described in the Apache Axis documentation.
The stub calls the Web service. The parameters are converted from "java.lang.String" to "NET.webserviceX.www.Currency" objects because only simple data types can be used in MBeans. The supplied result is the current currency conversion rate.
Creating the MBean's JAR file and the Java Classes
Create a common JAR file for the two files of the MBean and the generated Java classes using an ant script. The following example shows how the file "exampleMBean.jar" is generated.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project name="uc4" default="exampleMBean.jar">
<property name="classes_dir" value="bin" />
<target name="exampleMBean.jar" description="Web Service MBean">
<jar jarfile="exampleMBean.jar" basedir="${classes_dir}"/>
</target>
</project>
No ant script is required in development environments such as Eclipse. Here you can generate the JAR file via menu command.
Starting the JMX Agent Using an MBean
Include the generated JAR file and the Apache Axis JAR files in the JMX agent's classpath. The call for starting the JMX agent under Windows is shown below:
Java -cp axis.jar;commons-discovery-0.2.jar;commons-logging-1.0.4.jar;
wsdl4j-1.5.1.jar;saaj.jar;exampleMBean.jar;ucxjjmx.jar;jaxrpc.jar com/uc4/ex/jmx/UCXJMX
Notes:
- UNIX: use a colon (":") instead of a semicolon (";").
- The JMX agent does not require an application server but can run independently. It is sufficient to install the Java version 5 as it contains the required JMX packages of version 1.2.
Usage
Creating a JMX Job
- Log on to the AE system using the Automic Web Interface.
- Create a JMX job and select the JMX agent which contains the MBean in its Attributes tab. Select a suitable Login object.
- Switch to the Form tab. Click the
button in order to insert a new line. Register the MBean on the MBean Server by double-clicking the function "Register MBean" in the category "MBean Server".
Note: The JMX_CREATE_MBEAN function creates an MBean instance and registers it on the local MBean Server.
- Enter the MBean's full class name in the field "class". In this example it is "com.uc4.ws.Converter".
- Enter the term that should be assigned to the MBean in the field "Object name". This name must be unique in the MBean Server. It consists of two parts which are separated by a colon ":". The first part refers to the domain name and the second one to the key properties. This example uses the name "com.uc4:name=CurrencyConverter".
- The domain name must not include the characters ":", "*" and "?".
- The key properties assign a unique name to the MBeans within the domain. They are separated by commas ",". A key property is structured as follows: Properties=Value. The property must not correspond to an attribute of the MBean. The number of key properties is not limited and the order is irrelevant. A key property must not contain quotation marks, commas or ":", "=", "*" and "?". Specify at least one key property.
- Enter the term which should be assigned to the MBean in the field "Object name". This name must be unique in the MBean Server. It consists of two parts which are separated by a colon ":". The first part refers to the domain name and the second one to the key properties. This example uses the name "com.uc4:name=CurrencyConverter".
Notes:
Tip: For best practice examples, see Java Management Extensions (JMX) - Best Practices.
Note: The domain name must not include the characters ":", "*" and "?". In order to avoid collisions between the MBeans of different vendors, it is recommended to use the DNS name of your company backwards as the domain name.
Note: The key properties assign a unique name to the MBeans within the domain. They are separated by commas ",". A key property is structured as follows: Properties=Value. The property must not correspond to an attribute of the MBean. The number of key properties is not limited and the order is irrelevant. A key property must not contain quotation marks, commas or ":", "=", "*" and "?". Specify at least one key property.
- Activate the setting "End normally if already registered".
- Store the JMX job and process it. By doing so, the MBean is registered on the MBean Server and is visible in the MBean browser (see step 2).
Using the MBean
- The MBean can be addressed and used via its operations. Click the button in the JMX job's Form tabin order to insert a new line. Double-click the function "Execute operation" in the category "Operations".
Note: The JMX_INVOKE function calls an operation of an MBean.
- Click Searchto open the MBean browser.
- Select the MBean "CurrencyConverter" on the left. The table on the right shows the available JMX operations for the MBean.
- Highlight the operation "convertCurrency" and Click OK tab. The fields "MBean Name" and "Operation" are automatically filled with the correct values.
- Enter two currency codes in the field "Parameter" and separate them with a comma. Example: "USD,EUR" has the effect that the MBean returns the exchange rate for US Dollars to Euro.
- Execute the JMX job. The conversion rate is output in a report.
Note: Use the PREP_PROCESS_REPORT script function to read the report, and use the values supplied by the MBeans for further processing.