jdk/src/share/sample/jmx/jmx-scandir/index.html - edge/openjdk - Git at Google


            
            <!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&nbsp;the&nbsp;Java&nbsp;Documentation</a>]

            
              [<a href="#h2-Overview">Overview&nbsp;of&nbsp;the&nbsp;<i>scandir</i>&nbsp;Example</a>]

            
              [<a href="#h2-API-Doc">API&nbsp;Documentation&nbsp;and&nbsp;Sources</a>]

            
              [<a href="#h2-Patterns">Patterns,&nbsp;Best&nbsp;Practices,&nbsp;and&nbsp;Common&nbsp;Pitfalls</a>]

            
              [<a href="#h2-Testing">Testing&nbsp;the&nbsp;<i>scandir</i>&nbsp;Example</a>]

            
              [<a href="#h2-Running">Running&nbsp;the&nbsp;<i>scandir</i>&nbsp;Example</a>]

            
              [<a href="#h2-Playing">Playing&nbsp;with&nbsp;JConsole</a>]

            
              [<a href="#h2-Turning">Turning&nbsp;the&nbsp;example&nbsp;into&nbsp;a&nbsp;Secure&nbsp;JMX&nbsp;Application</a>]

            
              [<a href="#h2-Connecting">Connecting&nbsp;to&nbsp;the&nbsp;Secure&nbsp;JMX&nbsp;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&lt;String,DirectoryScannerMXBean&gt; 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&lt;String,ObjectName&gt;</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&lt;String,DirectoryScannerConfig&gt; 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&lt;Notification&gt; notifQueue =

            
                            new LinkedBlockingQueue&lt;Notification&gt;();


                   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 &nbsp;-Djava.util.logging.config.file=logging.properties

            
                 &nbsp;-Dscandir.config.file=src\etc\testconfig.xml

            
                 &nbsp;-jar&nbsp;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

            
                &nbsp;-Djava.util.logging.config.file=logging.properties

            
                &nbsp;-Djavax.net.ssl.keyStore=keystore

            
                &nbsp;-Djavax.net.ssl.keyStorePassword=password

            
                &nbsp;-Djavax.net.ssl.trustStore=truststore

            
                &nbsp;-Djavax.net.ssl.trustStorePassword=trustword

            
                &nbsp;-Dcom.sun.management.config.file=src\etc\management.properties

            
                &nbsp;-Dscandir.config.file=src\etc\testconfig.xml

            
                &nbsp;-jar&nbsp;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

            
                &nbsp;-J-Djava.util.logging.config.file=logging.properties

            
                &nbsp;-J-Djavax.net.ssl.keyStore=keystore

            
                &nbsp;-J-Djavax.net.ssl.keyStorePassword=password

            
                &nbsp;-J-Djavax.net.ssl.trustStore=truststore

            
                &nbsp;-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&lt;String,Object> env = new HashMap&lt;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

            
                &nbsp;-Djava.util.logging.config.file=logging.properties

            
                &nbsp;-Djavax.net.ssl.keyStore=keystore

            
                &nbsp;-Djavax.net.ssl.keyStorePassword=password

            
                &nbsp;-Djavax.net.ssl.trustStore=truststore

            
                &nbsp;-Djavax.net.ssl.trustStorePassword=trustword

            
                &nbsp;-classpath&nbsp;dist/jmx-scandir.jar

            
                 &nbsp;com.sun.jmx.examples.scandir.ScanDirClient&nbsp;localhost&nbsp;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:


            &lt;ScanManager xmlns="jmx:com.sun.jmx.examples.scandir.config" name="testconfig">

            
                &lt;InitialResultLogConfig>

            
                    &lt;LogFileMaxRecords>2048&lt;/LogFileMaxRecords>

            
                    &lt;LogFileName>build/scandir.log&lt;/LogFileName>

            
                    &lt;MemoryMaxRecords>128&lt;/MemoryMaxRecords>

            
                &lt;/InitialResultLogConfig>

            
                &lt;DirectoryScannerList>

            
                    &lt;DirectoryScanner name="scan-build">

            
                        &lt;Actions>NOTIFY LOGRESULT&lt;/Actions>

            
                        &lt;ExcludeFiles/>

            
                        &lt;IncludeFiles>

            
                            &lt;FileFilter>

            
                                &lt;FilePattern>.*\.class&lt;/FilePattern>

            
                                &lt;SizeExceedsMaxBytes>4096&lt;/SizeExceedsMaxBytes>

            
                            &lt;/FileFilter>

            
                        &lt;/IncludeFiles>

            
                        &lt;RootDirectory>build&lt;/RootDirectory>

            
                    &lt;/DirectoryScanner>

            
                &lt;/DirectoryScannerList>

            
            &lt;/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>