3 Registering Custom MBeans

The Oracle Coherence management framework can manage custom MBeans together with Coherence MBeans. Custom MBeans must be registered with the Coherence MBean servers.

This chapter includes the following sections:

Overview of Registering Custom MBeans
Coherence supports managing and monitoring custom MBeans within the Coherence management framework. Custom MBeans are MBeans that are specific to an application (including MBeans for the Java platform).
Registering Custom MBeans Declaratively
Custom MBeans can be registered with the Coherence management framework using the custom-mbeans.xml MBean configuration override file.
Registering Custom MBeans Programmatically
Custom MBeans can be registered with the Coherence management framework using the com.tangosol.net.management.Registry interface from you application.
Registering Custom MBeans in Managed Coherence Servers
You can use XML to register custom MBeans when using managed Coherence servers.

3.1 Overview of Registering Custom MBeans

Coherence supports managing and monitoring custom MBeans within the Coherence management framework. Custom MBeans are MBeans that are specific to an application (including MBeans for the Java platform). Integrating custom MBeans together with Oracle Coherence MBeans allows you to update and view system and application information for all members in a cluster from a single location.

Custom MBeans are registered to an Oracle Coherence MBean server either declaratively in an XML file or programmatically.

Note:

A dead lock might occur when constructors of global custom MBeans access Coherence distributed services. Constructors of global custom mbeans are not allowed to access Coherence Distributed services.

3.2 Registering Custom MBeans Declaratively

Custom MBeans can be registered with the Coherence management framework using the custom-mbeans.xml MBean configuration override file.

At run time, the first custom-mbeans.xml file that is found in the classpath is used. MBeans are declared in the configuration file using a class name, class factory name, or a query string that is executed against an MBean server.

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 cluster member, including the JMX management-enabled member.

This section includes the following topics:

3.2.1 Creating an MBean Configuration File

The custom-mbeans.xml file overrides the <mbeans> element of the operational deployment descriptor. Therefore, the root element must be the <mbeans> element. See mbeans in Developing Applications with Oracle Coherence.

To create the MBean configuration override file:

Create a text file and save it as custom-mbeans.xml.
Edit the file and create an empty <mbeans> node as follows:
```
<mbeans>
</mbeans>
```
Save and close the file.
Ensure that the location of the custom MBean configuration override file is 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.2.2 Registering MBeans Using a Class Name

The <mbean-class> element registers and instantiates 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>

The preceding configuration registers the MBean and allows remote management. Therefore, the MBean's name automatically includes the cluster member's node ID and domain namespace as part of the object name. For example:

Coherence:type=application,nodeId=<nodeId>

See Registering Custom MBeans Programmatically for changing the default registration behavior.

3.2.3 Registering MBeans from an MBean Factory

The <mbean-factory> and <mbean-accessor> elements 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>

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

See Registering Custom MBeans Programmatically for changing the default registration behavior.

3.2.4 Registering MBeans Using a Query

The <mbean-query> element queries 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 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.2.5 Specifying a Different MBean Configuration Override File

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

-Dcoherence.mbeans=my-mbeans.xml

Ensure that the classpath includes the location of the file, or 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 you specify the location of an MBean configuration override file.

3.2.6 Restricting MBeans to the Local MBean Server

Custom MBeans are visible to any cluster member that enables JMX management. To register MBeans to only the local MBean server and restrict the MBeans from being visible to remote cluster members, set the <local-only> element to true. 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.3 Registering Custom MBeans Programmatically

Custom MBeans can be registered with the Coherence management framework using the com.tangosol.net.management.Registry interface from you application.

The following example registers a standard MBean using the register method.

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

registry.register(sName, bean);

Coherence:type=custom,nodeId=<nodeId>

Using a Custom Domain Namespace

The default namespace behavior ensures unique object names on the centralized MBean server when multiple clusters run within the same JVM. That is, a different domain namespace is automatically assigned (Coherence@1:, and so on) to ensure that MBeans across clusters do not use the same object name. When using a custom domain namespace, applications must ensure unique object names.

To use a custom domain namespace, explicitly add the namespace to the definition. For example:

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

registry.register(sName, bean);

To perform JMX operations on the custom MBeans, use the object name as returned by Registry.ensureGlobalName() API.

Using Static MBean Names

The ensureGlobalName method adds the ,nodeId=... portion to the end of the MBean's ObjectName to ensure unique names on the centralized MBean server. If an application requires static MBean names, use an MBean query to add MBeans from a local MBean server to the management framework. For example, create MBeans on the managed member with static names and then the ,nodeId=... portion is added to the name of the MBean during MBean aggregation on the managing member.

To use static MBean names:

Register the MBeans on the local MBean server of the managed member using the registerMBean or createMBean method before joining the cluster. See Interface MBeanServer in Java™ Platform, Standard Edition API Specification.
Use the MBeanHelper.findMBeanServer() method to obtain the same MBean server that Oracle Coherence is using.
Configure the custom-mbeans.xml file to query the MBean server for the MBeans. See Registering MBeans Using a Query.

Note:

Ensure that an environment is set up properly to access the local MBean server. See Monitoring and Management Using JMX Technology in Java SE Monitoring and Management Guide.

3.4 Registering Custom MBeans in Managed Coherence Servers

You can use XML to register custom MBeans when using managed Coherence servers. Managed Coherence servers, like standalone Coherence, can use a custom-mbeans.xml file to register custom MBeans. See Registering Custom MBeans Declaratively.

There are three ways to specify an MBean configuration file when using managed Coherence server:

Add the custom-mbeans.xml file to the server classpath: When Coherence starts, it looks for the custom-mbeans.xml file in the server classpath and uses this as a MBean configuration file. This file and any associated classes can be added to the classpath by putting them in a JAR file that is located in the domain directory within the /lib subdirectory.
Specify a different MBean configuration file: Use the tangosol.coherence.mbeans system property when starting a managed Coherence server to specify an MBean configuration file other than the default custom-mbeans.xml file.
```
-Dtangosol.coherence.mbeans=my-mbeans.xml
```
Classes that are associated with custom MBeans must be added to the classpath.
Use the CoherenceClusterSystemResources MBean: Users can define custom MBeans in an operational override file and specify that file in the CustomClusterConfigurationFileName attribute of the CoherenceClusterSystemResources MBean. The specified configuration file is loaded on startup. See Registering Custom MBeans Declaratively.