Chapter 3. Adaptors

Chapter 3. Adaptors
Prev		Next

Table of Contents

Http Adaptor

Introduction
Security
Usage
Available requests

XSLTProcessor

Introduction
Attributes
XSL Development

RMI Adaptors and RMI Connector

Introduction
JRMP Adaptor
JRMP Adaptor over SSL
IIOP Adaptor

Http Adaptor

Carlos Quiroz

Revision History
Revision $Revision: 1.9 $	$Date: 2002/01/30 22:02:58 $

Introduction

The http adaptor offers a basic way to interface with an OpenJMX agent. It contains a HTTP 1.0 server which is able to translate HTTP requests to JMX requests. It has some limitations tough, like not being able to manipulate data which are not Strings, numbers or booleans. As an advantage HTTP traffic is usually enabled on firewalls and the universality of the browser client.

The OpenJMX HttpAdaptor is built basically to serve XML data. Requests are made in the usual http way and they are answered by default constructing a XML tree. However you can "skin" it by defining a ProcessorMBean, which has the task to handle the XML tree and do something with it. The processor will also be responsible to serve requests not understood by the server. In this way an appropriate processor can serve images and raw html. Currently there are two Processors defined:

DefaultProcessorMBean: It does not modify the XML tree limiting itself to publish the tree as text. Defining the content-type as text/xml. This usually means that you'r browser will display the XML text. This processor won't server any data besides the XML files.
XSLTProcessorMBean: This processor takes the XML tree and transforms it to HTML by means of XSLT. This requires that you use some JAXP-compliant XSLT. It has been tested with Xalan XSLT processor, and Saxon XSLT processor (which at time of writing does not work with any of the Saxon versions). The processor is also able to serve images and raw HTML data.
VelocityProcessorMBean: To be built...

As the processor is an MBean it means you can deploy it and modify it on runtime. The HttpAdaptorMBean defines two methods to set the Processor. If no processor is defined or an error is found, the DefaultProcessor is used.

The HttpAdaptor is an MBean defined in the interface HttpAdaptorMBean. It contains the following parameters.

Port: Defines the port in which the server will be listening to. By default is 8080.
Host: Defines the host name in which the server will be listening to. By default is localhost. This means that you can't access the server from another computer. This is good for security reasons. Forcing you to explicitly open the server.
Alive: Boolean property which tells whether the server is running or not.
Processor: This sets the processor to be used after the XML tree construction. If set the ProcessorName is set to null.
AuthenticationMethod: Sets the authentication method. Valid values are none, basic, digest. Please refer to the security chapter
ProcessorName: This sets the MBean's ObjectName to be used as XML processor. If set then Processor is set to null. The MBean has to implement the openjmx.adaptor.http.ProcessorMBean interface
SocketFactory: Replaces the default socket factory with another, for example, the openjmx.adaptor.http.ssl.SSLFactory

Security

The HttpAdaptor is in no way guaranteed to be secure. However basic authentication is available.

Basic Authentication

The Basic Authentication method provides a weak form of protection. When it is set your browser should prompt you for a username and password which are compared with the ones stored in the Adaptor. To add a username/password pair use the addAuthorization method. As mentioned before the basic authentication is weak since your username and password are sent with a weak encoding (Base64). However it can be prefectly used in secured networks or via enabling SSL.

SSL support

The HttpAdaptor can use SSL instead of normal sockets. For that is necessary three steps:

Install JSSE:
JSSE is necessary to run the Adaptor with SSL support. It is possible to use either JSSE version 1.0.2 available here, or JDK 1.4. JSSE comes with 3 jar files which should be added to your classpath: jsse.jar, jcert.jar and jnet.jar. Another alternative is to put those files at your JAVA_HOME/lib/ext dir. In case you are using JDK 1.4 you don't need to do this

Create server certificate:
Use the keytool command to create a server certificate. For example
keytool -genkey -keystore certs -keyalg rsa -alias openjmx
Where certs is the file name, where to store the keystore. and alias is any name you want to give to the keystore. You will be prompted for a password for the keystore and the key itself. Notice that your browser will probably complain about the vailidty of the key since it was signed by yourself.

Configure HttpAdaptor:
Finally you should change the default socket factory for a SSL factory. To do that you should use the SocketFactory attribute passing a openjmx.adaptor.http.ssl.SSLFactory object. The SSLFactory object should be previoulsy configured with your keystore and key.

After this you can start the HttpAdaptor as usual and point to https://host:port instead of http://host:port

SSLFactory

The SSLFactory contains several parameters you need to configure to find the certificate keystore. They are in the SSLFactory Management interface

KeyStoreType: Sets the keystore type. If you used the keytool command this is JKS
KeyStoreFileName: Filename of the certificate file
KeyStorePassword: Keystore password
KeyManagerAlgorithm: Keymanagers's algorithm, by default is SunX509
KeyManagerPassword: Keymanagers's password
SSLProtocol: SSL's protocol, by default is SSLv3

Usage

To use the HttpAdaptor you should instantatiate the MBean and register it to the right server. Later you can set up the desired parameters and invoke start to init the operation. Remember to add a JAXP-compliant parser such as xerces to the CLASSPATH. If you want to use the XSLTAdaptor you should also add xalan.jar to the CLASSPATH. If you want to use SSL add the JSSE jar files

Example 3.1. Instantiating the HttpAdapter

import openjmx.adapter.http.HttpAdapter;

MBeanServer server = ...;
HttpAdapter adapter = new HttpAdapter();
ObjectName name = new ObjectName("Server:name=HttpAdapter");
server.registerMBean(name, adapter);
adapter.setPort(XXX);
adapter.setHost("XXX");
adapter.start();

or...
server.createMBean("openjmx.adaptor.http.HttpAdaptor", name, null);
server.registerMBean(name, adapter);
server.setAttribute(name, new Attribute("Port", new Integer(XXX)));
server.setAttribute(name, new Attribute("Host", "XXX"));
server.invoke(name, "start", null, null);

If you wan to use a non-default Processor. You may instantiate and install it as follow

Example 3.2. Installing a non-default Processor

import openjmx.adapter.http.XSLTProcessor;

MBeanServer server = ...;
ObjectName name = new ObjectName("Server:name=HttpAdapter");
ObjectName processorName = new ObjectName("Server:name=XSLTProcessor");
server.createMBean("openjmx.adaptor.http.HttpAdaptor", name, null);
server.createMBean("openjmx.adaptor.http.XSLTProcessor", processorName, null);
server.registerMBean(name, adapter);
server.setAttribute(name, new Attribute("ProcessorName", processorName);

Available requests

The HttpAdaptor works by interpreting requests and executing some action. The Adaptor has a list of available requests and they produce an XML ouput tree (Or an exception...). New request handlers can be easily added if required by creating a openjmx.adaptor.http.HttpCommandProcessor implementation, and add it to the HttpAdaptor. However this shouldn't be normally done by common users.

The following is a list of the currently available requests, and the results and parameters required.

http://host:port/serverbydomain Returns a list of the MBeans available in the server grouped by domain. The result tree is as follows:
```
<Server>
	<Domain name="Http">
		<MBean classname="openjmx.adaptor.http.HttpAdaptor" description="HttpAdaptor MBean" objectname="Http:name=HttpAdaptor"></MBean>
		<MBean classname="openjmx.adaptor.http.XSLTProcessor" description="XSLT Processor" objectname="Http:name=XSLTProcessor"></MBean>
	</Domain>
	<Domain name="JMImplementation">
		<MBean classname="javax.management.MBeanServerDelegate" description="" objectname="JMImplementation:type=MBeanServerDelegate"></MBean>
	</Domain><Domain name="Test">
</Server>
							
```
The request can accept the following parameters:
- instanceof: Filters the MBeans whether they are instance of the class. For instance http://host:port/serverbydomain?instanceof=javax.management.timer.Timer will produce a list of all timers
- querynames: Filters the MBeans by objectname for instance http://host:port/serverbydomain?querynames=*:* will produce a list of all mbeans whether http://host:port/serverbydomain?querynames=Test:* will only contain those MBeans in the Test domain
http://host:port/server Returns a list of the MBeans available in the server. The result tree is as follows:
```
<Server>
	<MBean objectname="Http:name=HttpAdaptor"></MBean>
	<MBean objectname="Http:name=XSLTProcessor"></MBean>
	<MBean objectname="JMImplementation:type=MBeanServerDelegate"></MBean>
</Server>
							
```
The request can accept the following parameters:
- instanceof: Filters the MBeans whether they are instance of the class. For instance http://host:port/serverbydomain?instanceof=javax.management.timer.Timer will produce a list of all timers

http://host:port/mbean?objectname=XXX Returns the description of the referred MBean. It requires that the target objectname is passed on the request. The result tree is as follows for the request http://host:port/mbean?objectname=Test:name=test1

<MBean classname="test.openjmx.adaptor.http.HttpAdaptorXMLTest$TestClass" description="" objectname="Test:name=test1">
	<Attribute availability="RO" description="" name="Double" type="java.lang.Double" value="0.0"/>
	<Attribute availability="RW" description="" name="Str" type="java.lang.String" value="t1"/>
	<Attribute availability="RO" description="" name="True" type="boolean"  value="true"/>
	<Constructor description="" name="test.openjmx.adaptor.http.HttpAdaptorXMLTest$TestClass">
		<Parameter description="" id="0" name="" type="java.lang.String"/>
	</Constructor>
	<Operation description="" impact="unknown" name="aMethod" return="java.lang.Boolean">
		<Parameter description="" id="0" name="" type="java.lang.String">
		</Parameter>
	</Operation>
	<Operation description="" impact="unknown" name="anotherMethod" return="void">
		<Parameter description="" id="0" name="" type="java.lang.String"></Parameter>
		<Parameter description="" id="1" name="" type="int"></Parameter>
	</Operation>
	<Notification description="test" name="name">
		<Type name="test1"></Type>
		<Type name="test2"></Type>
		</Notification>
</MBean>

The request can accept the following extra parameters:

attributes: if set to false as http://host:port/mbean?objectname=Test:name=test1&attributes=false no attributes are included in the result tree
operations: if set to false as http://host:port/mbean?objectname=Test:name=test1&operations=false no operations are included in the result tree
constructors: if set to false as http://host:port/mbean?objectname=Test:name=test1&constructors=false no constructors are included in the result tree
notifications: if set to false as http://host:port/mbean?objectname=Test:name=test1&notifications=false no notifications are included in the result tree

http://host:port/setattribute?objectname=XXX&attribute=XXX&value=XXX Sets the value of an attribute. This is an operation request rather that a data request. All operation requests are returned as a MBeanOperation tree, which looks as follow
```
<MBeanOperation>
	<Operation objectname="Test:name=test1" operation="setattribute" result="success"/>
</MBeanOperation>
							
```
or if there was an error it looks like
```
<MBeanOperation>
	<Operation errorMsg="Attribute Number not found" objectname="Test:name=test1" operation="setattribute" result="error"/>
</MBeanOperation>
							
```
The request requires the following parameters:
- objectname: Target objectname
- attribute: Attribute's name
- value: Attribute's value
http://host:port/invoke?objectname=XXX&operation=XXX&type0=XXX&value0=XXX... Invokes an operation on the target MBean
```
<MBeanOperation>
	<Operation objectname="Test:name=test1" operation="invoke" result="success" return="true"/>
</MBeanOperation>
							
```
The following parameters are required:
- objectname: Target objectname
- operation: Name of the operation
- typeX: Type of the parameter number X. They are enumerated starting from 0
- valueX: Value of the parameter number X. They are enumerated starting from 0

http://host:port/delete?objectname=XXX Removed the target MBean

<MBeanOperation>
	<Operation objectname="Test:name=test1" operation="delete" result="success"/>
</MBeanOperation>

The following parameters are required:

objectname: Target objectname

http://host:port/create?class=XXX&objectname=XXX&type0=XXX&value0=XXX... Creates a target MBean invoking the corresponding constructor
```
<MBeanOperation>
	<Operation objectname="Test:name=test1" operation="invoke" result="success" return="true"/>
</MBeanOperation>
							
```
The following parameters are required:
- classname: Target objectname
- objectname: Target objectname
- typeX: Type of the parameter number X. They are enumerated starting from 0
- valueX: Value of the parameter number X. They are enumerated starting from 0
http://host:port/constructors?classname=openjmx.adaptor.http.HttpAdaptor Queries the MBean server of the available constructors for a class name resulting on
```
<Class classname="openjmx.adaptor.http.HttpAdaptor">
	<Constructor name="openjmx.adaptor.http.HttpAdaptor">
		<Parameters ...>
		</Parameters>
	</Constructor>
</Class>
							
```
The following parameters are required:
- classname: Target classname

Prev	Home	Next
Chapter 2. Extensions	Up	XSLTProcessor