<html>
<head>
<title>JMX™ 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>