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