<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
  <head>
<!--
 Copyright (c) 2006, 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 programatic 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 programatic 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>