--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.management/share/classes/javax/management/remote/package.html Sun Aug 17 15:54:13 2014 +0100
@@ -0,0 +1,206 @@
+<html>
+<head>
+ <title>JMX<sup><font size="-2">TM</font></sup> Remote API.</title>
+<!--
+Copyright (c) 2002, 2014, Oracle and/or its affiliates. All rights reserved.
+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
+published by the Free Software Foundation. Oracle designates this
+particular file as subject to the "Classpath" exception as provided
+by Oracle in the LICENSE file that accompanied this code.
+
+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.
+
+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.
+-->
+</head>
+<body bgcolor="white">
+ <p>Interfaces for remote access to
+ JMX MBean servers.
+ This package defines the essential interfaces for making a JMX
+ MBean server manageable remotely. The specification of this
+ functionality is completed by Part III of the
+ <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
+ JMX Specification, version 1.4</a> PDF document.</p>
+
+ <p>The JMX specification defines the notion of <b>connectors</b>.
+ A connector is attached to a JMX API MBean server and makes it
+ accessible to remote Java clients. The client end of a
+ connector exports essentially the same interface as the MBean
+ server, specifically the {@link
+ javax.management.MBeanServerConnection MBeanServerConnection}
+ interface.</p>
+
+ <p>A connector makes an MBean server remotely accessible through
+ a given protocol. The JMX Remote API allows the use of different
+ type of connectors:
+
+ <ul>
+ <li>The JMX Remote API defines a standard connector,
+ the <b>RMI Connector</b>, which provides remote access to an
+ MBeanServer through RMI.
+
+ <li>The JMX Remote API also defines an optional connector called
+ <b>JMXMP Connector</b> implementing the JMX Message Protocol
+ (JMXMP). As it is optional, it is not part of this bundle (see
+ note below).
+
+ <li>User-defined connector protocols are also possible using the
+ {@link javax.management.remote.JMXConnectorFactory
+ JMXConnectorFactory} and, optionally, the Generic Connector
+ (not part of this bundle, see note below).
+ </ul>
+
+ <p><u>Note</u>: the optional packages implementing
+ the optional part of the <em>JMX Remote API</em>
+ are not included in the <em>Java SE Platform</em>
+ but are available from the <em>JMX Remote API
+ <a href="http://java.sun.com/products/JavaManagement/download.html">
+ Reference Implementation</a></em>.</p>
+
+
+ <h3>Connector addresses</h3>
+
+ <p>Typically, a connector server has an address, represented by the
+ class {@link javax.management.remote.JMXServiceURL
+ JMXServiceURL}. An address for the RMI Connector can look
+ like this:</p>
+
+ <pre>
+ service:jmx:rmi:///jndi/rmi://myhost:1099/myname
+ </pre>
+
+ <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
+ specifies the RMI connector, while the second <code>rmi:</code>
+ specifies the RMI registry into which the RMI connector server
+ has stored its stub.
+
+ <p>The example above shows only one form of address.
+ An address for the RMI Connector can take several forms,
+ as detailed in the documentation for the package
+ <code>{@link javax.management.remote.rmi}</code>.</p>
+
+ <h3>Creating a connector server</h3>
+
+ <p>A connector server is created by constructing an instance of
+ a subclass of {@link
+ javax.management.remote.JMXConnectorServer
+ JMXConnectorServer}. Usually, this instance is created
+ using the method {@link
+ javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer(JMXServiceURL,
+ java.util.Map, javax.management.MBeanServer)
+ JMXConnectorServerFactory.newJMXConnectorServer}.</p>
+
+ <p>Typically, a connector server is associated with an MBean
+ server either by registering it in that MBean server, or by
+ supplying the MBean server as a parameter when creating the
+ connector server.</p>
+
+ <h3>Creating a connector client</h3>
+
+ <p>A connector client is usually created by supplying the
+ <code>JMXServiceURL</code> of the connector server to connect to
+ to the {@link
+ javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)
+ JMXConnectorFactory.connect} method.</p>
+
+ <p>For more specialized uses, a connector client can be created
+ by directly instantiating a class that implements the {@link
+ javax.management.remote.JMXConnector JMXConnector} interface,
+ for example the class {@link
+ javax.management.remote.rmi.RMIConnector
+ RMIConnector}.</p>
+
+ <h3>Additional client or server parameters</h3>
+
+ <p>When creating a connector client or server, it is possible to
+ supply an object of type {@link java.util.Map Map} that defines
+ additional parameters. Each entry in this Map has a key that is
+ a string and an associated value whose type is appropriate for
+ that key. The standard keys defined by the JMX Remote API all
+ begin with the string "<code>jmx.remote.</code>". The document
+ <em>JMX Remote API</em> lists these standard keys.</p>
+
+ <h3>Connection identifiers</h3>
+
+ <p>Every connection opened by a connector server has a string
+ identifier, called its <b>connection id</b>. This identifier
+ appears in the {@link
+ javax.management.remote.JMXConnectionNotification
+ JMXConnectionNotification} events emitted by the connector
+ server, in the list returned by {@link
+ javax.management.remote.JMXConnectorServerMBean#getConnectionIds()
+ getConnectionIds()}, and in the value
+ returned by the client's {@link
+ javax.management.remote.JMXConnector#getConnectionId()
+ getConnectionId()} method.</p>
+
+ <p>As an example, a connection ID can look something like this:</p>
+
+ <pre>
+rmi://192.18.1.9 username 1
+ </pre>
+
+ <p>The formal grammar for connection ids that follow this
+ convention is as follows (using the grammar notation from section 2.4 of
+ <em>The Java™ Language Specification</em>):</p>
+ <pre>
+<em>ConnectionId:</em>
+ <em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>
+
+<em>ClientAddress:</em>
+ // <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>
+
+<em>ClientPort</em>
+ : <em>HostPort</em>
+ </pre>
+
+ <p>The <code><em>Protocol</em></code> is a protocol that would
+ be recognized by {@link
+ javax.management.remote.JMXConnectorFactory
+ JMXConnectorFactory}.</p>
+
+ <p>The <code><em>ClientAddress</em></code> is the
+ address and port of the connecting client, if these can be
+ determined, otherwise nothing. The
+ <code><em>HostAddress</em></code> is the Internet address of
+ the host that the client is connecting from, in numeric or DNS
+ form. Numeric IPv6 addresses are enclosed in square brackets
+ <code>[]</code>. The <code><em>HostPort</em></code> is the
+ decimal port number that the client is connecting from.</p>
+
+ <p>The <code><em>ClientId</em></code> is the identity of the
+ client entity, typically a string returned by {@link
+ javax.management.remote.JMXPrincipal#getName()
+ JMXPrincipal.getName()}. This string must not contain
+ spaces.</p>
+
+ <p>The <code><em>ArbitraryText</em></code> is any additional
+ text that the connector server adds when creating the client id.
+ At a minimum, it must be enough to distinguish this connection
+ ID from the ID of any other connection currently opened by this
+ connector server.</p>
+
+
+ @see <a href="{@docRoot}/../technotes/guides/jmx/">
+ Java 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</a>
+
+ @since 1.5
+
+ </body>
+</html>