jdk/src/java.management/share/classes/javax/management/package.html
author uvangapally
Tue, 01 Aug 2017 10:33:47 +0530
changeset 46050 f51c14dc540f
parent 30678 a8b7fd8ede97
permissions -rw-r--r--
8181895: javax management docs contain links to technotes Summary: Edited links to point to Alternate paths Reviewed-by: rriggs Contributed-by: ujwal.vangapally@oracle.com
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
<html>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
     2
    <head>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
     3
        <title>javax.management package</title>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
     4
        <!--
46050
f51c14dc540f 8181895: javax management docs contain links to technotes
uvangapally
parents: 30678
diff changeset
     5
Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4156
diff changeset
    10
published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4156
diff changeset
    12
by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    21
2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    22
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
5551
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    24
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    25
or visit www.oracle.com if you need additional information or have any
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    26
questions.
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    27
        -->
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    28
    </head>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    29
    <body bgcolor="white">
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    30
        <p>Provides the core classes for the Java Management Extensions.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    32
        <p>The Java Management Extensions
30678
a8b7fd8ede97 8075284: fix up miscellaneous TM constructions
darcy
parents: 25859
diff changeset
    33
            (JMX&trade;) API is a standard
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    34
        API for management and monitoring.  Typical uses include:</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    36
        <ul>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    37
            <li>consulting and changing application configuration</li>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    39
            <li>accumulating statistics about application behavior and
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    40
            making them available</li>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    42
            <li>notifying of state changes and erroneous conditions.</li>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    43
        </ul>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    45
        <p>The JMX API can also be used as part of a solution for
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    46
        managing systems, networks, and so on.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    48
        <p>The API includes remote access, so a remote management
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    49
            program can interact with a running application for these
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    50
        purposes.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    52
        <h2>MBeans</h2>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    54
        <p>The fundamental notion of the JMX API is the <em>MBean</em>.
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    55
            An MBean is a named <em>managed object</em> representing a
18805
b359f8adc8ad 8010285: Enforce the requirement of Management Interfaces being public
jbachorik
parents: 9693
diff changeset
    56
            resource.  It has a <em id="mgIface">management interface</em>
b359f8adc8ad 8010285: Enforce the requirement of Management Interfaces being public
jbachorik
parents: 9693
diff changeset
    57
            which must be <em>public</em> and consist of:</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    59
        <ul>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    60
            <li>named and typed attributes that can be read and/or
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    61
            written</li>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    63
            <li>named and typed operations that can be invoked</li>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    64
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    65
            <li>typed notifications that can be emitted by the MBean.</li>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    66
        </ul>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    68
        <p>For example, an MBean representing an application's
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    69
            configuration could have attributes representing the different
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    70
            configuration items.  Reading the <code>CacheSize</code>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    71
            attribute would return the current value of that item.
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    72
            Writing it would update the item, potentially changing the
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    73
            behavior of the running application.  An operation such as
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    74
            <code>save</code> could store the current configuration
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    75
            persistently.  A notification such as
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    76
            <code>ConfigurationChangedNotification</code> could be sent
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    77
        every time the configuration is changed.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    79
        <p>In the standard usage of the JMX API, MBeans are implemented
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    80
            as Java objects.  However, as explained below, these objects are
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    81
        not usually referenced directly.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    84
        <h3>Standard MBeans</h3>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    86
        <p>To make MBean implementation simple, the JMX API includes the
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    87
            notion of <em>Standard MBeans</em>.  A Standard MBean is one
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    88
            whose attributes and operations are deduced from a Java
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    89
            interface using certain naming patterns, similar to those used
30678
a8b7fd8ede97 8075284: fix up miscellaneous TM constructions
darcy
parents: 25859
diff changeset
    90
            by JavaBeans&trade;.  For example, consider an interface like this:</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
    92
        <pre>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
    public interface ConfigurationMBean {
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    94
         public int getCacheSize();
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    95
         public void setCacheSize(int size);
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    96
         public long getLastChangedTime();
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    97
         public void save();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
    }
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
    99
        </pre>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   101
        <p>The methods <code>getCacheSize</code> and
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   102
            <code>setCacheSize</code> define a read-write attribute of
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   103
            type <code>int</code> called <code>CacheSize</code> (with an
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   104
        initial capital, unlike the JavaBeans convention).</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   106
        <p>The method <code>getLastChangedTime</code> defines an
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   107
            attribute of type <code>long</code> called
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   108
            <code>LastChangedTime</code>.  This is a read-only attribute,
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   109
        since there is no method <code>setLastChangedTime</code>.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   111
        <p>The method <code>save</code> defines an operation called
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   112
            <code>save</code>.  It is not an attribute, since its name
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   113
            does not begin with <code>get</code>, <code>set</code>, or
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   114
        <code>is</code>.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   116
        <p>The exact naming patterns for Standard MBeans are detailed in
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   117
        the <a href="#spec">JMX Specification</a>.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   119
        <p>There are two ways to make a Java object that is an MBean
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   120
            with this management interface.  One is for the object to be
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   121
            of a class that has exactly the same name as the Java
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   122
            interface but without the <code>MBean</code> suffix.  So in
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   123
            the example the object would be of the class
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   124
            <code>Configuration</code>, in the same Java package as
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   125
            <code>ConfigurationMBean</code>.  The second way is to use the
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   126
            {@link javax.management.StandardMBean StandardMBean}
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   127
        class.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   130
        <h3>MXBeans</h3>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   132
        <p>An <em>MXBean</em> is a variant of Standard MBean where complex
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   133
            types are mapped to a standard set of types defined in the
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   134
            {@link javax.management.openmbean} package.  MXBeans are appropriate
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   135
            if you would otherwise need to reference application-specific
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   136
            classes in your MBean interface.  They are described in detail
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   137
        in the specification for {@link javax.management.MXBean MXBean}.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   138
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   140
        <h3>Dynamic MBeans</h3>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   142
        <p>A <em>Dynamic MBean</em> is an MBean that defines its
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   143
            management interface at run-time.  For example, a configuration
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   144
            MBean could determine the names and types of the attributes it
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   145
        exposes by parsing an XML file.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   146
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   147
        <p>Any Java object of a class that implements the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   148
            javax.management.DynamicMBean DynamicMBean} interface is a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   149
        Dynamic MBean.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   152
        <h3>Open MBeans</h3>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   153
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   154
        <p>An <em>Open MBean</em> is a kind of Dynamic MBean where the
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   155
            types of attributes and of operation parameters and return
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   156
            values are built using a small set of predefined Java classes.
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   157
            Open MBeans facilitate operation with remote management programs
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   158
            that do not necessarily have access to application-specific
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   159
            types, including non-Java programs.  Open MBeans are defined by
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   160
            the package <a href="openmbean/package-summary.html"><code>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   161
        javax.management.openmbean</code></a>.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   162
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   164
        <h3>Model MBeans</h3>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   165
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   166
        <p>A <em>Model MBean</em> is a kind of Dynamic MBean that acts
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   167
            as a bridge between the management interface and the
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   168
            underlying managed resource.  Both the management interface and
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   169
            the managed resource are specified as Java objects.  The same
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   170
            Model MBean implementation can be reused many times with
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   171
            different management interfaces and managed resources, and it can
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   172
            provide common functionality such as persistence and caching.
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   173
            Model MBeans are defined by the package
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   174
            <a href="modelmbean/package-summary.html"><code>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   175
        javax.management.modelmbean</code></a>.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   178
        <h2>MBean Server</h2>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   180
        <p>To be useful, an MBean must be registered in an <em>MBean
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   181
            Server</em>.  An MBean Server is a repository of MBeans.
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   182
            Usually the only access to the MBeans is through the MBean
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   183
            Server.  In other words, code no longer accesses the Java
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   184
            object implementing the MBean directly, but instead accesses
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   185
            the MBean by name through the MBean Server.  Each MBean has a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   186
            unique name within the MBean Server, defined by the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   187
        javax.management.ObjectName ObjectName} class.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   189
        <p>An MBean Server is an object implementing the interface
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   190
            {@link javax.management.MBeanServer MBeanServer}.
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   191
            The most convenient MBean Server to use is the
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   192
            <em>Platform MBean Server</em>.  This is a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   193
            single MBean Server that can be shared by different managed
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   194
            components running within the same Java Virtual Machine.  The
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   195
            Platform MBean Server is accessed with the method {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   196
        java.lang.management.ManagementFactory#getPlatformMBeanServer()}.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   198
        <p>Application code can also create a new MBean Server, or
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   199
            access already-created MBean Servers, using the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   200
        javax.management.MBeanServerFactory MBeanServerFactory} class.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   203
        <h3>Creating MBeans in the MBean Server</h3>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   204
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   205
        <p>There are two ways to create an MBean.  One is to construct a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   206
            Java object that will be the MBean, then use the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   207
            javax.management.MBeanServer#registerMBean registerMBean}
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   208
            method to register it in the MBean Server.  The other is to
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   209
            create and register the MBean in a single operation using one
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   210
            of the {@link javax.management.MBeanServer#createMBean(String,
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   211
        javax.management.ObjectName) createMBean} methods.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   213
        <p>The <code>registerMBean</code> method is simpler for local
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   214
            use, but cannot be used remotely.  The
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   215
            <code>createMBean</code> method can be used remotely, but
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   216
        sometimes requires attention to class loading issues.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   218
        <p>An MBean can perform actions when it is registered in or
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   219
            unregistered from an MBean Server if it implements the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   220
            javax.management.MBeanRegistration MBeanRegistration}
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   221
        interface.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   222
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   223
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   224
        <h3>Accessing MBeans in the MBean Server</h3>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   225
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   226
        <p>Given an <code>ObjectName</code> <code>name</code> and an
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   227
            <code>MBeanServer</code> <code>mbs</code>, you can access
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   228
        attributes and operations as in this example:</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   229
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   230
        <pre>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
    int cacheSize = mbs.getAttribute(name, "CacheSize");
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
    {@link javax.management.Attribute Attribute} newCacheSize =
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   233
         new Attribute("CacheSize", new Integer(2000));
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
    mbs.setAttribute(name, newCacheSize);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
    mbs.invoke(name, "save", new Object[0], new Class[0]);
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   236
        </pre>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   238
        <p id="proxy">Alternatively, if you have a Java interface that
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   239
            corresponds to the management interface for the MBean, you can use an
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   240
        <em>MBean proxy</em> like this:</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   242
        <pre>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   243
    ConfigurationMBean conf =
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
        {@link javax.management.JMX#newMBeanProxy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
            JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
    int cacheSize = conf.getCacheSize();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
    conf.setCacheSize(2000);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   248
    conf.save();
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   249
        </pre>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   251
        <p>Using an MBean proxy is just a convenience.  The second
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   252
            example ends up calling the same <code>MBeanServer</code>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   253
        operations as the first one.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   255
        <p>An MBean Server can be queried for MBeans whose names match
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   256
            certain patterns and/or whose attributes meet certain
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   257
            constraints.  Name patterns are constructed using the {@link
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   258
            javax.management.ObjectName ObjectName} class and constraints
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   259
            are constructed using the {@link javax.management.Query Query}
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   260
            class.  The methods {@link
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   261
            javax.management.MBeanServer#queryNames queryNames} and {@link
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   262
            javax.management.MBeanServer#queryMBeans queryMBeans} then
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   263
        perform the query.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   266
        <h3>MBean lifecycle</h3>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   268
        <p>An MBean can implement the {@link javax.management.MBeanRegistration
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   269
            MBeanRegistration} interface in order to be told when it is registered
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   270
            and unregistered in the MBean Server. Additionally, the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   271
            javax.management.MBeanRegistration#preRegister preRegister} method
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   272
            allows the MBean to get a reference to the <code>MBeanServer</code>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   273
            object and to get its <code>ObjectName</code> within the MBean
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   274
        Server.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   277
        <h2>Notifications</h2>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   278
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   279
        <p>A <em>notification</em> is an instance of the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   280
            javax.management.Notification Notification} class or a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   281
            subclass.  In addition to its Java class, it has a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   282
            <em>type</em> string that can distinguish it from other
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   283
        notifications of the same class.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   284
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   285
        <p>An MBean that will emit notifications must implement the
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   286
            {@link javax.management.NotificationBroadcaster
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   287
            NotificationBroadcaster} or {@link
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   288
            javax.management.NotificationEmitter NotificationEmitter}
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   289
            interface.  Usually, it does this by subclassing
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   290
            {@link javax.management.NotificationBroadcasterSupport
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   291
            NotificationBroadcasterSupport} or delegating to an instance of
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   292
        that class. Here is an example:</p>
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   293
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   294
        <pre>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   295
    public class Configuration <b>extends NotificationBroadcasterSupport</b>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   296
            implements ConfigurationMBean {
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   297
        ...
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   298
        private void updated() {
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   299
            Notification n = new Notification(...);
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   300
            <b>{@link javax.management.NotificationBroadcasterSupport#sendNotification
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   301
            sendNotification}(n)</b>;
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   302
        }
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   303
    }
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   304
        </pre>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   305
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   306
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   307
        <p>Notifications can be received by a <em>listener</em>, which
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   308
            is an object that implements the {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   309
            javax.management.NotificationListener NotificationListener}
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   310
            interface.  You can add a listener to an MBean with the method
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   311
            {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   312
            javax.management.MBeanServer#addNotificationListener(ObjectName,
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   313
            NotificationListener, NotificationFilter, Object)}.
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   314
            You can optionally supply a <em>filter</em> to this method, to
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   315
            select only notifications of interest.  A filter is an object
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   316
            that implements the {@link javax.management.NotificationFilter
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   317
        NotificationFilter} interface.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   318
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   319
        <p>An MBean can be a listener for notifications emitted by other
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   320
            MBeans in the same MBean Server.  In this case, it implements
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   321
            {@link javax.management.NotificationListener
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   322
            NotificationListener} and the method {@link
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   323
            javax.management.MBeanServer#addNotificationListener(ObjectName,
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   324
        ObjectName, NotificationFilter, Object)} is used to listen.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   325
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   326
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   327
        <h2>Remote Access to MBeans</h2>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   328
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   329
        <p>An MBean Server can be accessed remotely through a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   330
            <em>connector</em>.  A connector allows a remote Java
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   331
            application to access an MBean Server in essentially the same
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   332
            way as a local one.  The package
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   333
            <a href="remote/package-summary.html"><code>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   334
        javax.management.remote</code></a> defines connectors.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   335
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   336
        <p>The JMX specification also defines the notion of an
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   337
            <em>adaptor</em>.  An adaptor translates between requests in a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   338
            protocol such as SNMP or HTML and accesses to an MBean Server.
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   339
            So for example an SNMP GET operation might result in a
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   340
        <code>getAttribute</code> on the MBean Server.</p>
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   341
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   342
	<h3 id="interop">Interoperability between versions of the JMX
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   343
	  specification</h3>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   344
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   345
        <p>When a client connects to a server using the JMX Remote
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   346
            API, it is possible that they do not have the same version
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   347
            of the JMX specification.  The version of the JMX
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   348
            specification described here is version 1.4.  Previous
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   349
            versions were 1.0, 1.1, and 1.2.  (There was no 1.3.)
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   350
            The standard JMX Remote API is defined to work with version
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   351
            1.2 onwards, so in standards-based deployment the only
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   352
            interoperability questions that arise concern version 1.2
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   353
        onwards.</p>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   354
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   355
        <p>Every version of the JMX specification continues to
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   356
            implement the features of previous versions.  So when the
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   357
            client is running an earlier version than the server, there
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   358
            should not be any interoperability concerns.</p>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   359
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   360
        <p>When the client is running a later version than the server,
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   361
            certain newer features may not be available, as detailed in
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   362
            the next sections.  The client can determine the server's
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   363
            version by examining the {@link
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   364
            javax.management.MBeanServerDelegateMBean#getSpecificationVersion
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   365
            SpecificationVersion} attribute of the {@code
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   366
        MBeanServerDelegate}.</p>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   367
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   368
        <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   369
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   370
	<ul>
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   371
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   372
            <li><p>You cannot use wildcards in a key property of an
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   373
                {@link javax.management.ObjectName ObjectName}, for
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   374
                example {@code domain:type=Foo,name=*}. Wildcards that
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   375
                match whole properties are still allowed, for example
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   376
            {@code *:*} or {@code *:type=Foo,*}.</p>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   377
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   378
            <li><p>You cannot use {@link
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   379
                javax.management.Query#isInstanceOf Query.isInstanceOf}
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   380
            in a query.</p>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   381
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   382
            <li><p>You cannot use dot syntax such as {@code
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   383
                HeapMemoryUsage.used} in the {@linkplain
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   384
                javax.management.monitor.Monitor#setObservedAttribute
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   385
                observed attribute} of a monitor, as described in the
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   386
                documentation for the {@link javax.management.monitor}
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   387
            package.</p>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   388
4156
acaa49a2768a 6851617: Remove JSR 255 (JMX API 2.0) from JDK 7
emcmanus
parents: 1571
diff changeset
   389
        </ul>
1571
421ef5172dd3 6336968: Methods to convert AttributeList to/from Map
emcmanus
parents: 833
diff changeset
   390
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   391
        <p id="spec">
46050
f51c14dc540f 8181895: javax management docs contain links to technotes
uvangapally
parents: 30678
diff changeset
   392
        @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
f51c14dc540f 8181895: javax management docs contain links to technotes
uvangapally
parents: 30678
diff changeset
   393
        JMX Specification, version 1.4</a>
833
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   394
bfa2bef7517c 6323980: Annotations to simplify MBean development
emcmanus
parents: 2
diff changeset
   395
        @since 1.5
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   396
90ce3da70b43 Initial load
duke
parents:
diff changeset
   397
    </body>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   398
</html>