Generating MBeans from Web Services

Guideline for the creation of MBeans based on Web services.

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.

General

The Automation EngineDiese Komponente steuert ein Automation Engine-System. Besteht aus verschiedenen Serverprozessen. 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. This guideline describes step by step how an MBean is generated from an existing Web service. The Web service "CurrencyConvertor" which is provided by Generic Objects Technologies Ltd serves as an example. It supplies currency exchange rates.

Requirements:

• JMX agent
• Access to the Web service (WDSL, URL, parameters)
• Apache Axis (freely available)

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.

Installation

	1.	Setting up Apache Axis

• Download the Apache Axis files from http://ws.apache.org/axis. Install them as described in the Apache Axis documentation.

	2.	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 Eclipse as your development environment. Specify the WSDL address http://www.webservicex.com/CurrencyConvertor.asmx?wsdl" as the input parameter.

• As a result, the following Java classes are generated:

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

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

	5.	Starting the JMX Agent"Programm, das die Ausführung von Verarbeitungen auf Zielsystemen wie z.B. Rechner oder Geschäftslösungen ermöglicht. Auch ein eigener Objekttyp in der Automation Engine. [Früher ""Executor"" genannt.] Siehe auch ""Host""." using an MBean

• IncludeScript, das häufig und in mehreren Objekten verwendet wird. Auch ein eigener Objekttyp in der Automation Engine. 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

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

	1.	Creating a JMX job

• Log on to the AE system using the UserInterfaceVeralteter Begriff. Ersetzt durch: Automic Web Interface.
• Create a JMX job and select the JMX agent which contains the MBean in its Attributes tab. Select a suitable LoginAnmeldedaten für Zielsysteme. Auch ein eigener Objekttyp in der Automation Engine. 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".

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

The domain name must not include the characters ":", "*" and "?". In order to avoid collisions between the MBeans of different vendors, Automic recommends using the DNS name of your company backwards as the domain name.

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 inverted commas, 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).

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

The function JMX_INVOKE calls an operation of an MBean.

• Click the "Search..." button in order to 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.

Read the report using the script function PREP_PROCESS_REPORT so that the values supplied by the MBeans can be used for further processing. The Sample Collection contains a description of the required steps.