You can extend Rhino’s OA&M features many ways, including deploying a management component called a management applet (m-let) in the JMX MBean server running in each Rhino node. Below is an introduction to the JMX model, how JMX m-lets work, and how Rhino uses them.

What is JMX?

The Java for Management eXtentions (JMX) specification defines a standard way of instrumenting and managing Java applications. The JMX Instrumentation and Agent Specification, v1.2 (October 2002) summarises JMX like this:

excerpt from JMX specification 1.2

The Java Management extensions (also called the JMX specification) define an architecture, the design patterns, the APIs, and the services for application and network management and monitoring in the Java programming language. This chapter introduces all these elements, presenting the broad scope of these extensions. The JMX specification provides Java developers across all industries with the means to instrument Java code, create smart Java agents, implement distributed management middleware and managers, and smoothly integrate these solutions into existing management and monitoring systems. In addition, the JMX specification is referenced by a number of Java APIs for existing standard management and monitoring technologies.

How does JAIN SLEE use JMX?

The JAIN SLEE 1.1 specification mandates using the JMX 1.2.1 MLet (management applet) specification for management clients to gain access to the SLEE MBean server and SLEE MBean objects.

excerpt from the JAIN SLEE 1.1 specification

14.4 Accessing the MBean Server and SLEE MBean objects

The SLEE specification mandates the use of the JMX 1.2.1 MLet (management applet) specification in order for management clients to gain access to the SLEE MBean Server and SLEE MBean objects.

14.4.1 Requirements of the SLEE Vendor

Changed in 1.1: A SLEE vendor may allow the use of JMX Remote API 1.0 (JSR 160)

The SLEE specification requires that a SLEE vendor implement necessary functionality to load and instantiate management clients implemented as MLet MBeans. For example, the javax.management.loading.MLet MBean can be used by a SLEE implementation to perform parsing of a MLet text file and instantiation of the MBeans defined in it, however this method of loading MLet MBeans is not prescriptive.

The SLEE must ensure that the MBean Server that the MLets are registered with is the same MBean Server that the SLEE MBean objects are registered with (or a remote image of it) in order for the MLet to invoke the SLEE’s management operations.

The SLEE specification does not strictly define when during a SLEE’s lifetime management client MLets should be instantiated. However, the earliest that a SLEE implementation should instantiate MLets is after the initialization phase is complete and the SLEE is ready to accept management operations. MLets may be instantiated any time after this point at the discretion of the SLEE implementation.

A SLEE vendor may also optionally allow management clients to connect to the SLEE’s MBean Server via a remote connection established in accordance with the JMX Remote API 1.0 (JSR 160).

14.4.2 Requirements of the Management Client

Changed in 1.1: The use of JMX 1.2.1 is mandated.

The general requirements of any management client that accesses the SLEE MBean objects are as follows:

  • The management client may not hold any direct references to a SLEE MBean object. It may only reference a SLEE MBean object by its Object Name. In other words, it can only invoke a SLEE MBean object through a local or remote MBean Server, and it identifies the SLEE MBean object to be invoked by the Object Name of the SLEE MBean object. Interaction with a SLEE MBean via a proxy object such as that created by the javax.management.MBeanServerInvocationHandler class is acceptable also.

  • Since the management client cannot hold a direct reference to a SLEE MBean object, it cannot directly add or remove itself as a notification listener to a SLEE MBean object that implements the NotificationBroadcaster interface. Rather, the management client registers and removes a listener by invoking the MBean Server’s addNotificationListener and removeNotificationListener methods, passing to these methods the Object Name of the SLEE MBean object that the management client wants to begin or stop receiving notifications from.

There are two typical approaches to implementing a custom SLEE management client. The first approach is to implement the client as a MLet MBean. The second approach is to implement a SLEE management client using the JMX Remote API. A SLEE management client implemented as an MLet MBean behaves as a JMX connector or protocol adaptor. This MLet is registered with the SLEE MBean Server and provides an adaptation layer between the SLEE management operations and the management client.

The requirements of a management client MLet MBean are:

  • The MLet can be implemented as any type of MBean supported by the JMX 1.2.1 specification.

  • The MLet should implement the javax.management.MBeanRegistration interface. The preRegister method defined in this interface provides the MLet with the MBean Server instance that the SLEE MBean objects are registered with.

  • A suitable MLet text file or other documentation that provides the necessary codebase and instantiation class information should be provided with the MLet distribution.

A SLEE management client implemented using the JMX Remote API interacts with a remote image of the SLEE’s MBean server. The remote MBean server forwards management client requests to the real MBean server running in the SLEE, thereby bypassing the need for the management client vendor to provide an MLet that provides protocol adaptation layer functionality. This implementation approach assumes that the SLEE implementation the management client is connecting to allow clients to connect via a JMX Remote API connection.

What are m-lets?

An m-let is a management applet service that lets you instantiate and register one or more Java Management Beans (MBeans), from a remote URL, in the MBean server. The server loads text-based m-let configuration file that specifies information about MBeans to be loaded.

Tip Metaswitch typically uses m-lets to implement JMX protocol adaptors.

How does Rhino use m-lets?

Each node in a Rhino cluster runs an MBean server (Rhino {space-metadata-from:rhino-internal-version} uses the Java VM MBean server). When Rhino starts, it dynamically loads m-lets into those MBean servers, based on m-let text files stored in the following places:

  • Rhino SDK — $RHINO_HOME/config/mlet.conf

  • Production Rhino — $RHINO_HOME/node-XXX/config/permachine-mlet.conf, $RHINO_HOME/node-XXX/config/pernode-node-mlet.conf.

These configuration files conform to to the OpenCloud M-Let Config 1.1 DTD.

See the OpenCloud M-Let Config 1.1 DTD:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
Use:
    <!DOCTYPE mlets PUBLIC
        "-//Open Cloud Ltd.//DTD JMX MLet Config 1.1//EN"
        "http://www.opencloud.com/dtd/mlet_1_1.dtd">
-->

<!ELEMENT mlets (mlet*)>

<!--
The mlet element describes the configuration of an MLet.  It contains an
optional description, an optional object name, an optional classpath, mandatory
class information, and optional class constructor arguments.  Constructor
arguments must be specified in the order they are defined in the class
constructor.
-->
<!ELEMENT mlet (description?, object-name?, classpath?, class, arg*)>

<!--
The description element may contain any descriptive text about the parent
element.

Used in: mlet
-->
<!ELEMENT description (#PCDATA)>

<!--
The object-name element contains the JMX object name of the MLet.  If the name
starts with a colon (:), the domain part of the object name is set to the
domain of the agent registering the MLet.

Used in: mlet

Example:
    <object-name>Adaptors:name=MyMLet</object-name>
-->
<!ELEMENT object-name (#PCDATA)>

<!--
The classpath element contains zero or more jar-url elements specifying jars
to be included in the classpath of the MLet and an optional specification
identifying security permissions that should be granted to classes loaded
from the specifed jars.

Used in: mlet
-->
<!ELEMENT classpath (jar-url*, security-permission-spec?)>

<!--
The jar-url element contains a URL of a jar file to be included in the
classpath of the MLet.

Used in: classpath

Example:
    <jar-url>file:/path/to/location/of/file.jar</jar-url>
-->
<!ELEMENT jar-url (#PCDATA)>

<!--
The security-permission-spec element specifies security permissions based on
the security policy file syntax. Refer to the following URL for definition of
Sun's security policy file syntax:

http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax

The security permissions specified here are granted to classes loaded from the
jar files identified in the jar-url elements in the classpath of the MLet.

Used in: jar

Example:
    <security-permission-spec>
        grant {
            permission java.lang.RuntimePermission "modifyThreadGroup";
        };
    </security-permission-spec>
-->
<!ELEMENT security-permission-spec (#PCDATA)>

<!--
The class element contains the fully-qualified name of the MLet's MBean class.

Used in: mlet

Example:
    <class>com.opencloud.slee.mlet.mymlet.MyMlet</class>
-->
<!ELEMENT class (#PCDATA)>

<!--
The arg element contains the type and value of a parameter of the MLet class'
constructor.

Used in: mlet
-->
<!ELEMENT arg (type, value)>

<!--
The type element contains the fully-qualified name of the parameter type.  The
currently supported types for MLets are: Java primitive types, object wrappers
for Java primitive types, and java.lang.String.

Used in: arg

Example:
    <type>int</type>
-->
<!ELEMENT type (#PCDATA)>

<!--
The value element contains the value for a parameter.  The value must be
appropriate for the corresponding parameter type.

Used in: arg

Example:
   <value>8055</value>
-->
<!ELEMENT value (#PCDATA)>
<!ATTLIST mlet  enabled CDATA #IMPLIED >

Structure of the m-let text file

<mlets>
    <mlet enabled="true">
        <classpath>
            <jar-url> </jar-url>
            <security-permission-spec>
            </security-permission-spec>
        </classpath>
        <class> </class>
        <arg>
            <type></type>
            <value></value>
        </arg>
    </mlet>

    <mlet enabled="true">

    </mlet>

The m-let text file can contain any number of MLET tags, each for instantiating a different MBean.

  • classpath — The classpath defines the code source of the MBean to be loaded.

    • jar-url — The URL to be used for loading the MBean classes.

    • security-permission-spec — Defines the security environment of the MBean.

  • class — The main class of the MBean to be instantiated.

  • arg — There may be zero or more arguments to the MBean. Each argument is defined by an arg element. The set of arguments must correspond to a constructor defined by the MBean main class.

    • type — The Java type of the argument.

    • value — The value of the argument.

Note For details on m-lets included in Metaswitch Rhino, see JMX Remote Adaptor M-let
Previous page Next page
Rhino Version 3.1