Spring Study Notes - Copyright © 2010 Gavin Lasnitzki Index   Notes   Objectives
Spring JMX

20. JMX

20.1. Introduction Key

Objectives: 6.1 JMX Architecture

The JMX technology was added to the platform in the Java 2 Platform, Standard Edition (J2SE) 5.0 release
The JMX specification defines the architecture, design patterns, APIs, and services in the Java programming language for management and monitoring of applications and networks.

Using the JMX technology, a given resource is instrumented by one or more Java objects known as Managed Beans, or MBeans.
These MBeans are registered in a core-managed object server, known as an MBean server.
The MBean server acts as a management agent and can run on most devices that have been enabled for the Java programming language.

The JMX technology defines standard connectors (known as JMX connectors) that enable you to access JMX agents from remote management applications. JMX connectors use different protocols provide the same management interface.

Spring's JMX support provides four core features:

  • The automatic registration of any Spring bean as a JMX MBean.
  • A flexible mechanism for controlling the management interface of your beans.
  • The declarative exposure of MBeans over remote, JSR-160 connectors.
  • The simple proxying of both local and remote MBean resources.

20.2. Exporting your beans to JMX

Objectives: 6.3 Spring JMX (server)

The core class in Spring's JMX framework is the MBeanExporter, responsible for taking your Spring beans and registering them with a JMX MBeanServer.

 

The MBeanExporter must not be lazily initialized.
By default, all public properties of the bean are exposed as attributes and all public methods (bar those inherited from the Object class) are exposed as operations.

20.2.1. Creating an MBeanServer Key Question

Spring will attempt to locate the running MBeanServer and register your beans with that server (if any).
You can create an MBeanServer instance declaratively by adding an instance of the org.springframework.jmx.support.MBeanServerFactoryBean class to your configuration.


 

20.2.2. Reusing an existing MBeanServer

Use the agentId to look up a specific MBeanServer in the environment.

20.2.3. Lazy-initialized MBeans

If you configure a bean with the MBeanExporter that is also configured for lazy initialization, then the MBeanExporter will register a proxy with the MBeanServer and will defer obtaining the bean from the container until the first invocation on the proxy occurs.

20.2.4. Automatic registration of MBeans

All valid MBeans can automatically be registered using:

Note: "spring:mbean=true" is a magic value that is used to detect JMX beans.

20.2.5. Controlling the registration behavior Question

 

Registration behavior Explanation

REGISTRATION_FAIL_ON_EXISTING

This is the default registration behavior. If an MBean instance has already been registered under the same ObjectName, the MBean that is being registered will not be registered and an InstanceAlreadyExistsException will be thrown. The existing MBean is unaffected.

REGISTRATION_IGNORE_EXISTING

If an MBean instance has already been registered under the same ObjectName, the MBean that is being registered will not be registered. The existing MBean is unaffected, and no Exception will be thrown.

This is useful in settings where multiple applications want to share a common MBean in a shared MBeanServer.

REGISTRATION_REPLACE_EXISTING

If an MBean instance has already been registered under the same ObjectName, the existing MBean that was previously registered will be unregistered and the new MBean will be registered in its place (the new MBean effectively replaces the previous instance).

 

20.3. Controlling the management interface of your beans

By default all of the public properties and methods of each exported bean was exposed as JMX attributes and operations respectively.

20.3.1. The MBeanInfoAssembler Interface Key

The default implementation, org.springframework.jmx.export.assembler.SimpleReflectiveMBeanInfoAssembler, simply defines a management interface that exposes all public properties and methods.

20.3.2. Using source-Level metadata

Using the MetadataMBeanInfoAssembler you can define the management interfaces for your beans using source level metadata
The reading of metadata is encapsulated by the org.springframework.jmx.export.metadata.JmxAttributeSource interface (implemented by AttributesJmxAttributeSource for Commons Attributes and AnnotationJmxAttributeSource for Java 5)

The MetadataMBeanInfoAssembler must be configured with an implementation instance of the JmxAttributeSource interface for it to function correctly (there is no default).

20.3.3. Using JDK 5.0 Annotations Question

To mark a bean for export to JMX, you should annotate the bean class with the ManagedResource attribute.
Each method you wish to expose as an operation must be marked with the ManagedOperation attribute.
Each property you wish to expose must be marked with the ManagedAttribute attribute.

 

20.3.4. Source-Level Metadata Types

Source-Level Metadata Types

Purpose Commons Attributes Attribute JDK 5.0 Annotation Attribute / Annotation Type
Mark all instances of a Class as JMX managed resources ManagedResource @ManagedResource Class
Mark a method as a JMX operation ManagedOperation @ManagedOperation Method
Mark a getter or setter as one half of a JMX attribute ManagedAttribute @ManagedAttribute Method (only getters and setters)
Define descriptions for operation parameters ManagedOperationParameter @ManagedOperationParameter and @ManagedOperationParameters Method

Source-Level Metadata Parameters

Parameter Description Applies to
ObjectName Used by MetadataNamingStrategy to determine the ObjectName of a managed resource ManagedResource
description Sets the friendly description of the resource, attribute or operation ManagedResource, ManagedAttribute, ManagedOperation, ManagedOperationParameter
currencyTimeLimit Sets the value of the currencyTimeLimit descriptor field ManagedResource, ManagedAttribute
defaultValue Sets the value of the defaultValue descriptor field ManagedAttribute
log Sets the value of the log descriptor field ManagedResource
logFile Sets the value of the logFile descriptor field ManagedResource
persistPolicy Sets the value of the persistPolicy descriptor field ManagedResource
persistPeriod Sets the value of the persistPeriod descriptor field ManagedResource
persistLocation Sets the value of the persistLocation descriptor field ManagedResource
persistName Sets the value of the persistName descriptor field ManagedResource
name Sets the display name of an operation parameter ManagedOperationParameter
index Sets the index of an operation parameter ManagedOperationParameter

20.3.5. The AutodetectCapableMBeanInfoAssembler interface

The AutodetectCapableMBeanInfoAssembler interface which extends the MBeanInfoAssembler interface to add support for autodetection of MBean.

The only problem with this approach is that the name of the JmxTestBean now has business meaning.

20.3.6. Defining management interfaces using Java interfaces Question

Although the standard mechanism for exposing MBeans is to use interfaces and a simple naming scheme, the InterfaceBasedMBeanInfoAssembler extends this functionality by removing the need for naming conventions, allowing you to use more than one interface and removing the need for your beans to implement the MBean interfaces.

 

20.3.7. Using MethodNameBasedMBeanInfoAssembler Question

The MethodNameBasedMBeanInfoAssembler allows you to specify a list of method names that will be exposed to JMX as attributes and operations.

20.4. Controlling the ObjectNames for your beans Key

20.4.1. Reading ObjectNames from Properties

You can configure your own KeyNamingStrategy instance and configure it to read ObjectNames from a JMX Properties instance rather than use bean key. The KeyNamingStrategy will attempt to locate an entry in the Properties with a key corresponding to the bean key. If no entry is found or if the Properties instance is null then the bean key itself is used.

20.4.2. Using the MetadataNamingStrategy

If no objectName has been provided for the ManagedResource annotation, then an ObjectName will be created with the following format: [fully-qualified-package-name]:type=[short-classname],name=[bean-name].

20.4.3. The <context:mbean-export/> element

When defining an instance of this subclass, the namingStrategy, assembler, and attributeSource configuration is no longer needed, since it will always use standard Java annotation-based metadata (autodetection is always enabled as well).

20.5. JSR-160 Connectors

20.5.1. Server-side Connectors

20.5.2. Client-side Connectors Key

20.5.3. JMX over Burlap/Hessian/SOAP

20.6. Accessing MBeans via Proxies

20.7. Notifications

20.7.1. Registering Listeners for Notifications

20.7.2. Publishing Notifications

20.8. Further Resources