This chapter provides instructions for registering custom MBeans to the Oracle Coherence management framework to integrate management of both custom MBeans and Oracle Coherence MBeans.
This chapter includes the following sections:
Oracle 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 an Oracle Coherence MBean server either declaratively in an XML file or programmatically.
The ability to integrate custom MBeans with Oracle Coherence MBeans allows administrators to update and view system and application information for all members in a cluster from a single location.
Custom MBeans are declaratively registered within an MBean configuration override file named custom-mbeans.xml. At run time, the first instance of custom-mbeans.xml that is found in the classpath is used. See Developing Applications with Oracle Coherence for detailed information about MBean configuration. To register MBeans, use either an MBean's class name, an MBean factory, or run 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 cluster member, including the JMX management-enabled member.
This section includes the following topics:
The custom-mbeans.xml file overrides the <mbeans> element of the operational deployment descriptor. Therefore, the root element must be the <mbeans> element. See the Developing Applications with Oracle Coherence for a complete reference of the <mbeans> element.
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
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.
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>
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=java,SubSystem=Memory,nodeId=<nodeId>
See "Registering Custom MBeans Programmatically" for changing the default registration behavior.
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>
The tangosol.coherence.mbeans system property specifies an MBean configuration override file instead of the default custom-mbeans.xml override file. For example:
-Dtangosol.coherence.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.
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>
The com.tangosol.net.management.Registry interface registers custom MBeans programmatically. The following example registers a standard MBean using the register method. See Java API Reference for Oracle Coherence 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);
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=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.
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 the MBeanServer interface reference for information about using these methods:
http://docs.oracle.com/javase/7/docs/api/javax/management/MBeanServer.html
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:
Refer to the Oracle documentation to ensure that an environment is set up properly to access the local MBean server.
http://download.oracle.com/javase/7/docs/technotes/guides/management/agent.html