3.1 MBean Fundamentals

An MBean represents a resource that a management system will monitor and control. The resource in question could be a device like a network card, a system resource such as a file or process, or an application component like a server-side container or service. In each case the MBean is the resource as far as the management system is concerned .

The JMX specification defines an MBean as a concrete Java class that

• Has one or more public constructors

• Implements its own corresponding MBean interface or the DynamicMBean interface

• Optionally implements the NotificationBroadcaster interface

3.1.1 The Management Interface

An MBean's constructors, the attributes and operations defined by the MBean interface that it implements, and the notifications that it generates make up the MBean's management interface. The MBean's Java class may have behavior beyond that exposed in the management interface but that behavior is not available to the management system.

Management systems access MBeans via an MBeanServer. Figure 3.1 illustrates the relationship among the three components . Note that there are two distinct interfaces in this picture. The management system has direct access to the MBeanServer interface, but it needs access to the MBean's management interface to manage the resource that the MBean represents. One of the MBeanServer's principal functions is to provide access to any MBean's management interface via a standard interface of its own.

The MBeanServer will be described in detail in Chapter 5. Here we will focus on just its MBean access methods in order to understand how MBean's management interfaces are exposed to management systems. There are six MBean access methods in the MBeanServer interface:

Object getAttribute(ObjectName objname, String attrname); 
AttributeList getAttributes(ObjectName objname,
  String[] attrnames);
MBeanInfo getMBeanInfo(ObjectName objname);
Object invoke(ObjectName objname, String method, Object[] params,
  String[] signature);
void setAttribute(ObjectName objname, Attribute attribute);
AttributeList setAttributes(ObjectName objname,
  AttributeList attributes);

The ObjectName parameters in these APIs refer to MBeans registered with the MBeanServer. The getAttribute() and getAttributes() methods return the values of the specified MBean's attributes, setAttribute() and setAttributes() set the values of the specified MBean's attributes, and invoke() executes an operation on the specified MBean.

The MBeanInfo object returned by the getMBeanInfo() method encapsulates metadata that describes the management interface of the MBean registered under the specified name . Figure 3.2 presents the static structure of this information.

The MBeanServer uses an MBean's MBeanInfo to implement its MBean access methods. The MBeanServer makes sure that no methods are invoked or attributes retrieved or updated that are not described in MBeanInfo . Management systems can use getMBeanInfo() to retrieve a complete description of an MBean's management interface. For example, management system consoles commonly use MBeanInfo to display MBeans in their GUIs.

3.1.2 The Introspection Algorithm

The MBeanServer uses a two-step process to collect MBean information for each MBean as it is registered:

1. It determines the kind of MBean being registered.

2. It asks a dynamic MBean for its MBean info or derives a standard MBean's MBean info via introspection.

There are two main kinds of MBeans: standard and dynamic. Here is the pseudocode for the algorithm that determines a given MBean's kind:

Let the MBean's Java class be C 
if C is abstract or C has no public constructors
  throw NotCompliantMBeanException
if C implements both CMBean and DynamicMBean
  throw NotCompliantMBeanException
if C implements CMBean
  return C is a CMBean StandardMBean
if C implements DynamicMBean
  return C is a DynamicMBean
for each superclass S of C
  if S implements both SMBean and DynamicMBean
    throw NotCompliantMBeanException
  if S implements SMBean
    return C is an SMBean StandardMBean
  if S implements DynamicMBean
    return C is a DynamicMBean

Once it has determined what kind of MBean it is registering, the MBeanServer has to record the MBean's MBeanInfo . That is a simple task for a dynamic MBean. With the exception of the ObjectName parameter, the methods in the DynamicMBean interface are identical to the MBeanServer's MBean access methods:

public interface DynamicMBean { 
  Object getAttribute(String attrname);
  AttributeList getAttributes(String[] attrnames);
  MBeanInfo getMBeanInfo();
  Object invoke(String method, Object[] params, String[] signature);
  void setAttribute(Attribute attr);
  AttributeList setAttributes(AttributeList attrs);
}

So the MBeanServer just has to ask the MBean for its MBeanInfo .

Things are a little more complex for a standard MBean. Because the MBeanServer can't depend on the presence of a getMBeanInfo() method, it uses another level of introspection and the "lexical design patterns" defined by the JMX specification to derive MBeanInfo from the MBean's MBean interface. Don't be confused by the words design pattern, we're not talking about object-oriented design patterns here; lexical design pattern is just another way of saying naming convention. These lexical design patterns are used to distinguish MBean attributes from MBean operations. An attribute is identified by the following pattern:

public

AttrType

get

AttrName

();             // attribute "getter" 
public void set

AttrName

(

AttrType

val);     // attribute "setter"

AttrType may be any Java type, but see the design considerations outlined in Section 3.3. AttrName is case sensitive, so getconnections() and getConnections() define two different attributes: connections and Connections , respectively. If both the attribute getter and setter are present, the attribute is a read/write attribute; if only the getter is present, the attribute is read-only; and if only the setter is present, the attribute is write-only. Finally if AttrType is boolean , the attribute getter may be defined by the pattern

public boolean is

AttrName

();

Note that only one form of getter is allowed for an attribute; that is, a Boolean attribute may have either a getAttrName() getter or an isAttrName() getter, but not both.

Methods defined by a standard MBean interface that don't match one of the attribute design patterns are taken to be operations. Like attributes, operations may take parameters of any valid Java type and return as a result a value of any valid Java type.