2218 lines
105 KiB
HTML
2218 lines
105 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<!--
|
||
|
|
Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
|
||
|
|
|
||
|
|
Redistribution and use in source and binary forms, with or without
|
||
|
|
modification, are permitted provided that the following conditions
|
||
|
|
are met:
|
||
|
|
|
||
|
|
- Redistributions of source code must retain the above copyright
|
||
|
|
notice, this list of conditions and the following disclaimer.
|
||
|
|
|
||
|
|
- Redistributions in binary form must reproduce the above copyright
|
||
|
|
notice, this list of conditions and the following disclaimer in the
|
||
|
|
documentation and/or other materials provided with the distribution.
|
||
|
|
|
||
|
|
- Neither the name of Oracle nor the names of its
|
||
|
|
contributors may be used to endorse or promote products derived
|
||
|
|
from this software without specific prior written permission.
|
||
|
|
|
||
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
||
|
|
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
|
||
|
|
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||
|
|
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
|
||
|
|
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
||
|
|
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
||
|
|
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
||
|
|
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
||
|
|
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
||
|
|
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
-->
|
||
|
|
|
||
|
|
<title>JMX(TM) "scandir" Example</title>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<h1><center>Java<font size="-1"><sup>TM</sup></font> Management Extensions (JMX<font size="-1"><sup>TM</sup></font>) <i>scandir</i> Example</center></h1>
|
||
|
|
|
||
|
|
<h2><a name="h2-Introduction">Introduction</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>The JMX <i>scandir</i> example is an application that
|
||
|
|
scans parts of a filesystem - e.g. a set of directories
|
||
|
|
used by a number of lab machines when running tests - in
|
||
|
|
order to clean up and optimize disk space by removing
|
||
|
|
obsolete files - e.g. files that are leaked by the test
|
||
|
|
suites running on those machines, like coredump files, or
|
||
|
|
temporary files that might remain after a test crash.
|
||
|
|
It could also serve as a basis for an application that
|
||
|
|
would monitor disk usage and suggest removal of old big
|
||
|
|
long-unaccessed files.
|
||
|
|
</p>
|
||
|
|
<p>The JMX <i>scandir</i> example does not however implement
|
||
|
|
the full fledged logic that such an application might
|
||
|
|
have. It implements a subset of this logic which is
|
||
|
|
sufficient to demonstrate common patterns and
|
||
|
|
solutions used when implementing a monitoring and
|
||
|
|
management interface for an application with JMX
|
||
|
|
Technology.</p>
|
||
|
|
<p>This example is an advanced JMX example, which presents
|
||
|
|
advanced JMX concepts. It is assumed that the reader is already
|
||
|
|
familiar with the JMX API. Newcomers to JMX Technology are
|
||
|
|
invited to have a look at the <a
|
||
|
|
href="http://java.sun.com/javase/6/docs/technotes/guides/jmx/"
|
||
|
|
>JMX API Overview, Tutorial and Examples</a> before going any further.
|
||
|
|
</p>
|
||
|
|
<p></p>
|
||
|
|
<hr>
|
||
|
|
<blockquote>
|
||
|
|
<u>Note:</u> This example was developed using <a
|
||
|
|
href="http://www.netbeans.org">NetBeans 5.0 IDE</a>. The instructions
|
||
|
|
given in this document to build, run, and test the example assume that
|
||
|
|
you have at your disposal:
|
||
|
|
<ul><li>either <a href="http://www.netbeans.org">NetBeans 5.0 IDE</a>,</li>
|
||
|
|
<li>or <a href="http://ant.apache.org/">Apache Ant 1.6.5</a> and
|
||
|
|
<a href="http://sourceforge.net/projects/junit/">JUnit 3.8.1 or
|
||
|
|
3.8.2</a><br>
|
||
|
|
(JUnit is only needed to run the example's unit tests).
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p><a name="setup">In order to build the example</a>,
|
||
|
|
<u>you may need to copy the jmx-scandir</u>
|
||
|
|
directory to somewhere where you have write permissions.
|
||
|
|
<br>In that case, you will need to update the <i>nbjdk.home</i> variable
|
||
|
|
in the copied <i><a href="build.properties">build.properties</a></i>
|
||
|
|
file located at the root of the copied project directory.
|
||
|
|
Please make sure that this variable points to the JDK 6 home directory.
|
||
|
|
</p>
|
||
|
|
<p>If you wish to run the testsuite from within the <a
|
||
|
|
href="http://www.netbeans.org">NetBeans IDE</a> you will also have
|
||
|
|
to set the <i>libs.junit.classpath</i> variable in
|
||
|
|
<a href="build.properties">build.properties</a>.
|
||
|
|
The <i>libs.junit.classpath</i> variable should point to your
|
||
|
|
<a href="http://sourceforge.net/projects/junit/">junit.jar</a>,
|
||
|
|
version 3.8.1 or 3.8.2.
|
||
|
|
</p>
|
||
|
|
</blockquote>
|
||
|
|
<hr>
|
||
|
|
<p></p>
|
||
|
|
<p><u>Table Of Contents:</u></p>
|
||
|
|
<p><center>[<a href="#h2-Generating">Generating the Java Documentation</a>]
|
||
|
|
[<a href="#h2-Overview">Overview of the <i>scandir</i> Example</a>]
|
||
|
|
[<a href="#h2-API-Doc">API Documentation and Sources</a>]
|
||
|
|
[<a href="#h2-Patterns">Patterns, Best Practices, and Common Pitfalls</a>]
|
||
|
|
[<a href="#h2-Testing">Testing the <i>scandir</i> Example</a>]
|
||
|
|
[<a href="#h2-Running">Running the <i>scandir</i> Example</a>]
|
||
|
|
[<a href="#h2-Playing">Playing with JConsole</a>]
|
||
|
|
[<a href="#h2-Turning">Turning the example into a Secure JMX Application</a>]
|
||
|
|
[<a href="#h2-Connecting">Connecting to the Secure JMX Application</a>]
|
||
|
|
[<a href="#h2-Conclusion">Conclusion</a>]
|
||
|
|
[<a href="#h2-References">References</a>]</center></p>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
<h2><a name="h2-Generating">Generating the Java Documentation</a></h2>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<p>Before reading further, you will need to generate the
|
||
|
|
Java Documentation for the example's sources.</p>
|
||
|
|
<p>In the example root directory (where the <code>build.xml</code>
|
||
|
|
file is located) run the following command:
|
||
|
|
<pre>ant javadoc</pre>
|
||
|
|
</p>
|
||
|
|
<p>Alternatively you can open the jmx-scandir project with the
|
||
|
|
NetBeans IDE and generate the Javadoc from its <code>Build</code>
|
||
|
|
menu.
|
||
|
|
</p>
|
||
|
|
<p>If building the documentation fails, please make sure to read the
|
||
|
|
<a href="#setup">note</a> at the beginning of this document.</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2><a name="h2-Overview">Overview of the <i>scandir</i> Example</a></h2>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<p>The JMX <i>scandir</i> example is built around the
|
||
|
|
following MBeans:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The first MBean we will present here is the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBean</a>. <br>A
|
||
|
|
<code>DirectoryScannerMXBean</code> is an MBean that scans a
|
||
|
|
file system starting at a given root directory, and then looks
|
||
|
|
for files that match the given criteria. When such a file is
|
||
|
|
found, the <code>DirectoryScannerMXBean</code> takes the
|
||
|
|
action for which it was configured: emit a notification,
|
||
|
|
<i>and/or</i> log a <code>record</code> for this file,
|
||
|
|
<i>and/or</i> delete that file. The code that would actually
|
||
|
|
delete the file is commented out - so that nothing valuable is
|
||
|
|
lost if the example is run by mistake on the wrong set of
|
||
|
|
directories.<br> <code>DirectoryScannerMXBeans</code> are
|
||
|
|
created by the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> - see next item on the list, from its
|
||
|
|
configuration.
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> is the actual entry point of the
|
||
|
|
application. It reads the application's
|
||
|
|
configuration, and from that configuration,
|
||
|
|
will create a <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManager.html"
|
||
|
|
title="The ResultLogManager is in charge of managing result logs"
|
||
|
|
>ResultLogManager</a> and some <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBeans</a>.
|
||
|
|
<br>The <code>ScanManagerMXBean</code> lets you start, stop, and
|
||
|
|
schedule directory scans. The
|
||
|
|
<code>ScanManagerMXBean</code> is a singleton
|
||
|
|
MBean: there can be at most one instance of such
|
||
|
|
an MBean registered in a given MBeanServer.
|
||
|
|
</li>
|
||
|
|
<li>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> is an MBean which is able to
|
||
|
|
load/save the configuration to/from an XML file. It
|
||
|
|
will also let you modify that configuration - by e.g.
|
||
|
|
creating new directory scanners in there.
|
||
|
|
The corresponding MBeans will be created later, only
|
||
|
|
when you later
|
||
|
|
ask the <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> </code> to apply the
|
||
|
|
configuration again.<br>
|
||
|
|
The <code>ScanDirConfigMXBean</code> is created by the
|
||
|
|
<code>ScanManagerMXBean</code>, when the
|
||
|
|
<code>ScanManagerMXBean</code> is registered.
|
||
|
|
It is also possible to create an alternate
|
||
|
|
<code>ScanDirConfigMXBean</code>, and to switch the
|
||
|
|
<code>ScanDirConfigMXBean</code> to use one or the other
|
||
|
|
configuration.
|
||
|
|
<br>An example of XML configuration file is given
|
||
|
|
<a href="src/etc/testconfig.xml"
|
||
|
|
title="An Example Of Configuration"
|
||
|
|
>here</a>. Although you could edit such a file by
|
||
|
|
hand, it is easier to do it programmatically (or
|
||
|
|
with <a href="#JConsole">JConsole</a>) through
|
||
|
|
the <code>ScanDirConfigMXBean</code> interface.
|
||
|
|
</li>
|
||
|
|
<li>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a> is in charge of managing result logs.
|
||
|
|
<br>Directory Scanners can be configured to log a
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/config/ResultRecord.html"
|
||
|
|
title="A ResultRecord contains information about a file matching the criteria of a Directory Scanner"
|
||
|
|
>ResultRecord</a> whenever they take action upon a file that
|
||
|
|
matches their criteria. The <code>ResultLogManagerMXBean</code> is
|
||
|
|
responsible for logging these result records.
|
||
|
|
The <code>ResultLogManagerMXBean</code> can be configured to log
|
||
|
|
such records to a flat file, or into a log held in memory, or
|
||
|
|
both. Both logs (file and memory) can be configured with a
|
||
|
|
maximum capacity.
|
||
|
|
<br>When the maximum capacity of the memory
|
||
|
|
log is reached, its first entry (i.e. its oldest entry) is
|
||
|
|
removed to make place for the latest one.
|
||
|
|
<br>When the maximum
|
||
|
|
capacity of the file log is reached, the file is
|
||
|
|
renamed by appending a tilde '~' to its name and a
|
||
|
|
new result log is created.
|
||
|
|
<br>The <code>ResultLogManagerMXBean</code>
|
||
|
|
will let you interactively clear these result logs, change their
|
||
|
|
capacity, and decide where (memory or file) to log.
|
||
|
|
The memory log is useful in that its content can be interactively
|
||
|
|
returned by the <code>ResultLogManagerMXBean</code>, while
|
||
|
|
the file log doesn't have this facility.<br>
|
||
|
|
The result logs are intended to be used by e.g. an offline
|
||
|
|
program that would take some actions on the files that
|
||
|
|
matched the scan criteria:
|
||
|
|
<br>The <i>scandir</i> application
|
||
|
|
could be configured to only produce logs (i.e. takes no
|
||
|
|
action but logging the matching files), and the real
|
||
|
|
action could be performed by another program or module (e.g. mail the result log to the engineer who
|
||
|
|
maintains the lab, or parse that log and delete all the
|
||
|
|
files listed there, or parse the log and prepare and send
|
||
|
|
a single mail to each owner of matching files, containing
|
||
|
|
the list of files they should consider deleting).<br>
|
||
|
|
The <code>ResultLogManagerMXBean</code> is a singleton
|
||
|
|
MBean created by the <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> </code>
|
||
|
|
which reads and writes its configuration from the
|
||
|
|
<code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a></code>.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>An application <code>main()</code> method is
|
||
|
|
provided in the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirAgent.html"
|
||
|
|
>ScanDirAgent</a> class. The <code>main()</code> simply registers
|
||
|
|
a <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> </code> in the platform MBeanServer, and
|
||
|
|
then waits for someone to call <code>close()</code> on the
|
||
|
|
<code>ScanManagerMXBean</code>.
|
||
|
|
</p>
|
||
|
|
<p>When the <code>ScanManagerMXBean</code> is registered, it
|
||
|
|
will create a default <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a></code> bound
|
||
|
|
to a default XML config file.
|
||
|
|
</p>
|
||
|
|
<p>The application's default XML config file is determined as
|
||
|
|
follows:
|
||
|
|
<ol>
|
||
|
|
<li>If the property <code>scandir.config.file</code> is
|
||
|
|
defined, the default application file will be the
|
||
|
|
file pointed to by this property. If that file
|
||
|
|
doesn't exist, it will be created when
|
||
|
|
<code>ScanDirConfigMXBean.save()</code> is
|
||
|
|
invoked.
|
||
|
|
</li>
|
||
|
|
<li>Otherwise the application config file is
|
||
|
|
assumed to be a file called <code>jmx-scandir.xml</code>,
|
||
|
|
located in the user's directory (as defined by
|
||
|
|
the System property <code>user.home</code>).
|
||
|
|
If that file doesn't exists, it will be created when
|
||
|
|
<code>ScanDirConfigMXBean.save()</code> is
|
||
|
|
invoked.
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
<p>It is worth noting that this project is defined to
|
||
|
|
run with the following properties:
|
||
|
|
<pre>-Djava.util.logging.config.file=logging.properties</pre>
|
||
|
|
<pre>-Dscandir.config.file=src/etc/testconfig.xml</pre>
|
||
|
|
With <code>ScanDirAgent</code> defined as the project's
|
||
|
|
main class. Hence when you invoke from the NetBeans IDE
|
||
|
|
<i>Run Project</i> on the <i>jmx-scandir</i> project,
|
||
|
|
or <i>Run file</i> on the <code>ScanDirAgent</code>, the
|
||
|
|
application starts with the test configuration provided in
|
||
|
|
<a href="src/etc/testconfig.xml"
|
||
|
|
title="An Example Of Configuration"
|
||
|
|
>src/etc/testconfig.xml</a>
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h2><a name="h2-API-Doc">API Documentation and Sources</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>Once generated, the Javadoc of example classes can
|
||
|
|
be found starting from <a href="dist/javadoc/index.html"
|
||
|
|
title="The API Documentation"
|
||
|
|
><code>dist/javadoc/index.html</code></a>.</p>
|
||
|
|
<p>You can view the sources in the <a
|
||
|
|
href="src"
|
||
|
|
title="The Example Source Tree"
|
||
|
|
><code>src</code></a> subdirectory.</p>
|
||
|
|
</ul>
|
||
|
|
<h2><a name="h2-Patterns">Patterns, Best Practices, and Common Pitfalls</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>This section discusses some common patterns and
|
||
|
|
design choices that this example demonstrates, and some pitfalls that
|
||
|
|
it avoids.
|
||
|
|
</ul>
|
||
|
|
<h3>MBeans or MXBeans?</h3>
|
||
|
|
<ul>
|
||
|
|
<p>What is an MXBean? MXBeans made their appearance in
|
||
|
|
J2SE 5.0 (Tiger), with the Management and Monitoring
|
||
|
|
API of the JVM. However, Java SE 6 is the first
|
||
|
|
Java SE release that contains a standard framework which
|
||
|
|
makes it possible to create and register your own MXBeans.
|
||
|
|
</p>
|
||
|
|
<p>MXBeans are a special kind of MBean, which once registered
|
||
|
|
in the MBeanServer, get automatically transformed into
|
||
|
|
OpenMBeans. From a developer point of view, nothing changes:
|
||
|
|
A Wombat MBean can become an MXBean simply by renaming
|
||
|
|
its <code>WombatMBean</code> interface into <code>WombatMXBean</code>.</p>
|
||
|
|
<p>Using MXBeans rather than plain Standard MBean brings its
|
||
|
|
own advantages:</p>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
Generic tools, like JConsole, will be able to
|
||
|
|
display and interact with your MXBeans nicely, even
|
||
|
|
if your MXBean interfaces reference custom types
|
||
|
|
- e.g. custom Java enums. This is because all the types
|
||
|
|
exposed by your MXBeans are converted to Open Types.
|
||
|
|
Just look at the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> with JConsole and you will
|
||
|
|
understand the benefits.
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
When writing a programmatic client, you can obtain
|
||
|
|
a proxy that implements the original MXBean interface,
|
||
|
|
and forget about the Open Type conversion.
|
||
|
|
The JUnit unit tests that come with this example
|
||
|
|
use this feature very widely. Have a look at them.
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
The MXBean framework also lets you nicely navigate
|
||
|
|
from one MXBean to another: your MXBeans can
|
||
|
|
have attributes and parameters which are proxies
|
||
|
|
to other MXBeans! We demonstrate this in the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> which exposes a list
|
||
|
|
of <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBean</a></code> and points
|
||
|
|
towards a <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a></code>.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>In short, MXBeans are so much easier to use that
|
||
|
|
this example doesn't even have a single regular
|
||
|
|
Standard MBean.
|
||
|
|
</p>
|
||
|
|
<p>See also <a
|
||
|
|
href="http://weblogs.java.net/blog/emcmanus/archive/2006/02/what_is_an_mxbe.html"
|
||
|
|
title="What is an MXBean?"
|
||
|
|
>What is an MXBean?</a>
|
||
|
|
and <a
|
||
|
|
href="http://weblogs.java.net/blog/emcmanus/archive/2006/06/intermxbean_ref.html"
|
||
|
|
title="Inter-MXBean references"
|
||
|
|
>Inter-MXBean References</a>.
|
||
|
|
</p>
|
||
|
|
<blockquote><u>Hint:</u> In order to simplify the task of coding a
|
||
|
|
JMX programmatic client, we recommend that getters, setters, and
|
||
|
|
operations defined in MBean and MXBean interfaces throw
|
||
|
|
<code>IOException</code>. Proxy objects will then be able
|
||
|
|
to rethrow directly any <code>IOException</code> received from
|
||
|
|
their underlying MBean Server connection, without wrapping
|
||
|
|
them into <code>UndeclaredThrowableExceptions</code>.<br>
|
||
|
|
Since the life cycle of the proxy object is not directly tied to
|
||
|
|
the life cycle of the MBean it proxies, you may also want to
|
||
|
|
have all methods in the MBean or MXBean interface throw
|
||
|
|
<code>InstanceNotFoundException</code> or more generally
|
||
|
|
<code>JMException</code>.
|
||
|
|
</blockquote>
|
||
|
|
</ul>
|
||
|
|
<h3>MBean Names - aka ObjectNames</h3>
|
||
|
|
<ul>
|
||
|
|
<p>As you must know if you've been studying JMX, MBeans are
|
||
|
|
named objects. The names of MBeans are represented by
|
||
|
|
instances of <code>ObjectName</code>. An ObjectName is
|
||
|
|
composed of a <i>domain</i>, followed by a colon ':',
|
||
|
|
followed by a comma-separated list of <i>key=value</i>
|
||
|
|
pairs.<br>
|
||
|
|
The ordering of the <i>key=value</i> pairs is not
|
||
|
|
important, but <code>ObjectNames</code> are case sensitive
|
||
|
|
(both keys and values are case sensitive) and <b>white space
|
||
|
|
is not ignored</b>.<br>
|
||
|
|
A common pitfall for JMX beginners is to inadvertently
|
||
|
|
insert white space after commas into an ObjectName,
|
||
|
|
and expect that two ObjectNames which differ only by such white
|
||
|
|
space will be considered identical. This is not the
|
||
|
|
case.<br>
|
||
|
|
As an example, the ObjectName '<b><code>D:k1=v1, k2=v2, k3=v3</code></b>' has
|
||
|
|
three keys, which are '<b><code>k1</code></b>', '<b><code> k2</code></b>',
|
||
|
|
and '<b><code> k3</code></b>': beware
|
||
|
|
of the space in the name of the second and third
|
||
|
|
keys!<br>
|
||
|
|
It is therefore a different ObjectName from
|
||
|
|
'<b><code>D:k1=v1,k2=v2,k3=v3</code></b>' (the keys are now
|
||
|
|
'<b><code>k1</code></b>', '<b><code>k2</code></b>', and
|
||
|
|
'<b><code>k3</code></b>'), but the same ObjectName as
|
||
|
|
'<b><code>D: k2=v2, k3=v3,k1=v1</code></b>', and yet different
|
||
|
|
from '<b><code>D:k2=v2, k3=v3, k1=v1</code></b>'!
|
||
|
|
<p>In this example, we are following the rules
|
||
|
|
for ObjectName suggested in the <a
|
||
|
|
href="http://java.sun.com/products/JavaManagement/best-practices.html"
|
||
|
|
>JMX Best Practices</a>:</p>
|
||
|
|
<ul>
|
||
|
|
<li>ObjectNames should be <a
|
||
|
|
href="http://java.sun.com/products/JavaManagement/best-practices.html#mozTocId654884"
|
||
|
|
>predictable</a>
|
||
|
|
</li>
|
||
|
|
<li>The domain part of our ObjectNames starts with a Java
|
||
|
|
package name
|
||
|
|
</li>
|
||
|
|
<li>Our ObjectNames contain a <code>type=</code>
|
||
|
|
key property. This property is different for every
|
||
|
|
object type in our domain.
|
||
|
|
</li>
|
||
|
|
<li>For every ObjectName with a given type, we have the same set of key
|
||
|
|
properties with the same syntax and semantics for their values - in
|
||
|
|
fact we only use an additional <code>name=</code> key.
|
||
|
|
</li>
|
||
|
|
<li>When there can only be one instance of a given type
|
||
|
|
there aren't any other key properties than <code>type=</code>.
|
||
|
|
The ObjectNames of the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> and <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a>, which are both singleton MBeans, are
|
||
|
|
composed in this way.
|
||
|
|
</li>
|
||
|
|
<li>When there can be several instances of a given type,
|
||
|
|
we differentiate them by further key properties.
|
||
|
|
To achieve this, we are using the most usual key property
|
||
|
|
in addition to <code>type=</code>: the <code>name=</code> key.
|
||
|
|
In this example, a key property list of the form
|
||
|
|
<code>type=X,name=Y</code> is always enough to uniquely name
|
||
|
|
an MBean. Tools like jconsole are usually aware
|
||
|
|
of the semantics of the <code>type=</code> key and
|
||
|
|
<code>name=</code> key, and are therefore able to
|
||
|
|
display this form of name in a way that
|
||
|
|
is easier to read than other name forms.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>The rules listed above are implemented by a couple
|
||
|
|
of static helper functions in the <a
|
||
|
|
href="src/com/sun/jmx/examples/scandir/ScanManager.java"
|
||
|
|
title="ScanManager.java"
|
||
|
|
>ScanManager</a> class. See the code of the
|
||
|
|
<b><code>makeSingletonName</code></b> and
|
||
|
|
<b><code>makeMBeanName</code></b> methods.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>Inter MBean Navigation</h3>
|
||
|
|
<ul>
|
||
|
|
<p>One of the most common problems that needs to be solved
|
||
|
|
when designing a management interface with JMX is to
|
||
|
|
choose a representation for inter-MBean relationships.<br>
|
||
|
|
Prior to Java 6, there were basically three possible
|
||
|
|
choices:</p>
|
||
|
|
<ul>
|
||
|
|
<li><b>Make the relation appear in the ObjectName</b>.
|
||
|
|
For instance, if MBean B was contained in
|
||
|
|
MBean A, you could choose to name MBean B so
|
||
|
|
that its parent relationship with MBean A
|
||
|
|
appeared in its name. <br>
|
||
|
|
The obvious limitation of this solution is that
|
||
|
|
it only allows to model one such relation (an
|
||
|
|
MBean has only one name) and the relation must
|
||
|
|
be fixed - it cannot change during the life of
|
||
|
|
the MBean since the name of an MBean cannot
|
||
|
|
change.<br>
|
||
|
|
This scheme is therefore mostly used when
|
||
|
|
the application MBeans are modeling objects
|
||
|
|
which are conceptually contained within
|
||
|
|
each other in a tree-like structure.
|
||
|
|
<br>For instance, most MBean names defined by
|
||
|
|
<a href="http://jcp.org/en/jsr/detail?id=77"
|
||
|
|
>J2EE Management (JSR 77)</a> follow
|
||
|
|
this scheme.
|
||
|
|
</li>
|
||
|
|
<li><b>Design getters and setters (or operations) which
|
||
|
|
return <code>ObjectName</code> or
|
||
|
|
<code>ObjectName[]</code> values</b>. The ObjectNames
|
||
|
|
point to the MBeans which are related to that
|
||
|
|
object. For instance , <a
|
||
|
|
href="http://glassfish.dev.java.net/"
|
||
|
|
title="Open Source Java EE 5 Application Server"
|
||
|
|
>GlassFish</a>
|
||
|
|
defines MBeans which also use this pattern.
|
||
|
|
</li>
|
||
|
|
<li><b>Use the JMX RelationService</b>. The JMX RelationService
|
||
|
|
is quite powerful, but simple relationships often
|
||
|
|
do not justify that overhead.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>In Java 6, these three possibilities still remain, but
|
||
|
|
the new MXBean framework brings up an interesting
|
||
|
|
alternative. Instead of returning an ObjectName or
|
||
|
|
an ObjectName array, <b>an MXBean can return a proxy</b>
|
||
|
|
to its related MXBeans. This is how we have chosen to
|
||
|
|
implement our inter MBean relationships in this
|
||
|
|
example:
|
||
|
|
<br>For instance the
|
||
|
|
<code>ScanManagerMXBean</code>/<code>DirectoryScannerMXBean</code>
|
||
|
|
relationship and the
|
||
|
|
<code>ScanManagerMXBean</code>/<code>ScanDirConfigMXBean</code>
|
||
|
|
relationships are implemented in this way.
|
||
|
|
<p>
|
||
|
|
The additional benefit, as compared to returning ObjectNames or
|
||
|
|
using the RelationService is that interface type of the MBeans
|
||
|
|
which are pointed to by the relationship becomes directly
|
||
|
|
apparent. The method:
|
||
|
|
<pre>
|
||
|
|
public Map<String,DirectoryScannerMXBean> getDirectoryScanners();
|
||
|
|
</pre>
|
||
|
|
makes it immediately obvious that the MBeans to which we point are
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBeans</a>. It would have been much less obvious in prior
|
||
|
|
versions of Java SE, were the returned type would have had to be
|
||
|
|
<code>Map<String,ObjectName></code>, or
|
||
|
|
even worse just <code>Map</code>.
|
||
|
|
</p>
|
||
|
|
<p>However, it must be clear that the behaviour will be
|
||
|
|
quite different when an MXBean is returned as compared
|
||
|
|
to when a simple bean is returned.
|
||
|
|
</p>
|
||
|
|
<p>When an MXBean is returned, the remote client sees either
|
||
|
|
an ObjectName, if it is a generic client like jconsole, or
|
||
|
|
a proxy to a remote MXBean, if the client is working with the
|
||
|
|
MXBean interface. Invoking an operation on one of the
|
||
|
|
proxy returned by a method such as
|
||
|
|
<code>getDirectoryScanners</code> will cause the
|
||
|
|
MBean to be invoked on the remote server side.
|
||
|
|
</p>
|
||
|
|
<p>If <code>getDirectoryScanners</code> were
|
||
|
|
defined as:
|
||
|
|
<pre>
|
||
|
|
public Map<String,DirectoryScannerConfig> getDirectoryScanners();
|
||
|
|
</pre>
|
||
|
|
then invoking a method on one of the returned objects
|
||
|
|
would have absolutely no effect on the remote
|
||
|
|
server side - because the returned objects in this
|
||
|
|
case would simply be a bunch of serialized data objects.
|
||
|
|
</p>
|
||
|
|
<p>It is worth noting that although an MXBean interface
|
||
|
|
can have getters and operations which return an MXBean
|
||
|
|
interface, a regular standard MBean shouldn't have
|
||
|
|
any getters or methods which return MBean interfaces or
|
||
|
|
MXBean interfaces.
|
||
|
|
</p>
|
||
|
|
<p>For more information see also <a
|
||
|
|
href="http://weblogs.java.net/blog/emcmanus/archive/2006/06/intermxbean_ref.html"
|
||
|
|
title="Inter-MXBean references"
|
||
|
|
>Inter-MXBean References</a>.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>The MBeanRegistration interface, or how an MBean can
|
||
|
|
know or provide its own name</h3>
|
||
|
|
<ul>
|
||
|
|
<p>
|
||
|
|
Sometimes, an MBean needs to have a reference to the
|
||
|
|
MBeanServer in which it is registered, or needs to know
|
||
|
|
with which ObjectName it has been registered.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Sometimes also, an MBean may need to perform some
|
||
|
|
checks before being registered, or will need
|
||
|
|
to carry out some actions right after it has been
|
||
|
|
successfully registered in the MBeanServer.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Sometimes again, an MBean may need to perform some
|
||
|
|
checks, or some cleaning actions, just before, or
|
||
|
|
just after, it is unregistered.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
When an MBean has such needs, the easiest solution
|
||
|
|
for it is to implement the <code>MBeanRegistration</code>
|
||
|
|
interface.
|
||
|
|
</p>
|
||
|
|
<p>The <code>MBeanRegistration</code> interface is a callback
|
||
|
|
interface which defines pre and post registration and
|
||
|
|
unregistration callbacks.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
When an MBean implementing this interface is created
|
||
|
|
(with <code>createMBean</code>) or registered
|
||
|
|
(with <code>registerMBean</code>) in an MBeanServer,
|
||
|
|
the MBeanServer will call the <code>preRegister</code>
|
||
|
|
and <code>postRegister</code> method implemented by
|
||
|
|
the MBean. The <code>preRegister</code> method
|
||
|
|
has an <code>MBeanServer</code> and <code>ObjectName</code>
|
||
|
|
parameter, which are passed by the MBeanServer to the
|
||
|
|
MBean. The MBean can store the reference it is being passed
|
||
|
|
in a private instance variable for later use.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Most of the MXBeans we have defined in this example
|
||
|
|
implement the <code>MBeanRegistration</code> interface. The table
|
||
|
|
below show how our MBeans use this interface to control
|
||
|
|
their own names, make sanity checks, perform
|
||
|
|
initialization steps or cleanup actions.
|
||
|
|
</p>
|
||
|
|
<p><br><center>
|
||
|
|
<table border="1" cellpadding="4" cellspacing="2"
|
||
|
|
bgcolor="#eeeeee" width="95%">
|
||
|
|
<thead>
|
||
|
|
<tr bgcolor="#cecece">
|
||
|
|
<th width="20%">MBean Requirement</th>
|
||
|
|
<th>callback</th>
|
||
|
|
<th>use case example</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">get a reference to the MBeanServer</td>
|
||
|
|
<td><code>preRegister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> needs a reference
|
||
|
|
to the MBeanServer in order to create and
|
||
|
|
register other MBeans, such as the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a>, and the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBeans</a>.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">reject registration if conditions are
|
||
|
|
not met.
|
||
|
|
</td>
|
||
|
|
<td><code>preRegister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> will throw
|
||
|
|
an IllegalArgumentException in <code>preRegister</code>
|
||
|
|
if the ObjectName it is being passed is
|
||
|
|
illegal. Throwing an exception in
|
||
|
|
<code>preRegister</code> makes the registration fail.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">get my client-assigned MBean name</td>
|
||
|
|
<td><code>preRegister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> propagates the
|
||
|
|
value of the <code>name=</code> property of
|
||
|
|
the ObjectName it is given into its
|
||
|
|
ScanManagerConfig bean.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">provide my own default ObjectName if none
|
||
|
|
was given to the MBeanServer
|
||
|
|
</td>
|
||
|
|
<td><code>preRegister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The name that is returned by <code>preRegister</code>
|
||
|
|
is the ObjectName with which the MBean will be
|
||
|
|
eventually registered.
|
||
|
|
The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> is able to suggest
|
||
|
|
a value for its own ObjectName if none was
|
||
|
|
provided. Similarly, the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a>
|
||
|
|
always returns its singleton ObjectName
|
||
|
|
defined by <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html#SCAN_MANAGER_NAME"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean.SCAN_MANAGER_NAME</a>.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">perform initialization steps</td>
|
||
|
|
<td><code>preRegister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> uses <code>preRegister</code>
|
||
|
|
to initialize its internal ScanManagerConfig bean.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">perform initialization steps, once it is
|
||
|
|
known that the registration was successful.
|
||
|
|
</td>
|
||
|
|
<td><code>postRegister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The <code>postRegister</code> method
|
||
|
|
can be used to implement
|
||
|
|
initialization steps that need to be done once it
|
||
|
|
is known that the registration was successful, or to
|
||
|
|
undo any action performed by <code>preRegister</code> once it
|
||
|
|
is known that registration was not successful.
|
||
|
|
The <code>postRegister</code> method has a Boolean parameter
|
||
|
|
which tells the MBean whether it was or wasn't
|
||
|
|
successfully registered in the MBeanServer.
|
||
|
|
The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> uses <code>postRegister</code> to create
|
||
|
|
and register other MBeans, such as the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a> and the default
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a>.
|
||
|
|
Note that <code>postRegister</code> is not expected to throw any
|
||
|
|
exception. If an exception needs to be thrown, it should
|
||
|
|
be thrown in <code>preRegister</code>.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">check whether the MBean can be deregistered</td>
|
||
|
|
<td><code>preDeregister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> uses this method to verify
|
||
|
|
that its state allows it to be deregistered.
|
||
|
|
In particular, it will refuse to be deregistered
|
||
|
|
if it is in the RUNNING or SCHEDULED state.
|
||
|
|
If <code>preDeregister</code> throws an exception, the unregisterMBean
|
||
|
|
call will fail and the MBean will remain registered in
|
||
|
|
the MBeanServer.
|
||
|
|
Take particular care when implementing business logic
|
||
|
|
in this method: if the logic you implement has an
|
||
|
|
unfortunate bug which makes it always throw an
|
||
|
|
exception, you will never be able to unregister
|
||
|
|
that MBean.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">clean up resources, refusing to be deregistered if
|
||
|
|
it fails
|
||
|
|
</td>
|
||
|
|
<td><code>preDeregister</code></td>
|
||
|
|
<td bgcolor="#fafafa">The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> uses this method to unregister
|
||
|
|
all the other MBeans it has created and registered in the
|
||
|
|
MBeanServer. This includes the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a>, the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBeans</a> it has created, and the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBeans</a> it has created when
|
||
|
|
applying its configuration.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#dedede">clean up resources which need to be released in
|
||
|
|
a best-effort way, when it is known that the MBean is no
|
||
|
|
longer registered.
|
||
|
|
</td>
|
||
|
|
<td><code>postDeregister</code></td>
|
||
|
|
<td bgcolor="#fafafa"><code>postDeregister</code> is only called if the MBean was succesfully
|
||
|
|
unregistered.
|
||
|
|
The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> uses this method to cancel
|
||
|
|
its internal java.util.Timer.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</center><br></p>
|
||
|
|
</ul>
|
||
|
|
<h3>The Singleton MBean Pattern</h3>
|
||
|
|
<ul>
|
||
|
|
<p>
|
||
|
|
A singleton MBean is an MBean which can only have one
|
||
|
|
instance registered in a given MBeanServer. <br>
|
||
|
|
A singleton MBean usually has a well-known name,
|
||
|
|
which can be defined as a constant. In that case,
|
||
|
|
clients no longer need to call <code>new ObjectName(...)</code>
|
||
|
|
and catch the declared <code>MalformedObjectNameException</code>.
|
||
|
|
</p>
|
||
|
|
<p>There are already quite a few examples of singleton
|
||
|
|
MBeans in the java.lang.management API. The
|
||
|
|
ThreadingMXBean, ClassLoadingMXBean, RuntimeMXBean, etc.
|
||
|
|
are all singleton MBeans.
|
||
|
|
</p>
|
||
|
|
<p>In this example, we have two singleton MBeans:
|
||
|
|
The <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a></code> and the
|
||
|
|
<code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a></code>. But in fact,
|
||
|
|
the only real singleton MBean is the
|
||
|
|
<code>ScanManagerMXBean</code>. The
|
||
|
|
<code>ResultLogManagerMXBean</code> just happens to
|
||
|
|
be a singleton MBean because it has a 1-1 relationship
|
||
|
|
with the <code>ScanManagerMXBean</code>.
|
||
|
|
</p>
|
||
|
|
<p>The <code>ScanManagerMXBean</code> implements the
|
||
|
|
singleton MBean pattern in this way:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>The <code>ScanManagerMXBean</code> name has a single
|
||
|
|
key property: <code>type=ScanManagerMXBean</code>.</li>
|
||
|
|
<li>Its name is defined by an ObjectName constant called
|
||
|
|
<code>SCAN_MANAGER_NAME</code> in the <code>ScanManager</code> class</li>
|
||
|
|
<li>The <code>ScanManagerMXBean</code> enforces its status of
|
||
|
|
singleton MBean. It will refuse to be registered
|
||
|
|
with a name other than
|
||
|
|
the <code>SCAN_MANAGER_NAME</code>. You can therefore depend on
|
||
|
|
the fact that the <code>ScanManagerMXBean</code> will always
|
||
|
|
be registered with its singleton <code>SCAN_MANAGER_NAME</code>
|
||
|
|
(see <code>preRegister</code>)
|
||
|
|
</li>
|
||
|
|
<li>You are not obliged to provide a name when you
|
||
|
|
register the <code>ScanManagerMXBean</code>: if you pass null,
|
||
|
|
then the <code>ScanManager</code> will be registered with
|
||
|
|
its singleton <code>SCAN_MANAGER_NAME</code>
|
||
|
|
(see <code>preRegister</code>).
|
||
|
|
</li>
|
||
|
|
<li>The <code>ScanManager</code> class has a no-arg static
|
||
|
|
<code>register</code> method that will register
|
||
|
|
the singleton instance in the Platform MBeanServer.
|
||
|
|
This static <code>register</code> method returns
|
||
|
|
a proxy to the registered singleton.
|
||
|
|
</li>
|
||
|
|
<li>The <code>ScanManager</code> class has also a static
|
||
|
|
<code>register</code> method that will create
|
||
|
|
a singleton instance in a (possibly remote)
|
||
|
|
MBeanServerConnection - using
|
||
|
|
<code>createMBean</code>.
|
||
|
|
This static <code>register</code> method
|
||
|
|
also returns a proxy to the registered singleton.
|
||
|
|
</li>
|
||
|
|
<li>Only the MBeanServer has a reference to the
|
||
|
|
singleton instance. The singleton instance is
|
||
|
|
not returned to the caller, and not kept
|
||
|
|
in any other static data structure.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>
|
||
|
|
On the other hand, the <code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a></code>
|
||
|
|
has a much more relaxed implementation of the pattern:
|
||
|
|
<br>It simply provides its own singleton name if it is
|
||
|
|
registered with a null ObjectName, but will not enforce
|
||
|
|
the use of that name.
|
||
|
|
</p>
|
||
|
|
<p>Note that all singleton MBean names in this example
|
||
|
|
are created using the <code>ScanManager.makeSingletonName</code>
|
||
|
|
method, which implements the pattern for ObjectNames suggested
|
||
|
|
in the JMX Best Practices.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>Managing the Life Cycle of dependent MBeans</h3>
|
||
|
|
<ul>
|
||
|
|
<p>A common task that many JMX applications have
|
||
|
|
is to manage the life cycle of MBeans registered
|
||
|
|
in the MBeanServer.</p>
|
||
|
|
<p>In this example, we have decided to follow a simple
|
||
|
|
pattern:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The application is initialized simply
|
||
|
|
by registering the singleton
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> in
|
||
|
|
the MBeanServer.
|
||
|
|
</li>
|
||
|
|
<li>The <code>ScanManagerMXBean</code> will then
|
||
|
|
in turn register any other MBean that the
|
||
|
|
application might need:
|
||
|
|
<ul>
|
||
|
|
<li>It creates and registers the singleton
|
||
|
|
<code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a></code>
|
||
|
|
</li>
|
||
|
|
<li>It creates and registers the default
|
||
|
|
<code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a></code>
|
||
|
|
which loads the initial configuration
|
||
|
|
</li>
|
||
|
|
<li>It creates as many
|
||
|
|
<code><a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBeans</a></code> as
|
||
|
|
needed when the configuration is applied
|
||
|
|
</li>
|
||
|
|
<li>It lets you create alternate
|
||
|
|
<code>ScanDirConfigMXBean</code>, to
|
||
|
|
which you can later switch in order
|
||
|
|
to apply a new alternate configuration.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>When a new configuration is applied (or if the
|
||
|
|
current configuration is reapplied), the
|
||
|
|
<code>ScanManagerMXBean</code> will unregister
|
||
|
|
any <code>DirectoryScannerMXBeans</code> it has
|
||
|
|
previously registered, and will re-create
|
||
|
|
brand new <code>DirectoryScannerMXBeans</code>
|
||
|
|
from the applied configuration.
|
||
|
|
</li>
|
||
|
|
<li>When you unregister the <code>ScanManagerMXBean</code>,
|
||
|
|
it does all the cleanup for you, by unregistering
|
||
|
|
all the MBeans that it has created during the
|
||
|
|
course of the application.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>The <code>ScanManagerMXBean</code> makes use of its
|
||
|
|
<code>MBeanRegistration</code> interface in order
|
||
|
|
to register the other MBeans it needs (see the
|
||
|
|
<code>ScanManager.postRegister</code> method) and to unregister
|
||
|
|
every MBean it has created (see the <code>ScanManager.preDeregister</code>
|
||
|
|
method).
|
||
|
|
</p>
|
||
|
|
<p>You will note that the <code>ScanManagerMXBean</code>
|
||
|
|
will only allow itself to be deregistered if it can be
|
||
|
|
closed - that is if there's no other action in
|
||
|
|
progress.
|
||
|
|
This is to make sure that the deregistration of
|
||
|
|
dependent MBeans will work smoothly.
|
||
|
|
<br>
|
||
|
|
The deregistration of related MBeans will happen
|
||
|
|
in the <code>ScanManager.preDeregister</code>
|
||
|
|
method.
|
||
|
|
<br>
|
||
|
|
If one of these MBeans could not be deregistered,
|
||
|
|
then the <code>ScanManagerMXBean</code> will throw
|
||
|
|
an exception, refusing to be deregistered.
|
||
|
|
<br>This leaves you a chance to try to deregister it
|
||
|
|
again later. Since the <code>ScanManagerMXBean</code>
|
||
|
|
has switched its state to CLOSED before starting
|
||
|
|
to unregister its dependent MBeans, it will refuse
|
||
|
|
any further actions, ensuring that e.g. nobody
|
||
|
|
can try to start it or schedule it while it
|
||
|
|
is in that partially-deregistered state.
|
||
|
|
</p>
|
||
|
|
<p>Handling the LifeCycle of all the application's
|
||
|
|
MBeans in a single MBean is usually a good design
|
||
|
|
pattern, especially if the application is a
|
||
|
|
module which is intended to share a JVM - or
|
||
|
|
an MBeanServer - with other modules.
|
||
|
|
</p>
|
||
|
|
<p>This is specially useful if the application needs to
|
||
|
|
be loaded and unloaded on demand: in that
|
||
|
|
case, simply registering or unregistering the top level
|
||
|
|
MBean (in our example the <code>ScanManagerMXBean</code>) does
|
||
|
|
the trick.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>Emitting Notifications</h3>
|
||
|
|
<ul>
|
||
|
|
<p>In order to emit notifications, an MBean must be
|
||
|
|
an instance of <code>NotificationEmitter</code>.
|
||
|
|
The <code>NotificationEmitter</code> interface defines methods
|
||
|
|
that the MBeanServer will call on the MBean in order
|
||
|
|
to register <code>NotificationListeners</code> with the MBean.
|
||
|
|
</p>
|
||
|
|
<p>It is worth noting that the MBean may not be
|
||
|
|
invoked each time a JMX client wants to register
|
||
|
|
a listener. For instance, the RMIConnectorServer
|
||
|
|
registers <i>only once</i> a single listener with each MBean
|
||
|
|
which is a <code>NotificationEmitter</code>.
|
||
|
|
In that specific case, the listener may even be registered
|
||
|
|
with the MBean before any client has actually subscribed
|
||
|
|
for notifications from that particular MBean.
|
||
|
|
</p>
|
||
|
|
<p>An MBean can therefore make no assumption about
|
||
|
|
which client or how many clients have registered for
|
||
|
|
notifications.
|
||
|
|
</p>
|
||
|
|
<p>It is also worth noting that the logic of the
|
||
|
|
methods defined in <code>NotificationEmitter</code> would not
|
||
|
|
be trivial to implement from scratch. Fortunately
|
||
|
|
the JMX API defines a helper class, called
|
||
|
|
<code>NotificationBroadcasterSupport</code>, which
|
||
|
|
provides an implementation for these methods.
|
||
|
|
</p>
|
||
|
|
<p>There are actually three ways for an MBean to
|
||
|
|
implement <code>NotificationEmitter</code>, of which only two
|
||
|
|
are recommended.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h4>Extending NotificationBroadcasterSupport</h4>
|
||
|
|
<ul>
|
||
|
|
<p>This is the simplest way of coding an MBean which
|
||
|
|
is a <code>NotificationEmitter</code>:
|
||
|
|
</p>
|
||
|
|
<p>Simply extend <code>NotificationBroadcasterSupport</code>,
|
||
|
|
then override its <code>getNotificationInfo</code> method
|
||
|
|
which returns the <code>MBeanNotificationInfo[]</code> array
|
||
|
|
that should be included in your MBean's <code>MBeanInfo</code>
|
||
|
|
and that's it.
|
||
|
|
<br>You just need to call the <code>sendNotification</code> method
|
||
|
|
inherited from <code>NotificationBroadcasterSupport</code> whenever
|
||
|
|
your MBean needs to send a notification.
|
||
|
|
</p>
|
||
|
|
<p>In our example, both the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> and <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a> extend
|
||
|
|
<code>NotificationBroadcasterSupport</code> in order
|
||
|
|
to send notifications.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h4>The Delegation Pattern: delegating to a
|
||
|
|
NotificationBroadcasterSupport delegate</h4>
|
||
|
|
<ul>
|
||
|
|
<p>There may be cases however where delegating to a
|
||
|
|
wrapped <code>NotificationBroadcasterSupport</code>
|
||
|
|
object may be preferred to extending
|
||
|
|
<code>NotificationBroadcasterSupport</code>.
|
||
|
|
</p>
|
||
|
|
<p>For instance, if your MBeans already derive from
|
||
|
|
some base class, extending <code>NotificationBroadcasterSupport</code>
|
||
|
|
might not be an option.
|
||
|
|
</p>
|
||
|
|
<p>Similarly, if you do not want to have the inherited
|
||
|
|
<code>public void sendNotification(Notification notification)</code>
|
||
|
|
method appear in the Javadoc of the concrete class of your
|
||
|
|
MBean, you may want to consider using the delegation
|
||
|
|
pattern instead of extending
|
||
|
|
<code>NotificationBroadcasterSupport</code>
|
||
|
|
</p>
|
||
|
|
<p>In our example both the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> and the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBean</a> use the delegation
|
||
|
|
pattern rather than extending
|
||
|
|
<code>NotificationBroadcasterSupport</code>.
|
||
|
|
In the end, choosing between one or the other method
|
||
|
|
is more a question of taste, although the delegation
|
||
|
|
pattern could be considered more flexible since it
|
||
|
|
doesn't require extending any given superclass.
|
||
|
|
</p>
|
||
|
|
<p>It may be also worth noting that some tools like
|
||
|
|
the JMX Module of <a
|
||
|
|
href="http://www.netbeans.org"
|
||
|
|
>NetBeans IDE</a>, will be able to
|
||
|
|
generate for you all the code that delegates to a
|
||
|
|
wrapped <code>NotificationBroadcasterSupport</code>.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h4>Implementing NotificationEmitter from scratch</h4>
|
||
|
|
<ul>
|
||
|
|
<p>This is the last possibility for an MBean that
|
||
|
|
needs to send notifications: simply implement
|
||
|
|
<code>NotificationEmitter</code> from scratch. This is highly
|
||
|
|
discouraged since that logic is not trivial, and
|
||
|
|
already provided by
|
||
|
|
<code>NotificationBroadcasterSupport</code> anyway.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h4>Beware of Synchronization Locks</h4>
|
||
|
|
<ul>
|
||
|
|
|
||
|
|
<p>One thing you must keep in mind when sending
|
||
|
|
notifications is not to send them from within
|
||
|
|
a synchronized block, or while holding a lock on
|
||
|
|
some resource.</p>
|
||
|
|
<p>Indeed, what happens when you send a notification
|
||
|
|
may vary greatly depending on whether the client
|
||
|
|
which has registered for notifications has done
|
||
|
|
so through a <code>JMXConnector</code> (like the
|
||
|
|
<code>JMXRMIConnector</code>)
|
||
|
|
or through a direct reference to the MBeanServer
|
||
|
|
(by calling
|
||
|
|
<code>MBeanServer.addNotificationListener</code>).
|
||
|
|
</p>
|
||
|
|
<p>In this latter case, the listener will be invoked
|
||
|
|
synchronously in the same thread that your MBean is
|
||
|
|
using to send its notification. If by misfortune, the
|
||
|
|
code of that listener now re-enters your MBean through a
|
||
|
|
call that flows through a JMXConnector, a deadlock
|
||
|
|
could occur. It is therefore very important to release
|
||
|
|
any lock you may have before calling
|
||
|
|
<code>sendNotification</code>.</p>
|
||
|
|
<p>An easy way to do that is demonstrated in the
|
||
|
|
<code>ScanManager</code> class. The ScanManager
|
||
|
|
has an internal private queue of pending notifications.
|
||
|
|
When a notification needs to be sent (e.g. because the
|
||
|
|
ScanManager state is being switched), the notification
|
||
|
|
is simply prepared and put into the pending notification
|
||
|
|
queue.
|
||
|
|
The notification queue is then processed later on,
|
||
|
|
at the end of the method, when the processing is finally
|
||
|
|
completed and all the locks have been released.
|
||
|
|
<br>At this point the notification queue might already
|
||
|
|
have been emptied by another thread - in which case
|
||
|
|
the pending notifications will have already been
|
||
|
|
removed from the queue. Which thread actually gets
|
||
|
|
to send the notifications is of no importance. The
|
||
|
|
important point is that all the locks detained by
|
||
|
|
your MBean code in that thread were released before
|
||
|
|
the notification was sent.
|
||
|
|
</p>
|
||
|
|
<p>In our example the <code>ScanManager</code> class
|
||
|
|
ensures this by:
|
||
|
|
<ul>
|
||
|
|
<li>Only calling <code>sendNotification</code>
|
||
|
|
in its private <code>sendQueuedNotifications</code>
|
||
|
|
method.
|
||
|
|
</li>
|
||
|
|
<li>Only calling <code>sendQueuedNotifications</code>
|
||
|
|
when all locks have been released.
|
||
|
|
</li>
|
||
|
|
<li>Never calling a method that calls
|
||
|
|
<code>sendQueuedNotifications</code> from within
|
||
|
|
a synchronized block.</li>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<h4>Don't subclass Notification</h4>
|
||
|
|
<ul>
|
||
|
|
<p>Another common best practice when you want
|
||
|
|
to improve interoperability is to use directly
|
||
|
|
the Notification base classes provided in the
|
||
|
|
JMX<sup>TM</sup> API. Do not create your own
|
||
|
|
subclasses of these standard classes.
|
||
|
|
</p>
|
||
|
|
<p>Indeed, if you code your own subclass, a generic
|
||
|
|
client, like jconsole, will not be able to receive
|
||
|
|
that notification unless it has that custom
|
||
|
|
subclass in its classpath.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If you want your application to be interoperable, it is
|
||
|
|
therefore preferable not to subclass any of the standard
|
||
|
|
Notification classes. You can define your own
|
||
|
|
Notification type string, and if you need to send
|
||
|
|
additional data, you can put a CompositeData, or a
|
||
|
|
HashMap of serializable standard types in the
|
||
|
|
Notification's user data fields.
|
||
|
|
</p>
|
||
|
|
<p>In this example, we are using directly the
|
||
|
|
standard notification classes:
|
||
|
|
<ul>
|
||
|
|
<li>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> and the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBean</a> both use directly
|
||
|
|
<code>AttributeChangeNotification</code> to notify
|
||
|
|
changes in their <code>State</code> attribute.
|
||
|
|
</li>
|
||
|
|
<li>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBean</a>
|
||
|
|
also uses the base <code>Notification</code>
|
||
|
|
class directly in order to notify whenever
|
||
|
|
it finds a matching file.
|
||
|
|
<br>In that case, we simply use the base
|
||
|
|
<code>Notification</code>
|
||
|
|
class with a new
|
||
|
|
<b><code>com.sun.jmx.examples.scandir.filematch</code></b>
|
||
|
|
type.
|
||
|
|
</li>
|
||
|
|
<li>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> and <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
title="The ResultLogManagerMXBean is in charge of managing result logs"
|
||
|
|
>ResultLogManagerMXBean</a> also both use the base
|
||
|
|
<code>Notification</code> class.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>Careful readers will have noted that the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> and the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
title="A DirectoryScannerMXBean looks for file matching a given set of criteria, starting at a given root."
|
||
|
|
>DirectoryScannerMXBean</a> both use the
|
||
|
|
<code>AttributeChangeNotification</code> class
|
||
|
|
to notify about their state change, whereas the
|
||
|
|
<a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> uses the base
|
||
|
|
<code>Notification</code> class.
|
||
|
|
</p>
|
||
|
|
<p>In fact, this is because the semantics of these
|
||
|
|
notifications is not exactly the same - although
|
||
|
|
both denote a state change:
|
||
|
|
<ul>
|
||
|
|
<p>In the case of <code>ScanManagerMXBean</code>
|
||
|
|
and <code>DirectoryScannerMXBean</code>, the
|
||
|
|
notification which is emitted is more about a
|
||
|
|
state transition, from one state to another.
|
||
|
|
For instance, going from <code>RUNNING</code>
|
||
|
|
to <code>STOPPED</code>, or from
|
||
|
|
<code>SCHEDULED</code> to <code>STOPPED</code>.
|
||
|
|
<br>In that case, the
|
||
|
|
<code>AttributeChangeNotification</code> was
|
||
|
|
more appropriate because it made it possible
|
||
|
|
to send the previous and the new value of the
|
||
|
|
state attribute, thus reflecting the whole
|
||
|
|
state transition.
|
||
|
|
</p>
|
||
|
|
<p>In the case of the <code>ScanDirConfigMXBean</code>
|
||
|
|
however, what is of interest is the state in
|
||
|
|
which the MBean has arrived. Using the base
|
||
|
|
<code>Notification</code> class with three different
|
||
|
|
notification type strings -
|
||
|
|
<b><code>com.sun.jmx.examples.scandir.config.loaded</code></b>,
|
||
|
|
<b><code>com.sun.jmx.examples.scandir.config.modified</code></b>,
|
||
|
|
and
|
||
|
|
<b><code>com.sun.jmx.examples.scandir.config.saved</code></b> -
|
||
|
|
was therefore closer to what we wanted to model.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Configuration MBeans</h3>
|
||
|
|
<ul>
|
||
|
|
<p>A common practice when designing a management application is
|
||
|
|
to have an MBean, or a set of MBeans, dedicated to configuration.
|
||
|
|
Separating configuration from control and monitoring allows
|
||
|
|
more appropriate logic, and often simplifies the design and
|
||
|
|
implementation of the management interface.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
In our example, the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a> is dedicated to the application configuration.
|
||
|
|
</p>
|
||
|
|
<p>The <code>ScanDirConfigMXBean</code> will let you interactively
|
||
|
|
modify, save, or load the application configuration. The modifications
|
||
|
|
will not be taken into account until it is applied, by invoking
|
||
|
|
<code>applyConfiguration</code> on the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a>.
|
||
|
|
It is also possible to create many configurations, by creating as
|
||
|
|
many <code>ScanDirConfigMXBean</code>s, and then to choose and apply
|
||
|
|
one of these configurations by calling
|
||
|
|
<code>ScanManagerMXBean.setConfigurationMBean</code> and then
|
||
|
|
<code>ScanManagerMXBean.applyConfiguration</code>.
|
||
|
|
</p>
|
||
|
|
<p>In this way, all configurations aspects are gathered and concentrated
|
||
|
|
inside the <code>ScanDirConfigMXBean</code> instead of being scattered
|
||
|
|
throughout all the MBeans that compose the application.
|
||
|
|
</p>
|
||
|
|
<p>In order to save and store the application configuration data, the
|
||
|
|
<code>ScanDirConfigMXBean</code> uses a set of XML serializable Java beans
|
||
|
|
defined in the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/config/package-summary.html"
|
||
|
|
title="The com.sun.jmx.examples.scandir.config package defines XML serializable beans"
|
||
|
|
>com.sun.jmx.examples.scandir.config</a> package. These beans are very
|
||
|
|
simple Java beans which have been lightly annotated for XML binding.
|
||
|
|
</p>
|
||
|
|
<p>It is worth noting that these same beans can also be handled by the
|
||
|
|
MXBean framework (our beans don't contain recursive data structures) and can
|
||
|
|
therefore be used directly as attributes and parameters of MXBeans, without
|
||
|
|
needing to be Java-serializable (the MXBean framework transform them in
|
||
|
|
CompositeData objects - which <b>are</b> serializable).
|
||
|
|
</p>
|
||
|
|
<p>The same <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/config/ScanManagerConfig.html"
|
||
|
|
title="The com.sun.jmx.examples.scandir.config package defines XML serializable beans"
|
||
|
|
>ScanManagerConfig</a> bean that we use to read from and write to the
|
||
|
|
XML configuration file is thus also used as attribute of the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
title="The ScanDirConfigMXBean is in charge of the configuration"
|
||
|
|
>ScanDirConfigMXBean</a>. It is transformed into a <code>CompositeData</code>
|
||
|
|
by the MXBean framework, and can be easily introspected with
|
||
|
|
<a href="#JConsole">jconsole</a>.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>MBeans Must Be Thread-Safe</h3>
|
||
|
|
<ul>
|
||
|
|
<p>A question often asked by newcomers to JMX technology
|
||
|
|
is whether the MBeanServer is thread-safe. Well, the MBeanServer <b>is</b>
|
||
|
|
thread safe, but it doesn't put any locks on the MBeans it contains. The
|
||
|
|
MBeans can be concurrently accessed by multiple threads, and must therefore
|
||
|
|
take care of their own thread safety.
|
||
|
|
</p>
|
||
|
|
<p>In this example, we have been using two methods to ensure thread
|
||
|
|
safety for our MBeans: synchronized blocks, and semaphores.
|
||
|
|
</p>
|
||
|
|
<p>Using synchronized blocks is probably the most common and easiest way
|
||
|
|
to implement thread safety in Java. When dealing with MBeans though, here
|
||
|
|
are a couple of rules to keep in mind:
|
||
|
|
<ul>
|
||
|
|
<li>Don't send notifications from within a synchronized block: there's
|
||
|
|
no way to tell whether the listener's code will be executed in the
|
||
|
|
same thread or a different thread, and holding a lock in these
|
||
|
|
conditions is therefore dangerous, as it could lead to deadlocks.</li>
|
||
|
|
<li>Also avoid invoking another MBean from a synchronized block
|
||
|
|
unless you are completely in control of both MBeans, and you can
|
||
|
|
ascertain that it won't lead to any deadlock. Indeed, if you invoke an
|
||
|
|
MBean exposed by another application, it can be sometime hard to
|
||
|
|
know with certainty whether holding a lock while invoking that
|
||
|
|
MBean will have any side effect. Maybe that MBean will make
|
||
|
|
further calls to other MBeans which will in turn try to call
|
||
|
|
your MBean, or maybe it will emit a
|
||
|
|
notification, and we'll be back to the considerations just
|
||
|
|
above.</li>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
<p>Another means of implementing thread-safe code is to use semaphores.
|
||
|
|
The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> uses a semaphore called
|
||
|
|
<code>sequencer</code> to ensure
|
||
|
|
that critical code sections are not executed concurrently. In this
|
||
|
|
MBean, we use <code>Semaphore.tryAcquire</code> to lock the sequencer
|
||
|
|
semaphore before entering the critical section. If the
|
||
|
|
<code>Semaphore.tryAcquire</code> returns true then we enter the critical
|
||
|
|
section. If it returns false, we throw an IllegalStateException, stating
|
||
|
|
that we couldn't acquire the lock. The code looks like this:
|
||
|
|
<pre>
|
||
|
|
if (!sequencer.tryAcquire())
|
||
|
|
throw new IllegalStateException("resource locked");
|
||
|
|
try {
|
||
|
|
// critical code here ...
|
||
|
|
} finally {
|
||
|
|
// Always use try/finally to ensure that the semaphore
|
||
|
|
// will be released, even if exceptions or errors are raised!
|
||
|
|
sequencer.release();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>Using <code>Semaphore.tryAcquire</code> and throwing an exception if
|
||
|
|
the semaphore is already locked makes it safer to call other MBeans
|
||
|
|
from within the critical section: in potential deadlock situations
|
||
|
|
the calling code will get the <code>IllegalStateException</code>
|
||
|
|
instead of being blocked on the deadlocked lock.
|
||
|
|
</p>
|
||
|
|
<p>It is worth noting that each of these techniques has its own
|
||
|
|
advantages and disadvantages - which can make one of them more or less
|
||
|
|
appropriate depending on the inner logic of the MBean you're implementing.
|
||
|
|
</p>
|
||
|
|
<p>Careful readers will also have noted that we used
|
||
|
|
<code>IllegalStateException</code> directly, instead of defining
|
||
|
|
our own subclass of RuntimeException, which could have had a more
|
||
|
|
precise semantics. If you define a new exception for your JMX application,
|
||
|
|
you must keep in mind that your client will need to have the class
|
||
|
|
of your exception in its classpath to get that exception.
|
||
|
|
Otherwise your client will get a completely different exception, indicating a
|
||
|
|
deserialization issue.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Waiting for Notifications</h3>
|
||
|
|
<ul>
|
||
|
|
<p>Implementing code that needs to wait for notifications is sometimes
|
||
|
|
difficult. Because notifications are asynchronous, doing something
|
||
|
|
like:
|
||
|
|
<pre>
|
||
|
|
// register a notification listener
|
||
|
|
...
|
||
|
|
// start a management action
|
||
|
|
...
|
||
|
|
// wait for a notification
|
||
|
|
...
|
||
|
|
// do something based on whether the expected notification
|
||
|
|
// is received
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
is not always trivial. However, there's a very easy way to do that: use
|
||
|
|
a blocking queue of notifications.
|
||
|
|
<pre>
|
||
|
|
final BlockingQueue<Notification> notifQueue =
|
||
|
|
new LinkedBlockingQueue<Notification>();
|
||
|
|
|
||
|
|
final NotificationListener listener = new NotificationListener() {
|
||
|
|
public void handleNotification(Notification notification,
|
||
|
|
Object handback) {
|
||
|
|
try {
|
||
|
|
// Just put the received notification in the queue.
|
||
|
|
// It will be consumed later on.
|
||
|
|
//
|
||
|
|
notifQueue.put(notification);
|
||
|
|
} catch (InterruptedException ex) {
|
||
|
|
// OK
|
||
|
|
}
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
// register the listener - possibly also as a JMXConnectionNotification
|
||
|
|
// listener to get Notification Lost notification
|
||
|
|
...
|
||
|
|
// start management action
|
||
|
|
...
|
||
|
|
// wait for notification
|
||
|
|
while (expected notif not received and delay not expired) {
|
||
|
|
Notification n = notifQueue.poll(3,TimeUnit.SECONDS);
|
||
|
|
// if expected notif, do something
|
||
|
|
...
|
||
|
|
}
|
||
|
|
// if expected notification not received do something else.
|
||
|
|
....
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>You will note that this is a technique we've been using in the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirAgent.html"
|
||
|
|
title="The ScanDirAgent class defines a main method for the scandir application"
|
||
|
|
>ScanDirAgent</a> class and in the example unit tests.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Holding hard references to other MBeans: proxy or direct reference?</h3>
|
||
|
|
<ul>
|
||
|
|
<p>We have seen that MXBeans will let you return proxy references to other
|
||
|
|
MXBeans. But should that MXBean hold a direct reference to the MXBeans it
|
||
|
|
relates to, or would it be better for it to hold only a proxy?
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
As a general rule it is better when an MBean reference is
|
||
|
|
only held by the MBeanServer. It is a better design
|
||
|
|
to hold a reference to a proxy, rather than to hold
|
||
|
|
a hard reference to an MBean. However there are two cases
|
||
|
|
when holding a hard reference might be preferred:
|
||
|
|
<ol>
|
||
|
|
<li>When MBean A needs to call a method of method B which
|
||
|
|
is not part of its MBean interface</li>
|
||
|
|
<li>When the overhead of going through the MBeanServer
|
||
|
|
plus the MXBean framework is too great (frequently-called
|
||
|
|
method, with creation of OpenType)</li>
|
||
|
|
</ol>
|
||
|
|
However - holding a hard reference is only advisable
|
||
|
|
when both MBeans are created by the same piece of code,
|
||
|
|
and the application can ensure that the life cycle
|
||
|
|
of each MBean is consistent with regard to the other.
|
||
|
|
</p>
|
||
|
|
<p>In our example, the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> holds only proxy references to the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirConfigMXBean.html"
|
||
|
|
>ScanDirConfigMXBean</a> and the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/DirectoryScannerMXBean.html"
|
||
|
|
>DirectoryScannerMXBeans</a>. <br>
|
||
|
|
However it holds a direct reference to the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManager.html"
|
||
|
|
>ResultLogManager</a>. This makes it possible to pass a direct
|
||
|
|
reference to the <code>DirectoryScannerMXBeans</code>,
|
||
|
|
which can then log their results
|
||
|
|
more efficiently, and would also make it possible to remove
|
||
|
|
the <code>log</code> method from the <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ResultLogManagerMXBean.html"
|
||
|
|
>ResultLogManagerMXBean</a> interface - leaving it in the
|
||
|
|
<code>ResultLogManager</code> class (possibly as a package method)
|
||
|
|
should we wish to do so.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Agent Class</h3>
|
||
|
|
<ul>
|
||
|
|
<p>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirAgent.html"
|
||
|
|
title="The ScanDirAgent class defines a main method for the scandir application"
|
||
|
|
>ScanDirAgent</a> is the Agent class for the <i>scandir</i> application.
|
||
|
|
This class contains the <code>main</code> method to start a standalone
|
||
|
|
<i>scandir</i> application.
|
||
|
|
</p>
|
||
|
|
<p>The <code>main</code> method simply registers a <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a> in the platform MBeanServer, and then waits
|
||
|
|
for someone to call <code>ScanManagerMXBean.close</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
When the <code>ScanManagerMXBean</code> state is switched to
|
||
|
|
<code>ScanManagerMXBean.ScanState.CLOSED</code>, the
|
||
|
|
<code>ScanManagerMXBean</code> is unregistered, and the application
|
||
|
|
terminates (i.e. the main thread completes).
|
||
|
|
</p>
|
||
|
|
<p>Standalone JMX applications usually have an Agent class that contain
|
||
|
|
their <code>main</code> method, which performs all the MBean
|
||
|
|
registration steps.
|
||
|
|
However, it is usually not a bad idea if that class can
|
||
|
|
be easily turned into an MBean. Indeed, this will make your
|
||
|
|
application easier to integrate in an environment where it would
|
||
|
|
no longer be standalone and would no longer control the implementation
|
||
|
|
of <code>main</code>. In our example the Agent
|
||
|
|
class could be easily turned into an MBean, exposing its three
|
||
|
|
<code>init</code>, <code>waitForClose</code> and <code>cleanup</code>
|
||
|
|
method. However we didn't go as far as turning it into an MBean since
|
||
|
|
the application can be already easily started by registering an instance
|
||
|
|
of <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanManagerMXBean.html"
|
||
|
|
title="The ScanManagerMXBean is the main MBean of the scandir application"
|
||
|
|
>ScanManagerMXBean</a>.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>Secure Client Class</h3>
|
||
|
|
<ul>
|
||
|
|
<p>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirClient.html"
|
||
|
|
title="The ScanDirClient class is a very short example of secure programmatic client"
|
||
|
|
>ScanDirClient</a> is an example class that shows how a
|
||
|
|
programmatic client can connect to a secured <i>scandir</i> application.
|
||
|
|
This class contains a <code>main</code> method which creates and
|
||
|
|
configures a <code>JMXConnector</code> client to connect with
|
||
|
|
a secured <i>scandir</i> daemon. This class will not work with
|
||
|
|
the default unsecured agent since it requires mutual authentication.
|
||
|
|
</p>
|
||
|
|
<p>How to secure a JMX <i>scandir</i> application and run
|
||
|
|
the secure <code>ScanDirClient</code> is discussed <a href="#secure"
|
||
|
|
>later</a> in this document.
|
||
|
|
</p>
|
||
|
|
<p>The <code>ScanDirClient</code> is not really part of the
|
||
|
|
application - and is given here only for the sake of
|
||
|
|
the example.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2><a name="h2-Testing">Testing the <i>scandir</i> Example</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>Make sure that you have access to junit.jar (either 3.8.1 or 3.8.2).
|
||
|
|
Make sure also that you have junit.jar in your
|
||
|
|
<code>CLASSPATH</code>.<br>
|
||
|
|
Then in the example root directory (where the <code>build.xml</code>
|
||
|
|
file is located) run the following command:
|
||
|
|
<pre>ant test -Dlibs.junit.classpath=<i><u>path to junit jar (either 3.8.1 or 3.8.2)</u></i></pre>
|
||
|
|
</p>
|
||
|
|
<p>Alternatively you can open the jmx-scandir project with the
|
||
|
|
NetBeans IDE and test the jmx-scandir project from the
|
||
|
|
<code>Run</code> menu.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2><a name="h2-Running">Running the <i>scandir</i> Example</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>In the example root directory (where the <code>build.xml</code>
|
||
|
|
file is located) run the following commands:
|
||
|
|
<pre>ant jar
|
||
|
|
ant run-single -Drun.class=com.sun.jmx.examples.scandir.ScanDirAgent -Djavac.includes=src</pre>
|
||
|
|
or simply <pre>ant run</pre>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>This will run the example using the configuration
|
||
|
|
file provided in the src/etc directory.
|
||
|
|
</p>
|
||
|
|
<p>Alternatively you can open the jmx-scandir project with the
|
||
|
|
NetBeans IDE. You can run the example by
|
||
|
|
selecting the <code>ScanDirAgent</code> file
|
||
|
|
and run it with <code>Run File</code> in the
|
||
|
|
<code>Run</code> menu or simply
|
||
|
|
set the <i>jmx-scandir</i> project as main project and
|
||
|
|
select <code>Run Main Project</code> from the
|
||
|
|
main menu. Both targets will use the configuration
|
||
|
|
file provided in the src/etc directory.
|
||
|
|
</p>
|
||
|
|
<p>When the application is started, you can connect to
|
||
|
|
it with <a href="#JConsole">jconsole</a>.
|
||
|
|
</p>
|
||
|
|
<blockquote>
|
||
|
|
<u>Note:</u> You can also run the <i>scandir</i>
|
||
|
|
application directly from the <code>java</code>
|
||
|
|
command line. Make sure to build the project jar
|
||
|
|
first.
|
||
|
|
<br>On Unix systems:
|
||
|
|
<pre>ant jar
|
||
|
|
java -Djava.util.logging.config.file=logging.properties \
|
||
|
|
-Dscandir.config.file=src/etc/testconfig.xml \
|
||
|
|
-jar dist/jmx-scandir.jar</pre>
|
||
|
|
<br>On Windows systems:
|
||
|
|
<p><code>ant jar<br>
|
||
|
|
java -Djava.util.logging.config.file=logging.properties
|
||
|
|
-Dscandir.config.file=src\etc\testconfig.xml
|
||
|
|
-jar dist\jmx-scandir.jar</code></p>
|
||
|
|
</blockquote>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2><a name="h2-Playing">Playing with JConsole</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>Run the example as explained in the previous section, so
|
||
|
|
that it uses the provided <code>src/etc/testconfig.xml</code>
|
||
|
|
configuration file. Then start
|
||
|
|
jconsole. In the connection window choose the process that runs
|
||
|
|
<code>com.sun.jmx.examples.scandir.ScanDirAgent</code> or
|
||
|
|
<code>jmx-scandir.jar</code>.
|
||
|
|
</p>
|
||
|
|
<p><center>
|
||
|
|
<table border="0" cellpadding="2" cellspacing="2">
|
||
|
|
<tr><td>
|
||
|
|
<a href="docfiles/connect-local-ant-run.jpg"
|
||
|
|
title="jconsole connection window - connect to local process"
|
||
|
|
><img height="440"
|
||
|
|
src="docfiles/connect-local-ant-run.jpg"
|
||
|
|
alt="jconsole connection window - connect to local process"
|
||
|
|
/></a>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
<a href="docfiles/connect-local-java-jar.jpg"
|
||
|
|
title="jconsole connection window - connect to local process"
|
||
|
|
><img height="440"
|
||
|
|
src="docfiles/connect-local-java-jar.jpg"
|
||
|
|
alt="jconsole connection window - connect to local process"
|
||
|
|
/></a>
|
||
|
|
</td></tr></table>
|
||
|
|
</center>
|
||
|
|
</p>
|
||
|
|
<p>Open the MBeans tab, and look for the
|
||
|
|
<code>ScanDirConfigMXBean</code>.
|
||
|
|
Click on its <code>Attributes</code> node and double click on its
|
||
|
|
<code>Configuration</code> attribute, to look at
|
||
|
|
the loaded configuration - values in bold can
|
||
|
|
be expanded by a double-click.
|
||
|
|
</p>
|
||
|
|
<p><center><a href="docfiles/scandir-config.jpg"
|
||
|
|
title="jconsole MBean tab: ScanDirConfigMXBean"
|
||
|
|
><img
|
||
|
|
src="docfiles/scandir-config.jpg"
|
||
|
|
alt="jconsole MBean tab: ScanDirConfigMXBean"
|
||
|
|
/></a></center>
|
||
|
|
</p>
|
||
|
|
<p>Now go to the <code>ScanManagerMXBean</code>, click on
|
||
|
|
its <code>Notifications</code> node, and subscribe
|
||
|
|
for notifications. Then click on the
|
||
|
|
<code>Operations</code> node and invoke the
|
||
|
|
<code>start()</code> operation:
|
||
|
|
</p>
|
||
|
|
<p><center><a href="docfiles/scandir-start.jpg"
|
||
|
|
title="jconsole MBean tab: ScanDirConfigMXBean"
|
||
|
|
><img
|
||
|
|
src="docfiles/scandir-start.jpg"
|
||
|
|
alt="jconsole MBean tab: ScanDirConfigMXBean"
|
||
|
|
/></a></center>
|
||
|
|
</p>
|
||
|
|
<p>You can see that the notifications counter was
|
||
|
|
incremented by three: you have just scheduled,
|
||
|
|
run, and completed a batch of directory scans.
|
||
|
|
</p>
|
||
|
|
<p>Now go to the <code>ResultLogManagerMXBean</code>,
|
||
|
|
click on its <code>Attributes</code> node, and
|
||
|
|
expand its <code>MemoryLog</code> attribute:
|
||
|
|
</p>
|
||
|
|
<p><center><a href="docfiles/scandir-result.jpg"
|
||
|
|
title="jconsole MBean tab: ScanDirConfigMXBean"
|
||
|
|
><img
|
||
|
|
src="docfiles/scandir-result.jpg"
|
||
|
|
alt="jconsole MBean tab: ScanDirConfigMXBean"
|
||
|
|
/></a></center>
|
||
|
|
</p>
|
||
|
|
<p>You can see that the directory scan results have
|
||
|
|
been logged.</p>
|
||
|
|
<p>To make the application terminate go back to the
|
||
|
|
<code>ScanManagerMXBean</code> and invoke
|
||
|
|
<code>close()</code>. The <code>ScanDirAgent</code>
|
||
|
|
will receive the notification, step out of
|
||
|
|
the application main thread, and the application
|
||
|
|
will terminate.
|
||
|
|
</p>
|
||
|
|
<p>This is of course a very limited scenario. Feel free
|
||
|
|
to improvise with all the features of the example, creating
|
||
|
|
a new configuration -
|
||
|
|
<code>ScanManagerMXBean.createOtherConfigurationMBean</code> -
|
||
|
|
adding multiple directory scanners to that configuration -
|
||
|
|
<code>ScanDirConfigMXBean.addDirectoryScanner</code> -
|
||
|
|
then switching the <code>ScanManagerMXBean</code> current
|
||
|
|
configuration by changing the value of the <i>ConfigurationMBean</i>
|
||
|
|
attribute - <code>ScanManagerMXBean.setConfigurationMBean</code>
|
||
|
|
- then applying the new configuration -
|
||
|
|
<code>ScanManagerMXBean.applyConfiguration(true)</code> -
|
||
|
|
then scheduling repeated directory scans every 10 seconds -
|
||
|
|
<code>ScanManagerMXBean.schedule(0,10000)</code> -
|
||
|
|
subscribing for notifications, etc...
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<a name="secure"></a>
|
||
|
|
<h2><a name="h2-Turning">Turning the example into a Secure JMX Application</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>In this section, we will see how to configure and
|
||
|
|
start the <i>scandir</i> example so that the JVM agent
|
||
|
|
is bootstrapped with a secure JMXConnectorServer. Indeed, until
|
||
|
|
now we have only used the insecure local connection,
|
||
|
|
which can only be used as long as both the client and
|
||
|
|
the server run on the same machine. This section will
|
||
|
|
explain how to start the <code>ScanDirAgent</code> so
|
||
|
|
that a real secure RMIConnectorServer is started at bootstrap.
|
||
|
|
</p>
|
||
|
|
<p>To achieve this we will: <a href="#management.properties"
|
||
|
|
>provide our own management.properties</a>, <a
|
||
|
|
href="#password-access">create our own password and access files</a>,
|
||
|
|
<a href="#keystore-truststore">provide a keystore and truststore</a>,
|
||
|
|
<a href="#start-secure-agent">start the ScanDirAgent with the
|
||
|
|
appropriate system properties</a>.
|
||
|
|
</ul>
|
||
|
|
<h3>Configuring the JVM Agent for Secure Remote Connection</h3>
|
||
|
|
<ul>
|
||
|
|
<p>The easiest way to <a name="management.properties">configure the
|
||
|
|
JVM Agent</a> for Secure Remote
|
||
|
|
Connection is to use your own <a
|
||
|
|
href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html#properties"
|
||
|
|
title="This page describes the properties you can put in your management.properties file"
|
||
|
|
>management.properties</a> file.
|
||
|
|
In this example, we have copied the default
|
||
|
|
<code>$JRE/lib/management/management.properties</code>
|
||
|
|
file to the example's <code>src/etc</code> directory and
|
||
|
|
modified it in <a href="src/etc/management.properties"
|
||
|
|
title="our modified management.properties"
|
||
|
|
>this way</a>:
|
||
|
|
<ul>
|
||
|
|
<li>We have set the RMI port to <u>4545</u> - this is just a
|
||
|
|
random port number we have picked up. Feel free to use your
|
||
|
|
own value suited to your environment.
|
||
|
|
<pre># For setting the JMX RMI agent port use the following line
|
||
|
|
com.sun.management.jmxremote.port=<b>4545</b></pre>
|
||
|
|
</li>
|
||
|
|
<li>We have <u>switched on</u> SSL <u>mutual authentication</u>
|
||
|
|
<pre># For RMI monitoring with SSL client authentication use the following line
|
||
|
|
com.sun.management.jmxremote.ssl.<b>need.client.auth</b>=<b>true</b></pre>
|
||
|
|
</li>
|
||
|
|
<li>We have also <u>secured the RMI Registry</u> with SSL
|
||
|
|
<pre># For using an SSL/TLS <b>protected</b> RMI Registry use the following line
|
||
|
|
com.sun.management.jmxremote.<b>registry.ssl</b>=<b>true</b></pre>
|
||
|
|
</li>
|
||
|
|
<li>We have provided <a
|
||
|
|
href="src/etc/password.properties">our own password file</a>
|
||
|
|
<pre># For a non-default password file location use the following line
|
||
|
|
com.sun.management.jmxremote.password.file=<i>src/etc/password.properties</i></pre>
|
||
|
|
</li>
|
||
|
|
<li>We have provided <a
|
||
|
|
href="src/etc/access.properties">our own access file</a>
|
||
|
|
<pre># For a non-default password file location use the following line
|
||
|
|
com.sun.management.jmxremote.access.file=<i>src/etc/access.properties</i></pre>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>You will note that we haven't provided any value
|
||
|
|
for the other security properties, like
|
||
|
|
<code>com.sun.management.jmxremote.authenticate=true</code>,
|
||
|
|
because these properties already default to a value
|
||
|
|
which enables security by default.
|
||
|
|
Note however that protecting the RMI Registry with SSL
|
||
|
|
improves the application security, but only as long as
|
||
|
|
mutual authentication is also switched on. Otherwise, just
|
||
|
|
anybody would be able to connect to the registry and
|
||
|
|
get the RMIServer stub.
|
||
|
|
</p>
|
||
|
|
<p>We do recommend that you <u>use the most secure configuration
|
||
|
|
when you deploy a JMX agent</u> - which means <u>switching on
|
||
|
|
SSL protection for the RMI registry</u> <b>and</b> <u>requiring
|
||
|
|
mutual authentication</u>, as we show in this example.
|
||
|
|
</p>
|
||
|
|
<p>We will use the <code>com.sun.management.config.file</code>
|
||
|
|
system property to pass our <a
|
||
|
|
href="src/etc/management.properties">management.properties</a>
|
||
|
|
file to the <code>ScanDirAgent</code>.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Creating a password and access file</h3>
|
||
|
|
<ul>
|
||
|
|
<p>As explained above, we have created our own
|
||
|
|
<a href="src/etc/password.properties">password file</a>
|
||
|
|
and <a href="src/etc/access.properties">access file</a>
|
||
|
|
for <a name="password-access">access control and authorization</a>.
|
||
|
|
</p>
|
||
|
|
<p>In the password file, we have defined two logins:
|
||
|
|
<i>guest</i> and <i>admin</i>. The password for
|
||
|
|
<i>guest</i> is <i>guestpasswd</i> and the password
|
||
|
|
for <i>admin</i> is <i>adminpasswd</i>.
|
||
|
|
</p>
|
||
|
|
<p>In the access file, we have mapped these two logins
|
||
|
|
to access rights: the <i>admin</i> login has <i>read-write</i>
|
||
|
|
access, while the <i>guest</i> login only has <i>read-only</i>.
|
||
|
|
</p>
|
||
|
|
<p>Before starting the <code>ScanDirAgent</code>, you will
|
||
|
|
need to restrict access permission to the password file,
|
||
|
|
in such a way that nobody but you can read it. Otherwise, the
|
||
|
|
JVM Agent will refuse to start the JMXConnectorServer, as it will
|
||
|
|
fear that security can be compromised if other parties can
|
||
|
|
have read access to the password file. How to restrict
|
||
|
|
read access to the password file is explained in detail
|
||
|
|
<a href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html#PasswordAccessFiles"
|
||
|
|
title="Using Password and Access Files"
|
||
|
|
>here</a>.
|
||
|
|
</p>
|
||
|
|
<p>As we have seen above, the location
|
||
|
|
of our access and password files is configured in our own <a
|
||
|
|
href="src/etc/management.properties">management.properties</a>
|
||
|
|
file.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>Keystore and Truststore</h3>
|
||
|
|
<ul>
|
||
|
|
<p>Using SSL with mutual authentication means that both
|
||
|
|
client and server will need a <a name="keystore-truststore"
|
||
|
|
>keystore and a truststore</a>
|
||
|
|
to store their own certificates, and the certificates of
|
||
|
|
the parties they trust. Usually, client and server will
|
||
|
|
have their own keystore and truststore.
|
||
|
|
</p>
|
||
|
|
<p>For the sake of simplicity - and to get you started
|
||
|
|
without the tedious necessity of creating your own keystore
|
||
|
|
and truststore, we are providing a dummy keystore and
|
||
|
|
truststore, containing a certificate self-signed by duke.
|
||
|
|
The password for our keystore is <i>password</i>, and the
|
||
|
|
password for our truststore is <i>trustword</i>.
|
||
|
|
We suggest that you first get the example running with the
|
||
|
|
keystore and truststore we are providing before attempting
|
||
|
|
to use your own keystore and truststore.
|
||
|
|
</p>
|
||
|
|
<p>A secure application will obviously need to use its own
|
||
|
|
keystore and truststore, <b><u>and should not rely on the keystore
|
||
|
|
and truststore we are providing here!</u></b>
|
||
|
|
</p>
|
||
|
|
<p>How to create your own keystore and truststore, is explained
|
||
|
|
in <a
|
||
|
|
href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html#SSL_enabled"
|
||
|
|
title="Monitoring and Management Using JMX"
|
||
|
|
>here</a>.
|
||
|
|
As shown <a href="#start-secure-agent">later</a>,
|
||
|
|
we will need to use <a
|
||
|
|
href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html#SSL_enabled"
|
||
|
|
>system properties</a> to pass our truststore
|
||
|
|
and keystore to the <code>ScanDirAgent</code>.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h3>Starting a Secure <i>scandir</i> agent</h3>
|
||
|
|
<ul>
|
||
|
|
<p>To start a <a name="start-secure-agent"
|
||
|
|
>secure <i>scandir</i> agent</a>, go to the
|
||
|
|
<i>scandir</i> example root directory and type the
|
||
|
|
following command:</p>
|
||
|
|
<p>On Unix Systems:
|
||
|
|
<pre>ant jar
|
||
|
|
java \
|
||
|
|
-Djava.util.logging.config.file=logging.properties \
|
||
|
|
-Djavax.net.ssl.keyStore=keystore \
|
||
|
|
-Djavax.net.ssl.keyStorePassword=password \
|
||
|
|
-Djavax.net.ssl.trustStore=truststore \
|
||
|
|
-Djavax.net.ssl.trustStorePassword=trustword \
|
||
|
|
-Dcom.sun.management.config.file=src/etc/management.properties \
|
||
|
|
-Dscandir.config.file=src/etc/testconfig.xml \
|
||
|
|
-jar dist/jmx-scandir.jar</pre>
|
||
|
|
</p>
|
||
|
|
<p>On Windows Systems:
|
||
|
|
<p><code>ant jar<br>
|
||
|
|
java
|
||
|
|
-Djava.util.logging.config.file=logging.properties
|
||
|
|
-Djavax.net.ssl.keyStore=keystore
|
||
|
|
-Djavax.net.ssl.keyStorePassword=password
|
||
|
|
-Djavax.net.ssl.trustStore=truststore
|
||
|
|
-Djavax.net.ssl.trustStorePassword=trustword
|
||
|
|
-Dcom.sun.management.config.file=src\etc\management.properties
|
||
|
|
-Dscandir.config.file=src\etc\testconfig.xml
|
||
|
|
-jar dist\jmx-scandir.jar</code></p>
|
||
|
|
</p>
|
||
|
|
<p>If you start jconsole now, you will see that you
|
||
|
|
are still able to connect to the agent using the
|
||
|
|
local connection. However, if you try to connect
|
||
|
|
through the remote connector, using
|
||
|
|
<a href="docfiles/remote-connection.jpg">localhost:4545</a>,
|
||
|
|
the connection will <a href="docfiles/remote-connection-failed.jpg"
|
||
|
|
>fail</a>, even if you provide a correct login/password
|
||
|
|
pair. Indeed, since the JMXConnectorServer is now protected with SSL,
|
||
|
|
jconsole must also be configured with the appropriate SSL parameters
|
||
|
|
so that it can authenticate the server and get authenticated by the
|
||
|
|
server too as the SSL configuration of the server requires mutual
|
||
|
|
authentication.
|
||
|
|
</p>
|
||
|
|
<p>The next section will discuss how to connect to the
|
||
|
|
secure agent.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2><a name="h2-Connecting">Connecting to the Secure JMX Application</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>We will now see how to connect to the secure agent,
|
||
|
|
using jconsole, and using a programmatic client.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Using jconsole to connect to the secure agent</h3>
|
||
|
|
<ul>
|
||
|
|
<p>The only special thing you need to do in order to
|
||
|
|
be able to connect to your secure agent with
|
||
|
|
jconsole, is to give it a keystore (containing
|
||
|
|
its client certificate) and a truststore (containing
|
||
|
|
the certificates of the servers it can trust).
|
||
|
|
In our example, we use the same keystore/truststore
|
||
|
|
pair on the client and server side - but this is
|
||
|
|
not what a real application would do.
|
||
|
|
Indeed a real application would have different
|
||
|
|
certificates for the client and the server, and
|
||
|
|
thus use different keystores (and probably truststores).
|
||
|
|
More information on SSL authentication can be obtained from the <a
|
||
|
|
href="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#HowSSLWorks"
|
||
|
|
title="How SSL Works"
|
||
|
|
>Java<sup>TM</sup> Secure Socket Extension (JSSE) Reference Guide</a>.
|
||
|
|
</p>
|
||
|
|
<p>To start jconsole with our provided keystore and
|
||
|
|
truststore, go to the scandir example root directory and
|
||
|
|
type in the following command:
|
||
|
|
<p><code>jconsole
|
||
|
|
-J-Djava.util.logging.config.file=logging.properties
|
||
|
|
-J-Djavax.net.ssl.keyStore=keystore
|
||
|
|
-J-Djavax.net.ssl.keyStorePassword=password
|
||
|
|
-J-Djavax.net.ssl.trustStore=truststore
|
||
|
|
-J-Djavax.net.ssl.trustStorePassword=trustword</code></p>
|
||
|
|
</p>
|
||
|
|
<p>The <code>-J-Djava.util.logging.config.file=logging.properties</code>
|
||
|
|
flag is not mandatory, but passing a <code>logging.properties</code>
|
||
|
|
may help you debug connection problems if anything goes wrong.
|
||
|
|
</p>
|
||
|
|
<p>In jconsole connection window, choose to connect to a
|
||
|
|
remote process, using the address <i>localhost:4545</i>
|
||
|
|
and the guest login:
|
||
|
|
</p>
|
||
|
|
<p><center><a href="docfiles/remote-connection.jpg"
|
||
|
|
><img src="docfiles/remote-connection.jpg"
|
||
|
|
alt="jconsole connection window"/></a></center>
|
||
|
|
</p>
|
||
|
|
<p>You will see that the agent will let view all the
|
||
|
|
MBeans and their attributes, but will reject any
|
||
|
|
attribute modification or remote method invocation.
|
||
|
|
</p>
|
||
|
|
<hr>
|
||
|
|
<p><u>Note:</u> if jconsole fails to connect and show
|
||
|
|
you <a href="docfiles/remote-connection-failed.jpg">this screen</a>
|
||
|
|
you have probably misspelled some of the properties on jconsole
|
||
|
|
command line, or you didn't start jconsole from the
|
||
|
|
scandir example root directory where our <code>truststore</code>
|
||
|
|
and <code>keystore</code> files are located. This article - <a
|
||
|
|
href="http://blogs.sun.com/roller/page/jmxetc?entry=troubleshooting_connection_problems_in_jconsole"
|
||
|
|
title="Troubleshooting connection problems in JConsole"
|
||
|
|
>Troubleshooting connection problems in JConsole</a> - may help
|
||
|
|
you figure out what is going wrong.
|
||
|
|
</p>
|
||
|
|
<hr>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Writing a programmatic client to connect to the secure agent</h3>
|
||
|
|
<ul>
|
||
|
|
<p>
|
||
|
|
In this section we will show the steps involved in writing
|
||
|
|
a programmatic client that will connect to our secure agent.
|
||
|
|
</p>
|
||
|
|
<p>The <a
|
||
|
|
href="dist/javadoc/com/sun/jmx/examples/scandir/ScanDirClient.html"
|
||
|
|
title="The ScanDirClient class is a very short example of secure programmatic client"
|
||
|
|
>ScanDirClient</a> is an example class that shows how a
|
||
|
|
programmatic client can connect to a secured <i>scandir</i> application.
|
||
|
|
This class contains a <code>main</code> method which creates and
|
||
|
|
configures a <code>JMXConnector</code> client to connect with
|
||
|
|
the secured <i>scandir</i> agent.
|
||
|
|
</p>
|
||
|
|
<p>The secure client differs only from a non secure client in
|
||
|
|
so far as it needs to use SSL RMI Factories and credentials to
|
||
|
|
connect to the secure agent. The steps required mainly involve:
|
||
|
|
<ul>
|
||
|
|
<li>Creating an empty environment map:
|
||
|
|
<pre>
|
||
|
|
// Create an environment map to hold connection properties
|
||
|
|
// like credentials etc... We will later pass this map
|
||
|
|
// to the JMX Connector.
|
||
|
|
//
|
||
|
|
System.out.println("\nInitialize the environment map");
|
||
|
|
final Map<String,Object> env = new HashMap<String,Object>();
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li>Putting the client's credentials in that map:
|
||
|
|
<i>(here the client will log in as <b>guest</b>)</i>
|
||
|
|
<pre>
|
||
|
|
// Provide the credentials required by the server
|
||
|
|
// to successfully perform user authentication
|
||
|
|
//
|
||
|
|
final String[] credentials = new String[] { "guest" , "guestpasswd" };
|
||
|
|
env.put("jmx.remote.credentials", credentials);
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li>Providing an <code>SslRMIClientSocketFactory</code> to interact
|
||
|
|
with the secure RMI Registry:
|
||
|
|
<pre>
|
||
|
|
// Provide the SSL/TLS-based RMI Client Socket Factory required
|
||
|
|
// by the JNDI/RMI Registry Service Provider to communicate with
|
||
|
|
// the SSL/TLS-protected RMI Registry
|
||
|
|
//
|
||
|
|
env.put("com.sun.jndi.rmi.factory.socket",
|
||
|
|
new SslRMIClientSocketFactory());
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li>Creating a JMXConnector and connecting with the
|
||
|
|
secure server:
|
||
|
|
<pre>
|
||
|
|
// Create the RMI connector client and
|
||
|
|
// connect it to the secure RMI connector server.
|
||
|
|
// args[0] is the server's host - localhost
|
||
|
|
// args[1] is the secure server port - 4545
|
||
|
|
//
|
||
|
|
System.out.println("\nCreate the RMI connector client and " +
|
||
|
|
"connect it to the RMI connector server");
|
||
|
|
final JMXServiceURL url = new JMXServiceURL(
|
||
|
|
"service:jmx:rmi:///jndi/rmi://"+args[0]+":"+args[1]+
|
||
|
|
"/jmxrmi");
|
||
|
|
final JMXConnector jmxc = JMXConnectorFactory.connect(url, env);
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>For this to work, we also need to start the <code>ScanDirClient</code>
|
||
|
|
with the appropriate system properties that will point to our
|
||
|
|
<code>keystore</code> and <code>truststore</code>. To start the secure
|
||
|
|
client, go to the <i>scandir</i> example root directory and type
|
||
|
|
the following command:
|
||
|
|
<p><code>ant jar<br>
|
||
|
|
java
|
||
|
|
-Djava.util.logging.config.file=logging.properties
|
||
|
|
-Djavax.net.ssl.keyStore=keystore
|
||
|
|
-Djavax.net.ssl.keyStorePassword=password
|
||
|
|
-Djavax.net.ssl.trustStore=truststore
|
||
|
|
-Djavax.net.ssl.trustStorePassword=trustword
|
||
|
|
-classpath dist/jmx-scandir.jar
|
||
|
|
com.sun.jmx.examples.scandir.ScanDirClient localhost 4545
|
||
|
|
</code></p>
|
||
|
|
</p>
|
||
|
|
<p>You should be seeing this trace:
|
||
|
|
<center><table width="90%" border="0" bgcolor="#eeeeee">
|
||
|
|
<tr><td>
|
||
|
|
<pre>
|
||
|
|
Initialize the environment map
|
||
|
|
|
||
|
|
Create the RMI connector client and connect it to the RMI connector server
|
||
|
|
Connecting to: service:jmx:rmi:///jndi/rmi://localhost:4545/jmxrmi
|
||
|
|
|
||
|
|
Get the MBeanServerConnection
|
||
|
|
|
||
|
|
Get ScanDirConfigMXBean from ScanManagerMXBean
|
||
|
|
|
||
|
|
Get 'Configuration' attribute on ScanDirConfigMXBean
|
||
|
|
|
||
|
|
Configuration:
|
||
|
|
|
||
|
|
<ScanManager xmlns="jmx:com.sun.jmx.examples.scandir.config" name="testconfig">
|
||
|
|
<InitialResultLogConfig>
|
||
|
|
<LogFileMaxRecords>2048</LogFileMaxRecords>
|
||
|
|
<LogFileName>build/scandir.log</LogFileName>
|
||
|
|
<MemoryMaxRecords>128</MemoryMaxRecords>
|
||
|
|
</InitialResultLogConfig>
|
||
|
|
<DirectoryScannerList>
|
||
|
|
<DirectoryScanner name="scan-build">
|
||
|
|
<Actions>NOTIFY LOGRESULT</Actions>
|
||
|
|
<ExcludeFiles/>
|
||
|
|
<IncludeFiles>
|
||
|
|
<FileFilter>
|
||
|
|
<FilePattern>.*\.class</FilePattern>
|
||
|
|
<SizeExceedsMaxBytes>4096</SizeExceedsMaxBytes>
|
||
|
|
</FileFilter>
|
||
|
|
</IncludeFiles>
|
||
|
|
<RootDirectory>build</RootDirectory>
|
||
|
|
</DirectoryScanner>
|
||
|
|
</DirectoryScannerList>
|
||
|
|
</ScanManager>
|
||
|
|
|
||
|
|
Invoke 'close' on ScanManagerMXBean
|
||
|
|
|
||
|
|
Got expected security exception: java.lang.SecurityException: Access denied!
|
||
|
|
Invalid access level for requested MBeanServer operation.
|
||
|
|
|
||
|
|
Close the connection to the server
|
||
|
|
|
||
|
|
Bye! Bye!
|
||
|
|
</pre>
|
||
|
|
</td></tr></table></center>
|
||
|
|
<p>If the <code>ScanDirClient</code> fails to connect with
|
||
|
|
the secure agent, then this article - <a
|
||
|
|
href="http://blogs.sun.com/roller/page/jmxetc?entry=troubleshooting_connection_problems_in_jconsole"
|
||
|
|
title="Troubleshooting connection problems in JConsole"
|
||
|
|
>Troubleshooting connection problems in JConsole</a> - may help
|
||
|
|
you figure out what is going wrong. Indeed the connection steps
|
||
|
|
performed by the <code>ScanDirClient</code> are very similar to
|
||
|
|
those performed by <code>jconsole</code>, and the problems you
|
||
|
|
could encounter are identical. Just remember that
|
||
|
|
<code>jconsole</code> needs the extra <code>-J</code> flag to pass
|
||
|
|
system properties to the VM, which is not needed with regular
|
||
|
|
<code>java</code> launcher invocations.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2><a name="h2-Conclusion">Conclusion</a></h2>
|
||
|
|
<ul>
|
||
|
|
<p>
|
||
|
|
In this document, we have presented an advanced
|
||
|
|
JMX example, and shown how to run a secure
|
||
|
|
JMX agent in a production environment.
|
||
|
|
We have also shown how to connect to such a
|
||
|
|
secure agent with both jconsole and a programmatic
|
||
|
|
client. We have also discuss various JMX
|
||
|
|
design-patterns and best practices.
|
||
|
|
Readers who would wish to learn more about JMX, and
|
||
|
|
Monitoring and Management of the JVM, are invited
|
||
|
|
to follow the links given in reference below.
|
||
|
|
</p>
|
||
|
|
</ul>
|
||
|
|
<h2><a name="h2-References">References</a></h2>
|
||
|
|
<ol>
|
||
|
|
<li><a href="http://java.sun.com/products/JavaManagement/best-practices.html"
|
||
|
|
>JMX Best Practices</a>: This document describes best practices that
|
||
|
|
have been identified for modeling using the JMX API. </li>
|
||
|
|
<li><a href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html"
|
||
|
|
>Monitoring and Management Using JMX</a>: How to enable, configure, and
|
||
|
|
connect to the JVM JMX agent.</li>
|
||
|
|
<li><a name="JConsole"><a
|
||
|
|
href="http://java.sun.com/javase/6/docs/technotes/guides/management/jconsole.html"
|
||
|
|
>Using JConsole</a>: JConsole is a JMX-Compliant monitoring tool which allows
|
||
|
|
you to interact graphically with your own MBeans.
|
||
|
|
</li>
|
||
|
|
<li><a href="http://java.sun.com/javase/6/docs/technotes/guides/management/"
|
||
|
|
>Monitoring and Management for the Java Platform</a>: The Java Platform
|
||
|
|
Standard Edition (Java SE) 6 provides comprehensive monitoring and
|
||
|
|
management support for the Java platform. </li>
|
||
|
|
<li><a href="http://java.sun.com/products/JavaManagement/community/jmx_blogs.html"
|
||
|
|
>List of JMX-related Blogs</a>: This page provides links to the
|
||
|
|
different web logs written by members of the Sun team working on the
|
||
|
|
JMX API.</li>
|
||
|
|
<li><a
|
||
|
|
href="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#HowSSLWorks"
|
||
|
|
title="The JSSE Reference Guide"
|
||
|
|
>Java<sup>TM</sup> Secure Socket Extension (JSSE) Reference Guide</a>:
|
||
|
|
comprehensive documentation about the Java<sup>TM</sup> Secure Socket
|
||
|
|
Extension (JSSE)
|
||
|
|
</li>
|
||
|
|
<li><a href="http://java.sun.com/javase/6/docs/"
|
||
|
|
>Java SE 6 Documentation Index</a>: This document covers the
|
||
|
|
Java<sup>TM</sup> Platform, Standard Edition 6 JDK.</li>
|
||
|
|
</ol>
|
||
|
|
<p>
|
||
|
|
<hr>
|
||
|
|
<p>
|
||
|
|
</body>
|
||
|
|
</html>
|