MBeans aus Webservices erzeugen

Dieses Dokument ist eine Schritt-für-Schritt-Anleitung für Entwickler, wie man MBeans aus einem bestehenden Webservice generiert. Die Automation Engine unterstützt Webservices durch die Verwendung von MBeans in Kombination mit dem JMX Agent. Viele Hersteller bieten aber anstelle von MBeans zumeist Webservices an, die den Zugriff auf ihre Anwendungen ermöglichen.

Hinweise:

  • Diese Anleitung setzt Kenntnisse von Java und Webservices voraus
  • AE bietet weder Unterstützung für Webservices noch für MBeans
  • 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!

Diese Seite beinhaltet Folgendes:

Voraussetzungen

  • JMX-Agent
  • Zugriff auf das Webservice (WDSL, URL, Parameter)
  • Apache Axis (kostenlos erhältlich)

Installation

Apache Axis einrichten

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

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 IDE Eclipse verwenden. Geben Sie die WSDL-Adresse http://www.webservicex.com/CurrencyConvertor.asmx?wsdl als Eingabeparameter an.

    Es werden die folgenden Java-Klassen erzeugt:

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
    • Die Schnittstelle hat denselben Namen wie die Klasse plus der Endung MBean
  • Im folgenden Beispiel heißt die Klasse Converter und die Schnittstelle 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 Webservice-Aufruf. Sie verwendet dabei die generierten Java-Klassen. Sie erzeugt eine Instanz des Service-Locators und ruft die MethodegetCurrencyConvertorSoap 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 umgewandelt, da nur einfache Datentypen in MBeans verwendet werden dürfen. Das Ergebnis, d.h. der aktuelle Währungs-Umrechnungskurs, wird zurückgeliefert.

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 Verwendung 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. Hier können Sie die JAR-Datei über einen Menübefehl direkt erzeugen.

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

Hinweise:

  • Unter UNIX muss der Strichpunkt (;) durch einen Doppelpunkt (:) ersetzt werden.
  • Der JMX-Agent benötigt keinen Application Server, sondern kann auch eigenständig laufen. Es genügt, die Java-Version 5 zu installieren. Sie enthält die erforderlichen JMX-Packages in der Version 1.2.

Verwendung

JMX-Job anlegen

  • Melden Sie sich mit dem AE am Automic Web Interface-System an.
  • Legen Sie einen JMX-Job an und wählen Sie auf dessen Registerkarte Attribute den JMX-Agenten aus, der das MBean enthält. 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 KategorieMBean Server die Funktion MBean registrieren mit einem Doppelklick aus.

    • Hinweis: 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 Klassennamen des MBeans ein. In unserem Beispiel ist das com.uc4.ws.Converter.
  • Im Feld Objektname 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.

    • Hinweise:

    • Der Domänenname darf die folgenden Zeichen nicht enthalten: :, * oder ?
    • 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: Eigenschaften=Wert.
      • Die Eigenschaft darf keinem Attribut des MBeans entsprechen.
      • Geben Sie zumindest eine Schlüsseleigenschaft an.
      • Die Anzahl der Schlüsseleigenschaften ist nicht begrenzt und auch die Reihenfolge unerheblich.
      • Eine Schlüsseleigenschaft darf keines der folgenden Zeichen enthalten: Anführungszeichen, Kommas, :, =, * oder ?

    Best-Practice-Beispiele finden Sie unter Java Management Extensions (JMX) - Best Practices.

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

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. Doppelklicken Sie auf die Funktion Operation ausführen in der Kategorie Operations.

    • Hinweis: 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 die Registerkarte 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 beispielsweise, dass das MBean den Umrechnungskurs von Dollar in Euro liefert.
  • Führen Sie den JMX-Job aus. Im Report wird der Umrechnungskurs ausgegeben.

    • Hinweis: Lesen Sie den Report mit der Script-Funktion PREP_PROCESS_REPORT aus, um die Werte, die MBeans zurückliefern, in der weiteren Verarbeitung nutzen zu können.