1 <html>
   2 <head>
   3     <title>JMX&trade; Remote API.</title>
   4 <!--
   5 Copyright (c) 2002, 2017, Oracle and/or its affiliates. All rights reserved.
   8 This code is free software; you can redistribute it and/or modify it
   9 under the terms of the GNU General Public License version 2 only, as
  10 published by the Free Software Foundation.  Oracle designates this
  11 particular file as subject to the "Classpath" exception as provided
  12 by Oracle in the LICENSE file that accompanied this code.
  14 This code is distributed in the hope that it will be useful, but WITHOUT
  15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  16 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17 version 2 for more details (a copy is included in the LICENSE file that
  18 accompanied this code).
  20 You should have received a copy of the GNU General Public License version
  21 2 along with this work; if not, write to the Free Software Foundation,
  22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  25 or visit www.oracle.com if you need additional information or have any
  26 questions.
  27 -->
  28 </head>
  29 <body bgcolor="white">
  30       <p>Interfaces for remote access to
  31         JMX MBean servers.
  32         This package defines the essential interfaces for making a JMX
  33         MBean server manageable remotely. The specification of this 
  34         functionality is completed by Part III of the 
  35        <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
  36         JMX Specification, version 1.4</a></p>
  38       <p>The JMX specification defines the notion of <b>connectors</b>.
  39         A connector is attached to a JMX API MBean server and makes it
  40         accessible to remote Java clients. The client end of a
  41         connector exports essentially the same interface as the MBean
  42         server, specifically the {@link
  43         javax.management.MBeanServerConnection MBeanServerConnection}
  44         interface.</p>
  46       <p>A connector makes an MBean server remotely accessible through
  47         a given protocol. The JMX Remote API allows the use of different 
  48         type of connectors:
  50       <ul>
  51        <li>The JMX Remote API defines a standard connector,
  52         the <b>RMI Connector</b>, which provides remote access to an
  53         MBeanServer through RMI.
  55        <li>The JMX Remote API also defines an optional connector called 
  56         <b>JMXMP Connector</b> implementing the JMX Message Protocol 
  57         (JMXMP). As it is optional, it is not part of this bundle (see
  58         note below).
  60        <li>User-defined connector protocols are also possible using the 
  61         {@link javax.management.remote.JMXConnectorFactory
  62         JMXConnectorFactory} and, optionally, the Generic Connector
  63         (not part of this bundle, see note below).
  64       </ul>
  66       <p><u>Note</u>: the optional packages implementing
  67         the optional part of the <em>JMX Remote API</em>
  68         are not included in the <em>Java SE Platform</em> 
  69         but are available from the <em>JMX Remote API 
  70         <a href="http://java.sun.com/products/JavaManagement/download.html">
  71         Reference Implementation</a></em>.</p>
  74       <h3>Connector addresses</h3>
  76       <p>Typically, a connector server has an address, represented by the
  77         class {@link javax.management.remote.JMXServiceURL
  78         JMXServiceURL}.  An address for the RMI Connector can look
  79         like this:</p>
  81       <pre>
  82       service:jmx:rmi:///jndi/rmi://myhost:1099/myname
  83       </pre>
  85       <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
  86         specifies the RMI connector, while the second <code>rmi:</code> 
  87         specifies the RMI registry into which the RMI connector server 
  88         has stored its stub.
  90       <p>The example above shows only one form of address.
  91         An address for the RMI Connector can take several forms,
  92         as detailed in the documentation for the package
  93         <code>{@link javax.management.remote.rmi}</code>.</p>
  95       <h3>Creating a connector server</h3>
  97       <p>A connector server is created by constructing an instance of
  98         a subclass of {@link
  99         javax.management.remote.JMXConnectorServer
 100         JMXConnectorServer}.  Usually, this instance is created
 101         using the method {@link
 102         javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer(JMXServiceURL,
 103         java.util.Map, javax.management.MBeanServer)
 104         JMXConnectorServerFactory.newJMXConnectorServer}.</p>
 106       <p>Typically, a connector server is associated with an MBean
 107         server either by registering it in that MBean server, or by
 108         supplying the MBean server as a parameter when creating the
 109         connector server.</p>
 111       <h3>Creating a connector client</h3>
 113       <p>A connector client is usually created by supplying the
 114         <code>JMXServiceURL</code> of the connector server to connect to 
 115         to the {@link
 116         javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)
 117         JMXConnectorFactory.connect} method.</p>
 119       <p>For more specialized uses, a connector client can be created
 120         by directly instantiating a class that implements the {@link
 121         javax.management.remote.JMXConnector JMXConnector} interface,
 122         for example the class {@link
 123         javax.management.remote.rmi.RMIConnector
 124         RMIConnector}.</p>
 126       <h3>Additional client or server parameters</h3>
 128       <p>When creating a connector client or server, it is possible to
 129         supply an object of type {@link java.util.Map Map} that defines
 130         additional parameters.  Each entry in this Map has a key that is
 131         a string and an associated value whose type is appropriate for
 132         that key.  The standard keys defined by the JMX Remote API all
 133         begin with the string "<code>jmx.remote.</code>".  The document
 134         <em>JMX Remote API</em> lists these standard keys.</p>
 136       <h3>Connection identifiers</h3>
 138       <p>Every connection opened by a connector server has a string
 139         identifier, called its <b>connection id</b>.  This identifier
 140         appears in the {@link
 141         javax.management.remote.JMXConnectionNotification
 142         JMXConnectionNotification} events emitted by the connector
 143         server, in the list returned by {@link
 144         javax.management.remote.JMXConnectorServerMBean#getConnectionIds()
 145         getConnectionIds()}, and in the value
 146         returned by the client's {@link
 147         javax.management.remote.JMXConnector#getConnectionId()
 148         getConnectionId()} method.</p>
 150       <p>As an example, a connection ID can look something like this:</p>
 152       <pre>
 153 rmi:// username 1
 154       </pre>
 156       <p>The formal grammar for connection ids that follow this
 157          convention is as follows (using the grammar notation from section 2.4 of 
 158          <em>The Java&trade; Language Specification</em>):</p>
 159       <pre>
 160 <em>ConnectionId:</em>
 161     <em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>
 163 <em>ClientAddress:</em>
 164     // <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>
 166 <em>ClientPort</em>
 167     : <em>HostPort</em>
 168       </pre>
 170       <p>The <code><em>Protocol</em></code> is a protocol that would
 171         be recognized by {@link
 172         javax.management.remote.JMXConnectorFactory
 173         JMXConnectorFactory}.</p>
 175       <p>The <code><em>ClientAddress</em></code> is the
 176         address and port of the connecting client, if these can be
 177         determined, otherwise nothing.  The
 178         <code><em>HostAddress</em></code> is the Internet address of
 179         the host that the client is connecting from, in numeric or DNS
 180         form.  Numeric IPv6 addresses are enclosed in square brackets
 181         <code>[]</code>.  The <code><em>HostPort</em></code> is the
 182         decimal port number that the client is connecting from.</p>
 184       <p>The <code><em>ClientId</em></code> is the identity of the
 185         client entity, typically a string returned by {@link
 186         javax.management.remote.JMXPrincipal#getName()
 187         JMXPrincipal.getName()}.  This string must not contain
 188         spaces.</p>
 190       <p>The <code><em>ArbitraryText</em></code> is any additional
 191         text that the connector server adds when creating the client id.
 192         At a minimum, it must be enough to distinguish this connection
 193         ID from the ID of any other connection currently opened by this
 194         connector server.</p>
 197     @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
 198       JMX Specification, version 1.4</a>
 200     @since 1.5
 202     </body>
 203 </html>