Skip Headers
Oracle® Coherence Management Guide
Release 3.7.1

Part Number E22842-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 Registering Custom MBeans

Coherence provides the ability to manage and monitor custom MBeans within the management framework. Custom MBeans are MBeans that are specific to an application (including MBeans for the Java platform ). Custom MBeans are registered to a Coherence MBean server either declaratively in an XML file or programmatically.

The ability to integrate custom MBeans with Coherence MBeans allows administrators to update and view system and application information for all members in a cluster from a single location.

The following sections are included in this chapter:

3.1 Registering Custom MBeans Declaratively

Custom MBeans are registered declaratively within an MBean configuration override file named custom-mbeans.xml. At run time, Coherence uses the first instance of custom-mbeans.xml that is found in the classpath. See Oracle Coherence Developer's Guide for detailed information on configuration. MBeans are registered using either an MBean's class name, an MBean factory, or by running a query to locate MBeans.

Note:

Custom MBeans must be found at run time. Make sure to place the MBeans (or the library that contains the MBeans) in the classpath of a Coherence member, including the JMX management-enabled member.

The following topics are included in this section:

3.1.1 Creating an MBean Configuration File

The custom-mbeans.xml file is used to override the <mbeans> element of the operational deployment descriptor. Therefore, the root element must be the <mbeans> element. See the Oracle Coherence Developer's Guide for a complete descriptions of the elements that can be defined within the <mbeans> element.

To create the MBean configuration override file:

  1. Create a text file an save it as custom-mbeans.xml.

  2. Edit the file and create an empty <mbeans> node as follows:

    <mbeans>
    </mbeans>
    
  3. Save and close the file.

  4. Make sure the location of the custom MBean configuration override file is located in the classpath at run time and precedes the coherence.jar library.

    The following example demonstrates starting a cache server that uses a custom-mbeans.xml file that is located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

3.1.2 Registering MBeans Using a Class Name

The <mbean-class> element is used to register and instantiate an MBean using the MBean's fully qualified class name. The following example registers an MBean named com.MyMBean and gives the MBean an object name type=application.

<mbeans>
   <mbean id="100">
      <mbean-class>com.MyMBean</mbean-class>
      <mbean-name>type=application</mbean-name>
      <enabled>true</enabled>
   </mbean>
</mbeans>

As configured, the MBean can be managed remotely and includes the member where it is located as part of the object name. Therefore, the complete object name when the MBean is registered is:

Coherence:type=application,nodeId=<nodeId>

3.1.3 Registering MBeans From an MBean Factory

The <mbean-factory> and <mbean-accessor> elements are used to register and instantiate an MBean from a factory class. The following example registers the Java platform's MemoryMXBean MBean using the getMemoryMXBean accessor method from the java.lang.management.ManagementFactory class and gives the MBean an object name type=java,SubSystem=Memory.

<mbeans>
   <mbean id="2">
      <mbean-factory>java.lang.management.ManagementFactory</mbean-factory>
      <mbean-accessor>getMemoryMXBean</mbean-accessor>
      <mbean-name>type=java,SubSystem=Memory</mbean-name>
      <enabled>true</enabled>
   </mbean>
</mbeans>

As configured, the MBean can be managed remotely and includes the member where it is located as part of the object name. Therefore, the complete object name when the MBean is registered is:

Coherence:type=java,SubSystem=Memory,nodeId=<nodeId>

3.1.4 Registering MBeans Using a Query

The <mbean-query> element is used to query an MBean server when registering and instantiating MBeans. The member's default MBean server is queried by default but an MBean server can also be specified. The following example executes the java.lang:* query on the member's default MBean server to find MBeans to register.

<mbeans>
   <mbean id="3">
      <mbean-query>java.lang:*</mbean-query>
      <mbean-name>type=Platform</mbean-name>
      <enabled>true</enabled>
   </mbean>
<mbeans>

To specify an MBean server other than the member's default MBean server, enter the name of a default domain for the MBean server using the <mbean-server-domain> element. For example:

<mbeans>
   <mbean id="3">
      <mbean-query>java.lang:*</mbean-query>
      <mbean-server-domain>MyDomain</mbean-server-domain>
      <mbean-name>type=Platform</mbean-name>
      <enabled>true</enabled>
   </mbean>
</mbeans>

3.1.5 Specifying a Different MBean Configuration Override File

The tangosol.coherence.mbeans system property specifies an MBean configuration override file to be used instead of the default custom-mbeans.xml override file. For example:

-Dtangosol.coherence.mbeans=my-mbeans.xml

If the file is not located in the classpath, enter the full (or relative) path to the file in addition to the file name. The system property also supports the use of a URL when specifying the location of an MBean configuration override file.

3.1.6 Restricting MBeans to the Local MBean Server

By default, custom MBeans that are registered with Coherence are visible by any cluster member that enables JMX management. To restrict the MBean from being visible to remote cluster members, set the <local-only> element to true. This registers the MBean only to the local MBean server. For example:

<mbeans>
   <mbean id="100">
      <mbean-class>com.MyMBean</mbean-class>
      <mbean-name>type=application</mbean-name>
      <local-only>true</local-only>
      <enabled>true</enabled>
   </mbean>
</mbeans>

3.2 Registering Custom MBeans Programmatically

The com.tangosol.net.management.Registry interface is used to register custom MBeans programmatically. The following example registers a standard MBean to Coherence using the register method. See Oracle Coherence Java API Reference for complete details of the Registry interface.

Registry    registry = CacheFactory.ensureCluster().getManagement();
Custom      bean     = new Custom();
String      sName    = registry.ensureGlobalName("type=Custom");

registry.register(sName, bean);

Using Static MBean Names

The example uses the ensureGlobalName method when adding a custom MBean to Coherence. The method is used to add the nodeId=... portion to the end of the MBean's ObjectName. The node ID is required to have unique names on the centralized MBean server. If an application requires static MBean names, use a MBean query to add MBeans from a local MBean server to the Coherence management system. The MBeans are created on the managed member with the static name and then the ,nodeId=... portion is added to the name of the MBean when aggregating on the managing member.

To use static MBean names:

  1. Register the MBeans on the local MBean server of the managed member using the registerMBean or createMBean methods before joining the cluster. See the MBeanServer interface JavaDocs for information on using these methods:

    http://java.sun.com/j2se/6/docs/api/javax/management/MBeanServer.html

  2. Use the MBeanHelper.findMBeanServer() method to obtain the same MBean server that Coherence is using.

  3. Configure the custom-mbeans.xml file to query the newly registered MBeans. See "Registering MBeans Using a Query".

Note:

Refer to the Sun documentation to ensure an environment is set up properly to access the local MBean server.

http://download.oracle.com/javase/6/docs/technotes/guides/management/agent.html