| 1 |
772 |
jeremybenn |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
| 2 |
|
|
<!-- package.html - describes classes in javax.management package.
|
| 3 |
|
|
Copyright (C) 2007 Free Software Foundation, Inc.
|
| 4 |
|
|
|
| 5 |
|
|
This file is part of GNU Classpath.
|
| 6 |
|
|
|
| 7 |
|
|
GNU Classpath is free software; you can redistribute it and/or modify
|
| 8 |
|
|
it under the terms of the GNU General Public License as published by
|
| 9 |
|
|
the Free Software Foundation; either version 2, or (at your option)
|
| 10 |
|
|
any later version.
|
| 11 |
|
|
|
| 12 |
|
|
GNU Classpath is distributed in the hope that it will be useful, but
|
| 13 |
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
| 14 |
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
| 15 |
|
|
General Public License for more details.
|
| 16 |
|
|
|
| 17 |
|
|
You should have received a copy of the GNU General Public License
|
| 18 |
|
|
along with GNU Classpath; see the file COPYING. If not, write to the
|
| 19 |
|
|
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
| 20 |
|
|
02110-1301 USA.
|
| 21 |
|
|
|
| 22 |
|
|
Linking this library statically or dynamically with other modules is
|
| 23 |
|
|
making a combined work based on this library. Thus, the terms and
|
| 24 |
|
|
conditions of the GNU General Public License cover the whole
|
| 25 |
|
|
combination.
|
| 26 |
|
|
|
| 27 |
|
|
As a special exception, the copyright holders of this library give you
|
| 28 |
|
|
permission to link this library with independent modules to produce an
|
| 29 |
|
|
executable, regardless of the license terms of these independent
|
| 30 |
|
|
modules, and to copy and distribute the resulting executable under
|
| 31 |
|
|
terms of your choice, provided that you also meet, for each linked
|
| 32 |
|
|
independent module, the terms and conditions of the license of that
|
| 33 |
|
|
module. An independent module is a module which is not derived from
|
| 34 |
|
|
or based on this library. If you modify this library, you may extend
|
| 35 |
|
|
this exception to your version of the library, but you are not
|
| 36 |
|
|
obligated to do so. If you do not wish to do so, delete this
|
| 37 |
|
|
exception statement from your version. -->
|
| 38 |
|
|
|
| 39 |
|
|
<html>
|
| 40 |
|
|
<head><title>GNU Classpath - javax.management</title></head>
|
| 41 |
|
|
|
| 42 |
|
|
<body>
|
| 43 |
|
|
|
| 44 |
|
|
<p>
|
| 45 |
|
|
Provides the core classes for the Java Management Extensions (JMX). This API
|
| 46 |
|
|
builds on the notion of Java beans by providing a layer of abstraction between
|
| 47 |
|
|
the beans themselves and the method of accessing them. Instead of being accessed
|
| 48 |
|
|
directly, management beans or <strong>MBeans</strong> are usually accessed via
|
| 49 |
|
|
a management server (an implementation of the @see MBeanServer interface). Thus,
|
| 50 |
|
|
the bean itself may be a simple Java object or it may be something
|
| 51 |
|
|
more complicated (for example, the server may map from Java to SNMP). The server may
|
| 52 |
|
|
also retrieve the bean from some remote location rather than using a local object.
|
| 53 |
|
|
</p>
|
| 54 |
|
|
<p>
|
| 55 |
|
|
Management beans are usually used for monitoring and/or configuration
|
| 56 |
|
|
of a particular entity. For example, the platform management beans
|
| 57 |
|
|
found in the @see java.lang.management package allow the user
|
| 58 |
|
|
to obtain information about the operating system, current memory usage, etc.
|
| 59 |
|
|
as well as turning on and off certain additional facilities. To this end,
|
| 60 |
|
|
an MBean consists of:
|
| 61 |
|
|
</p>
|
| 62 |
|
|
<ul>
|
| 63 |
|
|
<li><emph>attributes</emph> that may be read and/or written to.</li>
|
| 64 |
|
|
<li><emph>operations</emph> which may be performed.</li>
|
| 65 |
|
|
<li><emph>notifications</emph> that may emitted by the bean and listened for by users.</li>
|
| 66 |
|
|
</ul>
|
| 67 |
|
|
<p>
|
| 68 |
|
|
The most common type of management bean is the @see StandardMBean, A standard MBean
|
| 69 |
|
|
relies on the naming patterns established by the JavaBeans framework; the value of an
|
| 70 |
|
|
attribute <code>name</code> is retrieved by an accessor method named <code>getName</code>
|
| 71 |
|
|
and changed by a mutator method called <code>setName</code>. If the mutator is absent,
|
| 72 |
|
|
the attribute is read only. Naming is also used to associate the implementation of a
|
| 73 |
|
|
bean with its interface; an bean <code>Person</code> is assumed to be an implementation
|
| 74 |
|
|
of the interface <code>PersonMBean</code> (and vice versa). To avoid these naming constraints,
|
| 75 |
|
|
the @see StandardMBean class may be used.
|
| 76 |
|
|
</p>
|
| 77 |
|
|
<p>
|
| 78 |
|
|
<h2>Types of Beans</h2>
|
| 79 |
|
|
<p>
|
| 80 |
|
|
The @see StandardMBean class is one example of a @see DynamicMBean where the attributes and
|
| 81 |
|
|
operations of the bean are provided dynamically via the methods provided. With the
|
| 82 |
|
|
@see StandardMBean class, this simply means that the class uses reflection to access the
|
| 83 |
|
|
appropriate methods of the bean implementation. In a more complex scenario, the bean's
|
| 84 |
|
|
data could be supplied from a file or over the network.
|
| 85 |
|
|
</p>
|
| 86 |
|
|
<p>
|
| 87 |
|
|
Once we start talking about accessing beans over network and platform boundaries, we run
|
| 88 |
|
|
in to the issue of how to deal with the types utilised by these beans. Simple types, such
|
| 89 |
|
|
as numbers and strings, are usually fine but more complex types need special treatment.
|
| 90 |
|
|
An <emph>Open MBean</emph> is one that only uses a specific set of types defined in the
|
| 91 |
|
|
@see javax.management.openmbean package, allowing both sides of a remote connection to provide
|
| 92 |
|
|
this subset of types and thus interact. An @see MXBean goes a stage further, and defines
|
| 93 |
|
|
a method whereby a normal Java MBean may become an Open MBean by performing a defined mapping
|
| 94 |
|
|
on the types of the bean. For example, a @see java.util.List or @see java.util.Set of a
|
| 95 |
|
|
particular type becomes an array of the same type.
|
| 96 |
|
|
</p>
|
| 97 |
|
|
<h2>Accessing Beans</h2>
|
| 98 |
|
|
<p>
|
| 99 |
|
|
Although beans can be accessed like normal objects, the normal way of accessing them is
|
| 100 |
|
|
via an @see MBeanServer. This provides the abstraction from the bean's implementation to
|
| 101 |
|
|
a set of attributes, operations and notifications. The server identifies each bean via
|
| 102 |
|
|
an @see ObjectName. This name is unique to a particular bean and is used to identify the
|
| 103 |
|
|
bean when retrieving the value of an attribute or invoking an operation. Essentially, most
|
| 104 |
|
|
methods provided by the server are the same as those provided by the @see DynamicMBean
|
| 105 |
|
|
interface, except that each takes this additional @link ObjectName parameter to identify the
|
| 106 |
|
|
bean being accessed.
|
| 107 |
|
|
</p>
|
| 108 |
|
|
<p>
|
| 109 |
|
|
The @see MBeanServerFactory keeps track of the current MBean servers in use and allows new
|
| 110 |
|
|
ones to be created. A special @see MBeanServer instance, called the <emph>platform MBean
|
| 111 |
|
|
server</emph>, is created when the Java virtual machine is started and a reference to this
|
| 112 |
|
|
may be obtained from the @see ManagementFactory using
|
| 113 |
|
|
@see ManagementFactory#getPlatformMBeanServer(). This primarily exists for the purpose of
|
| 114 |
|
|
creating and registering the platform MBeans, described in @see java.lang.management, which
|
| 115 |
|
|
provide access to information about the underlying operating system, memory usage, the behaviour
|
| 116 |
|
|
of the garbage collector, etc. but is equally suitable for creating and registering your own
|
| 117 |
|
|
beans. Alternatively, a server instance may be obtained from the @see MBeanServerFactory.
|
| 118 |
|
|
</p>
|
| 119 |
|
|
<p>
|
| 120 |
|
|
A bean obtains an @link ObjectName by registering with the server. This operation can be
|
| 121 |
|
|
performed either by passing an existing instance to the @see MBeanServer#registerMBean method
|
| 122 |
|
|
or by using the @see MBeanServer#createMBean method to simultaneously create the bean and
|
| 123 |
|
|
register it with the server. During the registration process, the bean may perform some
|
| 124 |
|
|
arbitrary behaviour if it implements the @link MBeanRegistration interface. The same is
|
| 125 |
|
|
true when unregistering a bean.
|
| 126 |
|
|
</p>
|
| 127 |
|
|
<p>
|
| 128 |
|
|
To actually access the attributes and operations of a bean via the server, we use code
|
| 129 |
|
|
like the following:
|
| 130 |
|
|
</p>
|
| 131 |
|
|
<pre>
|
| 132 |
|
|
// First we obtain the platform MBean server which has the platform MBeans registered
|
| 133 |
|
|
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
|
| 134 |
|
|
// We also need the object name of the memory bean so we can address it
|
| 135 |
|
|
ObjectName name = new ObjectName(ManagementFactory.MEMORY_MXBEAN_NAME);
|
| 136 |
|
|
// Next we obtain the value of the 'verbose' attribute
|
| 137 |
|
|
// What actually happens here is that the server invokes the 'isVerbose' method of
|
| 138 |
|
|
// the MemoryMXBean
|
| 139 |
|
|
boolean verbose = server.getAttribute(name, "verbose");
|
| 140 |
|
|
// We can also set the value of verbose. Again the server is actually performing
|
| 141 |
|
|
// a setVerbose(val) on the bean but we don't need to know this.
|
| 142 |
|
|
Attribute attrib = new Attribute("verbose", true);
|
| 143 |
|
|
server.setAttribute(name, attrib);
|
| 144 |
|
|
// We can also invoke the 'gc' operation which calls the garbage collector.
|
| 145 |
|
|
server.invoke(name, "gc", new Object[]{}, new String[]{});
|
| 146 |
|
|
</pre>
|
| 147 |
|
|
<p>
|
| 148 |
|
|
As noted above, the server is simply making basic method calls on the object using
|
| 149 |
|
|
reflection. However, the server provides a layer of abstraction which means that something
|
| 150 |
|
|
more complicated could actually be going on. The lines above are equally applicable, for
|
| 151 |
|
|
example, if <code>server</code> is instead an @see MBeanServerConnection connecting us
|
| 152 |
|
|
to a distant computer.
|
| 153 |
|
|
</p>
|
| 154 |
|
|
<p>
|
| 155 |
|
|
This rather hideous code can be simplified back into simple method calls on an object,
|
| 156 |
|
|
so that we get the best of both worlds. This is achieved using a <emph>MBean proxy</emph>:
|
| 157 |
|
|
<pre>
|
| 158 |
|
|
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
|
| 159 |
|
|
ObjectName name = new ObjectName(ManagementFactory.MEMORY_MXBEAN_NAME);
|
| 160 |
|
|
MemoryMXBean bean = JMX.newMBeanProxy(server, name, MemoryMXBean.class);
|
| 161 |
|
|
boolean verbose = bean.isVerbose();
|
| 162 |
|
|
bean.setVerbose(true);
|
| 163 |
|
|
bean.gc();
|
| 164 |
|
|
</pre>
|
| 165 |
|
|
<p>
|
| 166 |
|
|
See how much simpler the operations are? The proxy handles the task of translating the method
|
| 167 |
|
|
calls into appropriate invocations of methods on the server, simplifying the code for the user.
|
| 168 |
|
|
</p>
|
| 169 |
|
|
<p>
|
| 170 |
|
|
Finally, we have assumed in the code above that the @see ObjectName of the bean is known.
|
| 171 |
|
|
If this is not the case, then the server's database can be searched. The @see Query class
|
| 172 |
|
|
provides appropriate operators (e.g. boolean (and,or), value comparison (>, <)) for
|
| 173 |
|
|
building up relatively complex queries. Once constructed, a query may be passed to either
|
| 174 |
|
|
the @see MBeanServer#queryNames or @see MBeanServer#queryMBeans to obtain an appropriate
|
| 175 |
|
|
set of @see ObjectName or MBean instances.
|
| 176 |
|
|
</p>
|
| 177 |
|
|
<h2>Notifications</h2>
|
| 178 |
|
|
<p>
|
| 179 |
|
|
MBeans also have the capability to emit events. Beans which do so implement either the
|
| 180 |
|
|
@see NotificationBroadcaster or @see NotificationEmitter interface (the difference between
|
| 181 |
|
|
the two is simply the existence of a better removal method in the newer
|
| 182 |
|
|
@see NotificationEmitter interface, which otherwise extends @see NotificationBroadcaster),
|
| 183 |
|
|
usually by extending the @see NotificationBroadcasterSupport class. As is usual with event
|
| 184 |
|
|
handling, other classes may <emph>signup</emph> to receive events via the
|
| 185 |
|
|
@see NotificationListener interface. The signup process can include registering a filter
|
| 186 |
|
|
(an implementation of @see NotificationFilter) so that only certain events reach the
|
| 187 |
|
|
listener and others are discarded.
|
| 188 |
|
|
</p>
|
| 189 |
|
|
<h2>Remote Access</h2>
|
| 190 |
|
|
<p>
|
| 191 |
|
|
The subpackage @see javax.management.remote provides facilities to access remote MBean
|
| 192 |
|
|
servers. This consists of a <emph>connector</emph> framework which abstracts the method
|
| 193 |
|
|
of accessing remote servers from the actual implementation, so that the same method is
|
| 194 |
|
|
used to connect to a remote server, regardless of how it is accessed.
|
| 195 |
|
|
</p>
|
| 196 |
|
|
</body>
|
| 197 |
|
|
</html>
|
