JMX MBean

Der Adapter ermöglicht den Zugriff auf MBeans des lokalen JMX-Servers. Dabei können MBeans gesucht, MBean-Attribute gelesen und gesetzt, MBean-Operationen aufgerufen sowie MBean-Metadaten und Schlüsseleigenschaften separat ausgegeben werden.

Dieser Adapter erwartet je nach gewählter Operation eine spezifische Input-XML-Struktur. Der Adapter gibt immer ein XML-Dokument aus, das in Abhängigkeit von der gewählten Operation Informationen über MBeans, die Ergebnisse der aufgerufenen MBean-Methoden oder ggf. Fehlermeldungen enthält.

Eigenschaften (Properties)

Operation

Bestimmt, welche Operation der Adapter durchführt

Mögliche Werte:

List MBeans: Alle verfügbaren MBeans mit Name, Domäne und Schlüsseleigenschaften auflisten (kein Input-XML-Dokument erforderlich)
Find MBeans: MBean anhand des Objektnamens suchen; erwartet ein spezifisches Input-XML-Dokument; siehe Operation Find MBeans
Execute Operations: JMX-Operationen ausführen; erwartet je nach gewünschter Operation ein spezifisches Input-XML-Dokument

Parameter

Adapter

Hauptklasse des Adapters (nicht verändern!)

Mögliche Werte: de.softproject.integration.adapter.jmx.JmxAdapter: Hauptklasse (Standard)

Statuswerte

`1`	Die Operation wurde erfolgreich ausgeführt.
`0`	Die Operation wurde erfolgreich ausgeführt, jedoch ohne Ergebnis.
`-1`	Die Operation ist aufgrund eines technischen Fehlers fehlgeschlagen.

Input

Dieser Adapter erwartet für die Operationen Find MBeans und Execute Operations eine adapterspezifische Input-XML-Struktur, siehe unten. Diese Input-XML-Struktur kann über XSL-Mappings in Abhängigkeit von den verarbeiteten Daten dynamisch generiert werden.

Operation: Find MBeans

Über die Operation Find MBeans können Sie nach MBeans suchen. Alle MBeans, die dem Suchmuster entsprechen, werden ausgegben. Der Adapter erwartet bei dieser Operation folgendes Input-XML-Dokument.

HTML/XML

<Elementname>
  <Query objectname="Suchausdruck" attribut="..." />
</Elementname>

Das Input-XML-Dokument besitzt ein beliebiges Wurzelement und beliebig viele Elemente <Query>. Jedes Element <Query> enthält im Attribut objectname einen Suchausdruck für den MBean-Objektnamen, der nach dem Muster Domänenname:Schlüssel bzw. Domänenname:Schlüsselname=Wert aufgebaut ist; siehe http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html.

Der Suchausdruck kann die Platzhalter (? und *) enthalten. Alle zusätzlich angegebenen Attribute werden unverändert zum Ausgabe-Dokument durchgereicht.

Beachten Sie:

Je nach verwendetem Applikations-Server können Namensauflösungen fehlerhaft implementiert sein. So löst der MBean-Server von JBoss Platzhalter ggf. nicht auf, wenn Sie in Schlüsselnamen und -werten stehen.
Jeder Objektname muss durch einen Schlüssel qualifiziert werden. Wenn alle Instanzen des JMX-Objekts angesprochen werden sollen, ergänzen Sie den Objektnamen um :*.

Beispiel

Die folgende Suchanfrage sucht innerhalb der Domänen de.softproject.X0 bis de.softproject.Xz nach allen MBeans, deren Schlüssel ( Key Property ) name mit X4 beginnt, und reicht ein Attribut sampleAttribute="1" ans Ausgabedokument weiter.

HTML/XML

<JMX>
  <Query objectname="de.softproject.X?:name=X4*" sampleAttribute="1" />
</JMX>

Der Adapter gibt beispielsweise folgendes XML-Dokument mit den Sucherergebnissen aus:

HTML/XML

<MBeans>
 <Query objectname="de.softproject.X?:name=X4*" sampleAttribute="value">
  <MBean objectname="de.softproject.X4:name=GlobalContextManager"
    domain="de.softproject.X4" keyProperties="name=GlobalContextManager">
    <KeyProperty name="name">GlobalContextManager</KeyProperty>
  </MBean>
  <MBean objectname="de.softproject.X4:name=X4Management"
    domain="de.softproject.X4" keyProperties="name=X4Management">
    <KeyProperty name="name">X4Management</KeyProperty>
  </MBean>
  </Query>
  </MBeans>

Operation: Execute Operations

Über die Operation Execute Operations können Sie MBean-Operationen aufrufen, Attribute lesen und setzen sowie MBean-Metadaten und Schlüsseleigenschaften separat ausgeben. Der grundsätzliche Aufbau des Input-XML-Dokument ist identisch wie bei der Operation Find MBeans, jedoch können innerhalb des Elements <Query> unterschiedliche Elemente einfügt werden. Diese Elemente repräsentieren Anweisungen, die im Folgenden erläutert werden.

Beachten Sie:

Wie bei Operation Find MBeans kann auch bei Operation Execute Operations der Suchausdruck in Attribut objectname die Platzhalter ? und * enthalten.
Jeder Objektname muss durch einen Schlüssel qualifiziert werden. Wenn alle Instanzen des JMX-Objekts angesprochen werden sollen, ergänzen Sie den Objektnamen um :*.

Metadaten auslesen

Das Kindelement <GetMetadata/> des Elements <Query> weist den Adapter an, sämtliche Metadaten der entsprechenden MBeans auszugeben:

Im Attribut class: Nennt die Implementierungsklasse
<Description>: Enthält einen Beschreibungstext der MBean
<Constructors>: Listet Konstruktoren mit zugehörigen Operationen und Beschreibung auf
<Attributes>: Führt alle Attribute der MBean auf
<Operations>: Führt alle Operationen der MBean mit Name, Beschreibung, Datentypen, Parametern usw.
<Notifications>: Führt ggf. Benachrichtigungen der MBean auf

HTML/XML

<Query objectname="Suchausdruck" attribut="wert">
   <GetMetadata/>
</Query>

Schlüsseleigenschaften separat ausgeben

Das Kindelement <ExpandKeyProperties/> des Elements <Query> weist den Adapter an, alle Schlüsseleigenschaften in jeweils einem separaten Element <Property> auszugeben:

HTML/XML

<Query objectname="Suchausdruck" attribut="wert">
   <ExpandKeyProperties/>
</Query>

Attributwerte auslesen

Das Kindelement <GetAttributeValue/> des Elements <Query> weist den Adapter an, Werte zu MBean-Attributen auszugeben, die in jeweils einem Kindelement <Attribute> im Attribut name angegeben werden:

HTML/XML

<Query objectname="Suchausdruck" attribut="wert">
   <GetAttributeValue>
      <Attribute name="Attribut-Name" />
   </GetAttributeValue>
</Query>

Attributwerte auslesen

Das Kindelement <SetAttributeValue/> des Elements <Query> weist den Adapter an, MBean-Attributwerte zu setzen. Dabei wird für jedes MBean-Attribut in einem Element <Attribute> festgelegt:

Im Attribut name: Name des zu setzenden MBean-Attributs
Im Attribut class: Datentyp des zu setzenden MBean-Attributs
Der Wert des MBean-Attributs wird im Elementinhalt angegeben.

HTML/XML

<Query objectname="Suchausdruck" attribut="wert">
   <SetAttributeValue>
      <Attribute name="Attribut-Name" class="Datentyp"></Attribute>
   </SetAttributeValue>
</Query>

MBean-Operationen aufrufen

Das Kindelement <InvokeOperation/> des Elements <Query> weist den Adapter an, eine MBean-Operation aufzurufen. Das Element <InvokeOperation/> muss im Attribut name den Namen der MBean-Operation enthalten. In beliebig vielen Kindelementen <Parameter> wird der jeweilige Parameterwert angegeben, im Attribut class wird der Datentyp des Parameterwerts definiert.

Folgende Datentyp-Angaben im Attribut class können verwendet werden:

boolean
char
byte
short
int
long
float

double
java.lang.Boolean
java.lang.Character
java.lang.Byte
java.lang.Short
java.lang.Integer
java.lang.Long

java.lang.Float
java.lang.Double
java.lang.String
java.math.BigInteger
java.math.BigDecimal
java.management.ObjectName

Da MBean-Parameter keine Namen besitzen, ist die Reihenfolge maßgeblich, in der diese notiert werden.

Ein Aufruf einer MBean-Operation erfolgt also durch eine nach folgendem Muster aufgebaute Input-XML-Struktur:

HTML/XML

<Query objectname="Suchausdruck" attribut="wert">
   <InvokeOperation name="MBean-Operation">
      <Parameter class="Datentyp">Parameterwert</Parameter>
   </InvokeOperation>
</Query>

Beispiel

Im folgenden Input-XML-Dokument werden Metadaten abgefragt, Schlüsseleigenschaften gelistet, MBean-Attribute gelesen und gesetzt sowie eine MBean-Operation mit zwei Parametern ausgeführt:

HTML/XML

<RootElement>
   <Query objectname="de.softproject.X?:name=X4Management">
      <GetMetadata/>
   </Query>
   <Query objectname="java.lang*:*">
      <ExpandKeyProperties/>
   </Query>
   <Query objectname="de.softproject.X4.WS*:*" text="enabling WebServices">
      <GetAttributeValue>
         <Attribute name="InService"/>
      </GetAttributeValue>
      <SetAttributeValue>
         <Attribute name="InService" class="boolean">true</Attribute>
      </SetAttributeValue>
   </Query>
   <Query objectname="de.softproject.X4:name=X4Management"
      description="Start a process">
      <InvokeOperation name="startProcessByName">
         <Parameter class="java.lang.String">1</Parameter>
         <Parameter class="java.lang.String">/Project/Folder/Process.wrf
         </Parameter>
      </InvokeOperation>
   </Query>
   </RootElement>