1 <html>
   2 <head>
   3     <title>JMX&trade; Remote API.</title>
   4 <!--
   5 Copyright (c) 2002, 2019, Oracle and/or its affiliates. All rights reserved.
   6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   7 
   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.
  13 
  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).
  19 
  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.
  23 
  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>
  37 
  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>
  45 
  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:
  49 
  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.
  54 
  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).
  59 
  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>
  65 
  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>
  72 
  73 
  74       <h2>Connector addresses</h2>
  75 
  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>
  80 
  81       <pre>
  82       service:jmx:rmi:///jndi/rmi://myhost:1099/myname
  83       </pre>
  84 
  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.
  89 
  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>
  94 
  95       <h2>Creating a connector server</h2>
  96 
  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>
 105 
 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>
 110 
 111       <h2>Creating a connector client</h2>
 112 
 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>
 118 
 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>
 125 
 126       <h2>Additional client or server parameters</h2>
 127 
 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>
 135 
 136       <h2>Connection identifiers</h2>
 137 
 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>
 149 
 150       <p>As an example, a connection ID can look something like this:</p>
 151 
 152       <pre>
 153 rmi://192.18.1.9 username 1
 154       </pre>
 155 
 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>
 162 
 163 <em>ClientAddress:</em>
 164     // <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>
 165 
 166 <em>ClientPort</em>
 167     : <em>HostPort</em>
 168       </pre>
 169 
 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>
 174 
 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>
 183 
 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>
 189 
 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>
 195 
 196 
 197     @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
 198       JMX Specification, version 1.4</a>
 199     
 200     @since 1.5
 201 
 202     </body>
 203 </html>