14.0 Loading MBeans Dynamically Using MLet Service

14.3 Creating the MLet Service in the Agent

14.1 MLet Service : An Overview

MLet, the management applet service allows you to instantiate and register in the MBean Server, one or more MBeans coming from a remote URL. The MLet service does this by loading an MLet text file, which specifies the information on the MBeans to be obtained. The location of the MLet text file is specified by a URL. When an MLet text file is loaded, all classes specified in MLet tags are downloaded, and an instance of each MBean specified in the file is created and registered. This makes it possible to create dynamically extensible agents.

Moreover, the MLet itself is registered with the MBeanServer as a Standard MBean (i.e. javax.management.loading.MLet class implements the javax.management.loading.MLetMBean interface). Thus, the MLet service itself can be remotely managed.

14.2 Loading MBeans From a URL

In order to download an MBean, you must first have its corresponding MLet definition in a Text file. The contents of the MLet file is defined in the form of HTML like tag called <MLET> which specifies information about the MBeans to be loaded. The tag contains information for downloading the class, such as the classname and the location of its class file. You may also specify arguments to the constructor used to instantiate the MBean.

14.2.1 MLet Tags

The MLet service loads a URL, which identifies the file containing <MLET> tags, one for each MBean to be instantiated, in the Multi-Protocol agent. The MLET tag has the following syntax:

<MLET
CODE = class | OBJECT = serfile
ARCHIVE = "archivelist"
[CODEBASE = codebaseURL]
[NAME = MBeanName]
[VERSION = version]
>
[arglist]
;</MLET>

The elements of this tag are explained below:

CODE = class

This attribute specifies the full Java class name, including package name, of the MBean to be obtained. The compiled .class file of the MBean must be contained in one of the JAR files specified by the ARCHIVE attribute. Either the CODE or the OBJECT attribute must be present.

OBJECT = serfile

This attribute specifies the .ser file that contains a serialized representation of the MBean to be obtained. This file must be contained in one of the JAR files specified by the ARCHIVE attribute. If the JAR file contains a directory hierarchy, this attribute must specify the path of the file within this hierarchy, otherwise a match will not be found.

ARCHIVE = archiveList

This mandatory attribute specifies one or more JAR files containing MBeans or other resources used by the MBean to be obtained. One of the JAR files must contain the file specified by the CODE or OBJECT attribute. If archive list contains more than one file:

Each file must be separated from the one that follows it by a comma (,)

The whole list must be enclosed in double quote marks (""). All JAR files in the archive list must be stored in the directory specified by the code base URL, or in the same directory as the MLet file, which is the default code base when none is given.

CODEBASE = codebaseURL

This optional attribute specifies the code base URL of the MBean to be obtained. It identifies the directory that contains the JAR files specified by the ARCHIVE attribute. This attribute is used when the JAR files are not in the same directory as the MLet text file. If this attribute is not specified, the base URL of the MLet text file is taken as the code base URL.

NAME = MBeanName

This optional attribute specifies the string format of an object name to be assigned to the MBean instance when the MLet service registers it in the MBean server.

VERSION = version

This optional attribute specifies the version number of the MBean and associated JAR files to be obtained. This version number can be used to specify whether or not the JAR files need to be loaded from the server to update those already loaded by the MLet service. The version must be a series of non-negative decimal integers each separated by a dot (.), for example 2.14.

arglist

The optional contents of the MLet tag specify a list of one or more arguments to pass to the constructor of the MBean to be instantiated. The MLet service looks for a constructor with a signature that matches the types of the arguments specified in the arglist. Instantiating objects with a constructor other than the default constructor is limited to constructor arguments for which there is a string representation.

Each item in the arglist corresponds to an argument in the constructor. Use the following syntax to specify the argList:

where:

argumenttype is the class of argument (for example Integer).
argumentValue is the string representation of the value of the argument.

Please have a look at the Sample MLet file for your reference.

14.3 Creating the MLet Service in the Agent

Once the MLet file is defined, the URL for the same can be specified using the JMX Compiler UI or using the API.

Using JMX Compiler UI

Select Project -> Settings option. In the Settings Tree Structure, select JMX Standard Services -> Management Applet, which displays the Management Applet dialog on the right side.
Select the option Enable MLet Service.
Select the Add button to display the MLet URL dialog.
Specify the URL of the MLet Text file and click OK button to add the entry.

The default URL specified in this option is http://localhost:8080/sample-mlet.txt. For this, the remote server must be started at local host at port number 8080 and the MLet text file must be present in the specified directory. (In this example, the sample-mlet.txt file is in the current directory where the remote server is started).

Similarly, you can specify any number of URLs for creating the MLet Service.

Using API

The MLet Service can also be created by adding the relevant code directly in the generated main file. The following sample code snippet creates the MLet Service MBean, with the URL : http://localhost:8080/sample-mlet.txt. In this example, the web server must be started at local host at port number 8080 and the MLet text file must be present in the specified directory. (In this example, the sample-mlet.txt file is in the current directory where the web server is started).

//Registering the MLet Service
MLet mlet = new MLet();
name = "Services:type=MLet";
server.registerMBean(mlet,new ObjectName(name));
mlet.addURL(new URL("http://localhost:8080/sample-mlet.txt""));

While adding the above code snippet, we must import the package javax.management.loading.MLet.

14.4 Running the MLet Example

An example on the MLet service is present in the <Agent Toolkit Home>/examples/jmx/mlet directory. This is a simple example to illustrate the use of dynamic loading of management applet (MLet) provided by the XMOJO JMX implementation.

The Readme.html file explains the usage of the example and the steps involved in running the example .