1 <html>
2 <head>
3 <title>JMX<sup><font size="-2">TM</font></sup> Remote API.</title>
4 <!--
5 Copyright (c) 2002, 2011, 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="{@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).</p>
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>
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™ 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>