1 files changed, 197 insertions, 0 deletions
diff --git a/libjava/classpath/javax/management/package.html b/libjava/classpath/javax/management/package.html
new file mode 100644
index 000000000..3543eec90
--- /dev/null
+++ b/libjava/classpath/javax/management/package.html
@@ -0,0 +1,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 (&gt;, &lt;)) 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>