Skip to content

D
dragonwell8_jdk

openanolis / dragonwell8_jdk

通知 4
Star 2
Fork 0
D
dragonwell8_jdk
切换分支/标签
查找文件 普通视图历史永久链接Permalink
package.html 17.8 KB
Newer Older
D
Initial load  
duke 已提交
1 
<html>
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
2 3 4 
    <head>
        <title>javax.management package</title>
        <!--
O
6943119: Rebrand source copyright notices  
ohair 已提交
5 
Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
D
Initial load  
duke 已提交
6 7 8 9 
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
O
6943119: Rebrand source copyright notices  
ohair 已提交
10 
published by the Free Software Foundation.  Oracle designates this
D
Initial load  
duke 已提交
11 
particular file as subject to the "Classpath" exception as provided
O
6943119: Rebrand source copyright notices  
ohair 已提交
12 
by Oracle in the LICENSE file that accompanied this code.
D
Initial load  
duke 已提交
13 14 15 16 17 18 19 20 21 22 23 

This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).

You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
O
6956202: Fix a few missed rebranding issues, please contact lines etc.  
ohair 已提交
24 25 26 
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
27 28 29 30 
        -->
    </head>
    <body bgcolor="white">
        <p>Provides the core classes for the Java Management Extensions.</p>
D
Initial load  
duke 已提交
31
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
32 33 34 
        <p>The Java Management Extensions
            (JMX<sup><font size="-1">TM</font></sup>) API is a standard
        API for management and monitoring.  Typical uses include:</p>
D
Initial load  
duke 已提交
35
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
36 37 
        <ul>
            <li>consulting and changing application configuration</li>
D
Initial load  
duke 已提交
38
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
39 40 
            <li>accumulating statistics about application behavior and
            making them available</li>
D
Initial load  
duke 已提交
41
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
42 43 
            <li>notifying of state changes and erroneous conditions.</li>
        </ul>
D
Initial load  
duke 已提交
44
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
45 46 
        <p>The JMX API can also be used as part of a solution for
        managing systems, networks, and so on.</p>
D
Initial load  
duke 已提交
47
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
48 49 50 
        <p>The API includes remote access, so a remote management
            program can interact with a running application for these
        purposes.</p>
D
Initial load  
duke 已提交
51
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
52 
        <h2>MBeans</h2>
D
Initial load  
duke 已提交
53
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
54 55 56 57 
        <p>The fundamental notion of the JMX API is the <em>MBean</em>.
            An MBean is a named <em>managed object</em> representing a
            resource.  It has a <em>management interface</em> consisting
        of:</p>
D
Initial load  
duke 已提交
58
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
59 60 61 
        <ul>
            <li>named and typed attributes that can be read and/or
            written</li>
D
Initial load  
duke 已提交
62
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
63 
            <li>named and typed operations that can be invoked</li>
D
Initial load  
duke 已提交
64
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
65 66 
            <li>typed notifications that can be emitted by the MBean.</li>
        </ul>
D
Initial load  
duke 已提交
67
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
68 69 70 71 72 73 74 75 76 77 
        <p>For example, an MBean representing an application's
            configuration could have attributes representing the different
            configuration items.  Reading the <code>CacheSize</code>
            attribute would return the current value of that item.
            Writing it would update the item, potentially changing the
            behavior of the running application.  An operation such as
            <code>save</code> could store the current configuration
            persistently.  A notification such as
            <code>ConfigurationChangedNotification</code> could be sent
        every time the configuration is changed.</p>
D
Initial load  
duke 已提交
78
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
79 80 81 
        <p>In the standard usage of the JMX API, MBeans are implemented
            as Java objects.  However, as explained below, these objects are
        not usually referenced directly.</p>
D
Initial load  
duke 已提交
82 83
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
84 
        <h3>Standard MBeans</h3>
D
Initial load  
duke 已提交
85
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
86 87 88 89 90 91 92 93 
        <p>To make MBean implementation simple, the JMX API includes the
            notion of <em>Standard MBeans</em>.  A Standard MBean is one
            whose attributes and operations are deduced from a Java
            interface using certain naming patterns, similar to those used
            by JavaBeans<sup><font size="-1">TM</font></sup>.  For
        example, consider an interface like this:</p>

        <pre>
D
Initial load  
duke 已提交
94 
    public interface ConfigurationMBean {
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
95 96 97 98 
         public int getCacheSize();
         public void setCacheSize(int size);
         public long getLastChangedTime();
         public void save();
D
Initial load  
duke 已提交
99 
    }
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
100 
        </pre>
D
Initial load  
duke 已提交
101
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
102 103 104 105 
        <p>The methods <code>getCacheSize</code> and
            <code>setCacheSize</code> define a read-write attribute of
            type <code>int</code> called <code>CacheSize</code> (with an
        initial capital, unlike the JavaBeans convention).</p>
D
Initial load  
duke 已提交
106
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
107 108 109 110 
        <p>The method <code>getLastChangedTime</code> defines an
            attribute of type <code>long</code> called
            <code>LastChangedTime</code>.  This is a read-only attribute,
        since there is no method <code>setLastChangedTime</code>.</p>
D
Initial load  
duke 已提交
111
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
112 113 114 115 
        <p>The method <code>save</code> defines an operation called
            <code>save</code>.  It is not an attribute, since its name
            does not begin with <code>get</code>, <code>set</code>, or
        <code>is</code>.</p>
D
Initial load  
duke 已提交
116
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
117 118 
        <p>The exact naming patterns for Standard MBeans are detailed in
        the <a href="#spec">JMX Specification</a>.</p>
D
Initial load  
duke 已提交
119
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
120 121 122 123 124 125 126 127 128 
        <p>There are two ways to make a Java object that is an MBean
            with this management interface.  One is for the object to be
            of a class that has exactly the same name as the Java
            interface but without the <code>MBean</code> suffix.  So in
            the example the object would be of the class
            <code>Configuration</code>, in the same Java package as
            <code>ConfigurationMBean</code>.  The second way is to use the
            {@link javax.management.StandardMBean StandardMBean}
        class.</p>
D
Initial load  
duke 已提交
129 130
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 
        <h3>MXBeans</h3>

        <p>An <em>MXBean</em> is a variant of Standard MBean where complex
            types are mapped to a standard set of types defined in the
            {@link javax.management.openmbean} package.  MXBeans are appropriate
            if you would otherwise need to reference application-specific
            classes in your MBean interface.  They are described in detail
        in the specification for {@link javax.management.MXBean MXBean}.</p>


        <h3>Dynamic MBeans</h3>

        <p>A <em>Dynamic MBean</em> is an MBean that defines its
            management interface at run-time.  For example, a configuration
            MBean could determine the names and types of the attributes it
        exposes by parsing an XML file.</p>

        <p>Any Java object of a class that implements the {@link
            javax.management.DynamicMBean DynamicMBean} interface is a
        Dynamic MBean.</p>


        <h3>Open MBeans</h3>

        <p>An <em>Open MBean</em> is a kind of Dynamic MBean where the
            types of attributes and of operation parameters and return
            values are built using a small set of predefined Java classes.
            Open MBeans facilitate operation with remote management programs
            that do not necessarily have access to application-specific
            types, including non-Java programs.  Open MBeans are defined by
            the package <a href="openmbean/package-summary.html"><code>
        javax.management.openmbean</code></a>.</p>


        <h3>Model MBeans</h3>

        <p>A <em>Model MBean</em> is a kind of Dynamic MBean that acts
            as a bridge between the management interface and the
            underlying managed resource.  Both the management interface and
            the managed resource are specified as Java objects.  The same
            Model MBean implementation can be reused many times with
            different management interfaces and managed resources, and it can
            provide common functionality such as persistence and caching.
            Model MBeans are defined by the package
            <a href="modelmbean/package-summary.html"><code>
        javax.management.modelmbean</code></a>.</p>


        <h2>MBean Server</h2>

        <p>To be useful, an MBean must be registered in an <em>MBean
            Server</em>.  An MBean Server is a repository of MBeans.
            Usually the only access to the MBeans is through the MBean
            Server.  In other words, code no longer accesses the Java
            object implementing the MBean directly, but instead accesses
            the MBean by name through the MBean Server.  Each MBean has a
            unique name within the MBean Server, defined by the {@link
        javax.management.ObjectName ObjectName} class.</p>

        <p>An MBean Server is an object implementing the interface
            {@link javax.management.MBeanServer MBeanServer}.
            The most convenient MBean Server to use is the
            <em>Platform MBean Server</em>.  This is a
            single MBean Server that can be shared by different managed
            components running within the same Java Virtual Machine.  The
            Platform MBean Server is accessed with the method {@link
        java.lang.management.ManagementFactory#getPlatformMBeanServer()}.</p>

        <p>Application code can also create a new MBean Server, or
            access already-created MBean Servers, using the {@link
        javax.management.MBeanServerFactory MBeanServerFactory} class.</p>


        <h3>Creating MBeans in the MBean Server</h3>

        <p>There are two ways to create an MBean.  One is to construct a
            Java object that will be the MBean, then use the {@link
            javax.management.MBeanServer#registerMBean registerMBean}
            method to register it in the MBean Server.  The other is to
            create and register the MBean in a single operation using one
            of the {@link javax.management.MBeanServer#createMBean(String,
        javax.management.ObjectName) createMBean} methods.</p>

        <p>The <code>registerMBean</code> method is simpler for local
            use, but cannot be used remotely.  The
            <code>createMBean</code> method can be used remotely, but
        sometimes requires attention to class loading issues.</p>

        <p>An MBean can perform actions when it is registered in or
            unregistered from an MBean Server if it implements the {@link
            javax.management.MBeanRegistration MBeanRegistration}
        interface.</p>


        <h3>Accessing MBeans in the MBean Server</h3>

        <p>Given an <code>ObjectName</code> <code>name</code> and an
            <code>MBeanServer</code> <code>mbs</code>, you can access
        attributes and operations as in this example:</p>

        <pre>
D
Initial load  
duke 已提交
232 233 
    int cacheSize = mbs.getAttribute(name, "CacheSize");
    {@link javax.management.Attribute Attribute} newCacheSize =
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
234 
         new Attribute("CacheSize", new Integer(2000));
D
Initial load  
duke 已提交
235 236 
    mbs.setAttribute(name, newCacheSize);
    mbs.invoke(name, "save", new Object[0], new Class[0]);
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
237 
        </pre>
D
Initial load  
duke 已提交
238
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
239 240 241 
        <p id="proxy">Alternatively, if you have a Java interface that
            corresponds to the management interface for the MBean, you can use an
        <em>MBean proxy</em> like this:</p>
D
Initial load  
duke 已提交
242
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
243 
        <pre>
D
Initial load  
duke 已提交
244 245 246 247 248 249 
    ConfigurationMBean conf =
        {@link javax.management.JMX#newMBeanProxy
            JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
    int cacheSize = conf.getCacheSize();
    conf.setCacheSize(2000);
    conf.save();
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
250 
        </pre>
D
Initial load  
duke 已提交
251
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
252 253 254 
        <p>Using an MBean proxy is just a convenience.  The second
            example ends up calling the same <code>MBeanServer</code>
        operations as the first one.</p>
D
Initial load  
duke 已提交
255
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
256 257 258 259 260 261 262 263 264 
        <p>An MBean Server can be queried for MBeans whose names match
            certain patterns and/or whose attributes meet certain
            constraints.  Name patterns are constructed using the {@link
            javax.management.ObjectName ObjectName} class and constraints
            are constructed using the {@link javax.management.Query Query}
            class.  The methods {@link
            javax.management.MBeanServer#queryNames queryNames} and {@link
            javax.management.MBeanServer#queryMBeans queryMBeans} then
        perform the query.</p>
D
Initial load  
duke 已提交
265 266
E
6851617: Remove JSR 255 (JMX API 2.0) from JDK 7  
emcmanus 已提交
267 
        <h3>MBean lifecycle</h3>
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 

        <p>An MBean can implement the {@link javax.management.MBeanRegistration
            MBeanRegistration} interface in order to be told when it is registered
            and unregistered in the MBean Server. Additionally, the {@link
            javax.management.MBeanRegistration#preRegister preRegister} method
            allows the MBean to get a reference to the <code>MBeanServer</code>
            object and to get its <code>ObjectName</code> within the MBean
        Server.</p>


        <h2>Notifications</h2>

        <p>A <em>notification</em> is an instance of the {@link
            javax.management.Notification Notification} class or a
            subclass.  In addition to its Java class, it has a
            <em>type</em> string that can distinguish it from other
        notifications of the same class.</p>
E
6851617: Remove JSR 255 (JMX API 2.0) from JDK 7  
emcmanus 已提交
286 287 288 289 290 291 292 293 
        <p>An MBean that will emit notifications must implement the
            {@link javax.management.NotificationBroadcaster
            NotificationBroadcaster} or {@link
            javax.management.NotificationEmitter NotificationEmitter}
            interface.  Usually, it does this by subclassing
            {@link javax.management.NotificationBroadcasterSupport
            NotificationBroadcasterSupport} or delegating to an instance of
        that class. Here is an example:</p>
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 

        <pre>
    public class Configuration <b>extends NotificationBroadcasterSupport</b>
            implements ConfigurationMBean {
        ...
        private void updated() {
            Notification n = new Notification(...);
            <b>{@link javax.management.NotificationBroadcasterSupport#sendNotification
            sendNotification}(n)</b>;
        }
    }
        </pre>


        <p>Notifications can be received by a <em>listener</em>, which
            is an object that implements the {@link
            javax.management.NotificationListener NotificationListener}
            interface.  You can add a listener to an MBean with the method
            {@link
            javax.management.MBeanServer#addNotificationListener(ObjectName,
            NotificationListener, NotificationFilter, Object)}.
            You can optionally supply a <em>filter</em> to this method, to
            select only notifications of interest.  A filter is an object
            that implements the {@link javax.management.NotificationFilter
        NotificationFilter} interface.</p>

        <p>An MBean can be a listener for notifications emitted by other
            MBeans in the same MBean Server.  In this case, it implements
            {@link javax.management.NotificationListener
            NotificationListener} and the method {@link
            javax.management.MBeanServer#addNotificationListener(ObjectName,
        ObjectName, NotificationFilter, Object)} is used to listen.</p>


        <h2>Remote Access to MBeans</h2>

        <p>An MBean Server can be accessed remotely through a
            <em>connector</em>.  A connector allows a remote Java
            application to access an MBean Server in essentially the same
            way as a local one.  The package
            <a href="remote/package-summary.html"><code>
        javax.management.remote</code></a> defines connectors.</p>

        <p>The JMX specification also defines the notion of an
            <em>adaptor</em>.  An adaptor translates between requests in a
            protocol such as SNMP or HTML and accesses to an MBean Server.
            So for example an SNMP GET operation might result in a
        <code>getAttribute</code> on the MBean Server.</p>
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
343 344 345 
	<h3 id="interop">Interoperability between versions of the JMX
	  specification</h3>
E
6851617: Remove JSR 255 (JMX API 2.0) from JDK 7  
emcmanus 已提交
346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 
        <p>When a client connects to a server using the JMX Remote
            API, it is possible that they do not have the same version
            of the JMX specification.  The version of the JMX
            specification described here is version 1.4.  Previous
            versions were 1.0, 1.1, and 1.2.  (There was no 1.3.)
            The standard JMX Remote API is defined to work with version
            1.2 onwards, so in standards-based deployment the only
            interoperability questions that arise concern version 1.2
        onwards.</p>

        <p>Every version of the JMX specification continues to
            implement the features of previous versions.  So when the
            client is running an earlier version than the server, there
            should not be any interoperability concerns.</p>

        <p>When the client is running a later version than the server,
            certain newer features may not be available, as detailed in
            the next sections.  The client can determine the server's
            version by examining the {@link
            javax.management.MBeanServerDelegateMBean#getSpecificationVersion
            SpecificationVersion} attribute of the {@code
        MBeanServerDelegate}.</p>

        <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4>
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
370 371 372 

	<ul>
E
6851617: Remove JSR 255 (JMX API 2.0) from JDK 7  
emcmanus 已提交
373 374 375 376 377 
            <li><p>You cannot use wildcards in a key property of an
                {@link javax.management.ObjectName ObjectName}, for
                example {@code domain:type=Foo,name=*}. Wildcards that
                match whole properties are still allowed, for example
            {@code *:*} or {@code *:type=Foo,*}.</p>
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
378
E
6851617: Remove JSR 255 (JMX API 2.0) from JDK 7  
emcmanus 已提交
379 380 381 
            <li><p>You cannot use {@link
                javax.management.Query#isInstanceOf Query.isInstanceOf}
            in a query.</p>
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
382
E
6851617: Remove JSR 255 (JMX API 2.0) from JDK 7  
emcmanus 已提交
383 384 385 386 387 388 
            <li><p>You cannot use dot syntax such as {@code
                HeapMemoryUsage.used} in the {@linkplain
                javax.management.monitor.Monitor#setObservedAttribute
                observed attribute} of a monitor, as described in the
                documentation for the {@link javax.management.monitor}
            package.</p>
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
389
E
6851617: Remove JSR 255 (JMX API 2.0) from JDK 7  
emcmanus 已提交
390 
        </ul>
E
6336968: Methods to convert AttributeList to/from Map  
emcmanus 已提交
391
E
6323980: Annotations to simplify MBean development  
emcmanus 已提交
392 393 394 395 396 397 398 399 
        <p id="spec">
        @see <a href="{@docRoot}/../technotes/guides/jmx/index.html">
        Java SE 6 Platform documentation on JMX technology</a>
        in particular the
        <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
        JMX Specification, version 1.4(pdf).</a>

        @since 1.5
D
Initial load  
duke 已提交
400 401 402 

    </body>
</html>