Generating MBeans from Web Services

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

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

    • Notes:

    • The domain name must not include the characters: :, * or ?
    • 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.
      • Specify at least one key property.
      • The number of key properties is not limited and the order is irrelevant.
      • A key property must not contain the following characters: quotation marks, commas, :, =, * or ?

    For best practice examples, see Java Management Extensions (JMX) - Best Practices.

  • 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 function JMX_INVOKE 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: Read the report using the script function PREP_PROCESS_REPORT so that the values supplied by the MBeans can be used for further processing.