0N/A<html>
0N/A<head>
0N/A <title>JMX<sup><font size="-2">TM</font></sup> Remote API.</title>
0N/A<!--
4230N/ACopyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A
0N/AThis code is free software; you can redistribute it and/or modify it
0N/Aunder the terms of the GNU General Public License version 2 only, as
2362N/Apublished by the Free Software Foundation. Oracle designates this
0N/Aparticular file as subject to the "Classpath" exception as provided
2362N/Aby Oracle in the LICENSE file that accompanied this code.
0N/A
0N/AThis code is distributed in the hope that it will be useful, but WITHOUT
0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/Aversion 2 for more details (a copy is included in the LICENSE file that
0N/Aaccompanied this code).
0N/A
0N/AYou should have received a copy of the GNU General Public License version
0N/A2 along with this work; if not, write to the Free Software Foundation,
0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A
2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2365N/Aor visit www.oracle.com if you need additional information or have any
2365N/Aquestions.
0N/A-->
0N/A</head>
0N/A<body bgcolor="white">
0N/A <p>Interfaces for remote access to
0N/A JMX MBean servers.
0N/A This package defines the essential interfaces for making a JMX
0N/A MBean server manageable remotely. The specification of this
0N/A functionality is completed by Part III of the
0N/A <a href="{@docRoot}/technotes/guides/jmx/JMX_1_4_specification.pdf">
0N/A JMX Specification, version 1.4</a> PDF document.</p>
0N/A
0N/A <p>The JMX specification defines the notion of <b>connectors</b>.
0N/A A connector is attached to a JMX API MBean server and makes it
0N/A accessible to remote Java clients. The client end of a
0N/A connector exports essentially the same interface as the MBean
0N/A server, specifically the {@link
0N/A javax.management.MBeanServerConnection MBeanServerConnection}
0N/A interface.</p>
0N/A
0N/A <p>A connector makes an MBean server remotely accessible through
0N/A a given protocol. The JMX Remote API allows the use of different
0N/A type of connectors:
0N/A
0N/A <ul>
0N/A <li>The JMX Remote API defines a standard connector,
0N/A the <b>RMI Connector</b>, which provides remote access to an
0N/A MBeanServer through RMI.
0N/A
0N/A <li>The JMX Remote API also defines an optional connector called
0N/A <b>JMXMP Connector</b> implementing the JMX Message Protocol
0N/A (JMXMP). As it is optional, it is not part of this bundle (see
0N/A note below).
0N/A
0N/A <li>User-defined connector protocols are also possible using the
0N/A {@link javax.management.remote.JMXConnectorFactory
0N/A JMXConnectorFactory} and, optionally, the Generic Connector
0N/A (not part of this bundle, see note below).</p>
0N/A </ul>
0N/A
0N/A <p><u>Note</u>: the optional packages implementing
0N/A the optional part of the <em>JMX Remote API</em>
0N/A are not included in the <em>Java SE Platform</em>
0N/A but are available from the <em>JMX Remote API
0N/A <a href="http://java.sun.com/products/JavaManagement/download.html">
0N/A Reference Implementation</a></em>.</p>
0N/A
0N/A
0N/A <h3>Connector addresses</h3>
0N/A
0N/A <p>Typically, a connector server has an address, represented by the
0N/A class {@link javax.management.remote.JMXServiceURL
0N/A JMXServiceURL}. An address for the RMI Connector can look
0N/A like this:</p>
0N/A
0N/A <pre>
0N/A service:jmx:rmi:///jndi/rmi://myhost:1099/myname
0N/A </pre>
0N/A
0N/A <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
0N/A specifies the RMI connector, while the second <code>rmi:</code>
0N/A specifies the RMI registry into which the RMI connector server
0N/A has stored its stub.
0N/A
0N/A <p>The example above shows only one form of address.
0N/A An address for the RMI Connector can take several forms,
0N/A as detailed in the documentation for the package
0N/A <code>{@link javax.management.remote.rmi}</code>.</p>
0N/A
0N/A <h3>Creating a connector server</h3>
0N/A
0N/A <p>A connector server is created by constructing an instance of
0N/A a subclass of {@link
0N/A javax.management.remote.JMXConnectorServer
0N/A JMXConnectorServer}. Usually, this instance is created
0N/A using the method {@link
0N/A javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer(JMXServiceURL,
0N/A java.util.Map, javax.management.MBeanServer)
0N/A JMXConnectorServerFactory.newJMXConnectorServer}.</p>
0N/A
0N/A <p>Typically, a connector server is associated with an MBean
0N/A server either by registering it in that MBean server, or by
0N/A supplying the MBean server as a parameter when creating the
0N/A connector server.</p>
0N/A
0N/A <h3>Creating a connector client</h3>
0N/A
0N/A <p>A connector client is usually created by supplying the
0N/A <code>JMXServiceURL</code> of the connector server to connect to
0N/A to the {@link
0N/A javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)
0N/A JMXConnectorFactory.connect} method.</p>
0N/A
0N/A <p>For more specialized uses, a connector client can be created
0N/A by directly instantiating a class that implements the {@link
0N/A javax.management.remote.JMXConnector JMXConnector} interface,
0N/A for example the class {@link
0N/A javax.management.remote.rmi.RMIConnector
0N/A RMIConnector}.</p>
0N/A
0N/A <h3>Additional client or server parameters</h3>
0N/A
0N/A <p>When creating a connector client or server, it is possible to
0N/A supply an object of type {@link java.util.Map Map} that defines
0N/A additional parameters. Each entry in this Map has a key that is
0N/A a string and an associated value whose type is appropriate for
0N/A that key. The standard keys defined by the JMX Remote API all
0N/A begin with the string "<code>jmx.remote.</code>". The document
0N/A <em>JMX Remote API</em> lists these standard keys.</p>
0N/A
0N/A <h3>Connection identifiers</h3>
0N/A
0N/A <p>Every connection opened by a connector server has a string
0N/A identifier, called its <b>connection id</b>. This identifier
0N/A appears in the {@link
0N/A javax.management.remote.JMXConnectionNotification
0N/A JMXConnectionNotification} events emitted by the connector
0N/A server, in the list returned by {@link
0N/A javax.management.remote.JMXConnectorServerMBean#getConnectionIds()
0N/A getConnectionIds()}, and in the value
0N/A returned by the client's {@link
0N/A javax.management.remote.JMXConnector#getConnectionId()
0N/A getConnectionId()} method.</p>
0N/A
0N/A <p>As an example, a connection ID can look something like this:</p>
0N/A
0N/A <pre>
0N/Armi://192.18.1.9 username 1
0N/A </pre>
0N/A
0N/A <p>The formal grammar for connection ids that follow this
4008N/A convention is as follows (using the grammar notation from section 2.4 of
4008N/A <em>The Java&trade; Language Specification</em>):</p>
0N/A <pre>
0N/A<em>ConnectionId:</em>
0N/A <em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>
0N/A
0N/A<em>ClientAddress:</em>
0N/A // <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>
0N/A
0N/A<em>ClientPort</em>
0N/A : <em>HostPort</em>
0N/A </pre>
0N/A
0N/A <p>The <code><em>Protocol</em></code> is a protocol that would
0N/A be recognized by {@link
0N/A javax.management.remote.JMXConnectorFactory
0N/A JMXConnectorFactory}.</p>
0N/A
0N/A <p>The <code><em>ClientAddress</em></code> is the
0N/A address and port of the connecting client, if these can be
0N/A determined, otherwise nothing. The
0N/A <code><em>HostAddress</em></code> is the Internet address of
0N/A the host that the client is connecting from, in numeric or DNS
0N/A form. Numeric IPv6 addresses are enclosed in square brackets
0N/A <code>[]</code>. The <code><em>HostPort</em></code> is the
0N/A decimal port number that the client is connecting from.</p>
0N/A
0N/A <p>The <code><em>ClientId</em></code> is the identity of the
0N/A client entity, typically a string returned by {@link
0N/A javax.management.remote.JMXPrincipal#getName()
0N/A JMXPrincipal.getName()}. This string must not contain
0N/A spaces.</p>
0N/A
0N/A <p>The <code><em>ArbitraryText</em></code> is any additional
0N/A text that the connector server adds when creating the client id.
0N/A At a minimum, it must be enough to distinguish this connection
0N/A ID from the ID of any other connection currently opened by this
0N/A connector server.</p>
0N/A
0N/A
0N/A @see <a href="{@docRoot}/technotes/guides/jmx/">
4230N/A Java Platform documentation on JMX technology</a>,
0N/A in particular the
0N/A <a href="{@docRoot}/technotes/guides/jmx/JMX_1_4_specification.pdf">
0N/A JMX Specification, version 1.4</a>
0N/A
0N/A @since 1.5
0N/A
0N/A </body>
0N/A</html>