1<html> 2<head> 3 <title>JMX™ Remote API.</title> 4<!-- 5Copyright (c) 2002, 2014, Oracle and/or its affiliates. All rights reserved. 6DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 7 8This code is free software; you can redistribute it and/or modify it 9under the terms of the GNU General Public License version 2 only, as 10published by the Free Software Foundation. Oracle designates this 11particular file as subject to the "Classpath" exception as provided 12by Oracle in the LICENSE file that accompanied this code. 13 14This code is distributed in the hope that it will be useful, but WITHOUT 15ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 16FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 17version 2 for more details (a copy is included in the LICENSE file that 18accompanied this code). 19 20You should have received a copy of the GNU General Public License version 212 along with this work; if not, write to the Free Software Foundation, 22Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 23 24Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 25or visit www.oracle.com if you need additional information or have any 26questions. 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="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf"> 36 JMX Specification, version 1.4</a> PDF document.</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 <h3>Connector addresses</h3> 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 <h3>Creating a connector server</h3> 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 <h3>Creating a connector client</h3> 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 <h3>Additional client or server parameters</h3> 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 <h3>Connection identifiers</h3> 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> 153rmi://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™ 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="{@docRoot}/../technotes/guides/jmx/"> 198 Java Platform documentation on JMX technology</a>, 199 in particular the 200 <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf"> 201 JMX Specification, version 1.4</a> 202 203 @since 1.5 204 205 </body> 206</html> 207