Java EE/JMX Agent

Java EE/JMX

Java EE/JMX-Agent und IBM WebSphere

---

MBeans aus Webservices erzeugen

Leitfaden für die Erstellung von MBeans auf Basis von Webservices.

Diese Anleitung setzt Kenntnisse von Java und Webservices voraus.

Beachten Sie, dass Automic weder Support für die Webservices noch für die MBeans anbietet!

Allgemeines

Automation Engine unterstützt Webservices durch die Verwendung von MBeans mit dem JMX-Agenten. Viele Hersteller bieten aber anstelle von MBeans zumeist Webservices an, die den Zugriff auf ihre Anwendungen ermöglichen. Dieser Leitfaden zeigt Ihnen Schritt für Schritt wie Sie aus einem existierenden Webservice ein MBean erzeugen können. Als Beispiel wird das Webservice "CurrencyConvertor" verwendet, das Generic Objects Technologies Ltd zur Verfügung stellt. Es liefert die aktuellsten Währungsumrechnungskurse.

Voraussetzungen:

• einen JMX-Agenten
• Zugriff auf das Webservice (WDSL, URL, Parameter)
• Apache Axis (frei verfügbar)

Beachten Sie, dass Sie MBeans nur für synchrone Webservices erstellen können! Asynchrone Webservices sind im Gebrauch viel komplizierter und benötigen eine individuelle Handhabung.

Testen Sie das erzeugte MBean umfassend!

Installation

	1.	Apache Axis einrichten

• Laden Sie die Dateien des Apache Axis von http://ws.apache.org/axis herunter. Installieren Sie Apache Axis gemäß der Dokumentation.

	2.	Java-Klassen für den Aufruf des Webservices generieren

• Starten Sie das Tool "WSDL2Java" von Apache Axis. Dabei handelt es sich um einen Webservice-Wrapper-Generator. Als Entwicklungsumgebung können Sie beispielsweise auch Eclipse verwenden. Geben Sie die WSDL-Adresse "http://www.webservicex.com/CurrencyConvertor.asmx?wsdl" als Eingabeparameter an.

• Das Ergebnis werden die folgenden Java-Klassen erzeugt:

	3.	MBean für die Nutzung der Java-Klassen erzeugen

• In diesem Schritt erstellen Sie ein MBean, das die generierten Java-Klassen verwendet, um das Webservice über JMX aufzurufen.
  Einleitend einige Anmerkungen zu den Programmier-Richtlinien für MBeans:
  
• Ein Standard-MBean-Pattern besteht aus einem Interface und einer Klasse, die dieses implementiert. 
• Das Interface hat denselben Namen wie die Klasse plus der Endung "MBean".

• Im folgenden Beispiel heißt die Klasse "Converter" und das Interface "ConverterMBean.java". Erstellen Sie die beiden Dateien beispielsweise in einem Package namens "com.uc4.ws". Es folgt dazu der komplette Code des Interfaces und der Klasse:

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));
}
}

Die Methode "convertCurrency" enthält den Aufruf des WebServices und verwendet dabei die generierten Java-Klassen. Sie erzeugt eine Instanz des Service-Locators und ruft die Methode "getCurrencyConvertorSoap" auf, um einen SOAP-Stub zu erhalten. Dieses Pattern (locator-stub) ist in der Apache Axis Dokumentation beschrieben.

Der Stub nimmt den Aufruf des Webservices vor. Die Parameter werden von "java.lang.String" zu "NET.webserviceX.www.Currency" Objekten konvertiert, da nur einfache Datentypen in MBeans verwendet werden dürfen. Das Ergebnis, d.h. der aktuelle Währungs-Umrechnungskurs, wird zurückgeliefert.

	4.	JAR-Datei für das MBean und die Java-Klassen erstellen

• Erzeugen Sie eine gemeinsame JAR-Datei für die beiden Dateien des MBeans und der erzeugten Java-Klassen unter zur Hilfenahme eines Ant-Scripts. Im folgenden Beispiel wird eine Datei namens "exampleMBean.jar" generiert.

<?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>

In einer Entwicklungsumgebung wie Eclipse benötigen Sie kein Ant-Script und können die JAR-Datei über einen Menübefehl direkt erzeugen.

	5.	JMX-Agent mit dem MBean starten

• Nehmen Sie die erzeugte JAR-Datei sowie die JAR-Dateien des Apache Axis im classpath des JMX-Agenten auf. Der Aufruf, um den JMX-Agenten zu starten, sieht unter Windows wie folgt aus:

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

Unter UNIX muss der Strichpunkt ";" durch einen Doppelpunkt ":" ersetzt werden.

Der JMX-Agent benötigt keinen Application Server, sondern kann auch eigenständig laufen. Zur Laufzeit wird jedoch eine JMX-Implementierung vorausgesetzt. Um dies zu gewährleisten, reicht es die Java-Version 5 zu installieren. Sie enthält die erforderlichen JMX-Packages in der Version 1.2.

Verwendung

	1.	JMX-Job anlegen

• Melden Sie sich mit dem UserInterface am Automation Engine System an.
• Legen Sie einen JMX-Job an und wählen Sie in dessen Registerkarte Attribute den JMX-Agenten, der das MBean enthält, aus. Vergessen Sie auch nicht ein passendes Login-Objekt auszuwählen.
• Wechseln Sie auf die Registerkarte Form. Klicken Sie auf die Schaltfläche , um eine neue Zeile einzufügen. Damit das MBean genutzt werden kann, muss es zuerst am MBean-Server registriert werden. Wählen Sie daher in der Kategorie "MBean Server" die Funktion "MBean registrieren" mit einem Doppelklick aus.

Die Funktion JMX_CREATE_MBEAN legt eine Instanz des MBeans an und registriert es am lokalen MBean-Server.

• Geben Sie im Feld "Klasse" den vollständigen Klassenname des MBeans ein. In unserem Beispiel ist das "com.uc4.ws.Converter".
• Im Feld "Objekt name" ist die Bezeichnung einzutragen, die dem MBean zugewiesen werden soll. Dieser muss im MBean Server eindeutig sein. Die Bezeichnung besteht aus zwei Teilen, die mit Doppelpunkt ":" voneinander getrennt sind. Der erste gibt den Domänenamen an und der zweite die Schlüsseleigenschaften. In unserem Beispiel ist das "com.uc4:name=CurrencyConverter".

Der Domänename darf alle Zeichen außer ":", "*" und "?" enthalten. Um Kollisionen zwischen MBeans verschiedener Hersteller zu vermeiden, empfiehlt es sich für den Domänenamen den umgekehrten DNS-Namen Ihrer Firma zu verwenden.

Mit den Schlüsseleigenschaften weisen Sie den MBeans in der Domäne einen eindeutigen Namen zu. Sie werden mit Komma "," getrennt. Eine Schlüsseleigenschaft besitzt folgenden Aufbau: Eigenschaft=Wert. Die Eigenschaft muss keinem Attribut des MBeans entsprechen. Die Anzahl der Schlüsseleigenschaften ist nicht begrenzt und auch die Reihenfolge unerheblich. Eine Schlüsseleigenschaft darf alle Zeichen außer Hochkomma, Komma sowie ":", "=", "*" und "?" enthalten. Geben Sie zumindest eine Schlüsseleigenschaft an.

• Aktivieren Sie die Einstellung "Normal beenden, wenn bereits registriert".

• Speichern Sie den JMX-Job und führen Sie ihn aus. Das MBean wird dadurch am MBean Server registriert und ist jetzt auch im MBean-Browser zu sehen, wie der nächste Schritt zeigt.

	2.	MBean verwenden

• Das MBean kann über seine Operationen angesprochen und verwendet werden. Klicken Sie in der Registerkarte Form des JMX-Jobs auf die Schaltfläche , um eine neue Zeile einzufügen. Wählen Sie in der Kategorie "Operationen" die Funktion "Operation ausführen" mit einem Doppelklick aus.

Die Funktion JMX_INVOKE ruft eine Operation eines MBeans auf.

• Klicken Sie auf die Schaltfläche "Durchsuchen...", um den MBean-Browser zu öffnen.

• Wählen Sie auf der linken Seite das MBean "CurrencyConverter" aus. Die Tabelle auf der rechten Seite zeigt Ihnen welche JMX-Operationen für das MBean zur Verfügung stehen.
• Markieren Sie die Operation "convertCurrency" und klicken Sie auf OK. Die Felder "MBean Name" und "Operation" werden automatisch mit den korrekten Werten befüllt.
• Geben Sie im Feld "Parameter" zwei Währungskürzel getrennt durch Komma ein. Beispiel: "USD,EUR" bewirkt, dass das MBean den Umrechnungskurs von Dollar in Euro zurückgibt.
• Führen Sie den JMX-Job aus. Im Report wird der Umrechnungskurs ausgegeben.

Lesen Sie den Report mit der Scriptfunktion PREP_PROCESS_REPORT aus, um die Werte, die MBeans zurückliefern in der weiteren Verarbeitung nutzen zu können. Die Beispielsammlung enthält dazu die Beschreibung der nötigen Schritte.