JMX MBean

The adapter enables access to MBeans of the local JMX server. MBeans can be searched, MBean attributes can be read and set, MBean operations can be called and MBean metadata and key properties can be output separately.

This adapter expects a specific input XML structure depending on the selected operation. The adapter always outputs an XML document that contains information about MBeans, the results of the called MBean methods or, if applicable, error messages, depending on the selected operation.

Properties

Operation

Determines which operation the adapter executes

Possible values:

List MBeans: List all available MBeans with name, domain and key properties (no input XML document required).
Find MBeans: Search MBean by object name; expects a specific input XML document; see operation Find MBeans
Execute Operations: Execute JMX operations; expects a specific input XML document depending on the desired operation.

Parameters

Adapter

Main class of the adapter (do not change!)

Possible values: en.softproject.integration.adapter.jmx.JmxAdapter: Main class (default)

Status values

`1`	The operation was executed successfully.
`0`	The operation was executed successfully, but without any result.
`-1`	The operation failed due to a technical error.

Input

This adapter expects an adapter-specific input XML structure for the operations Find MBeans and Execute Operations, see below. This input XML structure can be generated dynamically via XSL mappings depending on the processed data.

Operation: Find MBeans

You can search for MBeans using the Find MBeans operation. All MBeans that match the search pattern are output. The adapter expects the following input XML document for this operation.

HTML/XML

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

The input XML document has any root element and any number of <Query> elements. Each <Query> element contains a search expression for the MBean object name in the attribute objectname, which is structured according to the pattern domainname:key or domainname:keyname=value; see http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html.

The search expression can contain the wildcards (? and *). All additionally specified attributes are passed through to the output document unchanged.

Note:

Depending on the application server used, name resolution may be implemented incorrectly. For example, the MBean server from JBoss may not resolve placeholders if they are in key names and values.
Each object name must be qualified by a key. If all instances of the JMX object are to be addressed, add :* to the object name.

Example

The following search query searches within the domains de.softproject.X0 to de.softproject.Xz for all MBeans whose key ( Key Property ) name starts with X4 and passes an attribute sampleAttribute="1" to the output document.

HTML/XML

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

For example, the adapter outputs the following XML document with the search results:

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

The Execute Operations operation allows you to call MBean operations, read and set attributes and output MBean metadata and key properties separately. The basic structure of the input XML document is identical to the Find MBeans operation, see Operation: Find MBeans, but different elements can be inserted within the <Query> element. These elements represent instructions which are explained below.

Note:

As with Operation Find MBeans, with Operation Execute Operations the search expression in attribute objectname can contain the wildcards ? and *.
Each object name must be qualified by a key. If all instances of the JMX object are to be addressed, add :* to the object name.

Read metadata

The <GetMetadata/> child element of the <Query> element instructs the adapter to output all metadata of the corresponding MBeans:

In the attribute class: names the implementation class
<Description>: Contains a description text of the MBean
<Constructors>: Lists constructors with associated operations and description
<Attributes>: Lists all attributes of the MBean
<Operations>: Lists all operations of the MBean with name, description, data types, parameters, etc.
<Notifications>: Lists notifications from the MBean, if applicable.

HTML/XML

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

Output key properties separately

The child element <ExpandKeyProperties/> of the <Query> element instructs the adapter to output all key properties in a separate <Property> element each:

HTML/XML

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

Read attribute values

The <GetAttributeValue/> child element of the <Query> element instructs the adapter to output values to MBean attributes specified in each <Attribute> child element in the name attribute:

HTML/XML

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

Read attribute values

The <SetAttributeValue/> child element of the <Query> element instructs the adapter to set MBean attribute values. This is done by defining each MBean attribute in an <Attribute> element:

In the attribute name: Name of the MBean attribute to be set.
In the attribute class: data type of the MBean attribute to be set.
The value of the MBean attribute is specified in the element content.

HTML/XML

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

Call MBean operations

The <InvokeOperation/> child element of the <Query> element instructs the adapter to invoke an MBean operation. The <InvokeOperation/> element must contain the name of the MBean operation in the name attribute. In any number of child elements <Parameter> the respective parameter value is specified, in the attribute class the data type of the parameter value is defined.

The following data type specifications in the class attribute can be used:

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

Since MBean parameters do not have names, the order in which they are noted is decisive.

A call to an MBean operation is thus made by an input XML structure built according to the following pattern:

HTML/XML

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

Example

In the following input XML document, metadata is queried, key properties are listed, MBean attributes are read and set, and an MBean operation with two parameters is executed:

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>