1 <html>
2 <head>
3 <title>RMI connector</title>
4 <!--
5 Copyright (c) 2002, 2015, 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>The RMI connector is a connector for the JMX Remote API that
31 uses RMI to transmit client requests to a remote MBean server.
32 This package defines the classes that the user of an RMI
33 connector needs to reference directly, for both the client and
34 server sides. It also defines certain classes that the user
35 will not usually reference directly, but that must be defined so
36 that different implementations of the RMI connector can
37 interoperate.</p>
38
39 <p>The RMI connector supports the JRMP transport for RMI.</p>
40
41 <p>Like most connectors in the JMX Remote API, an RMI connector
42 usually has an address, which
43 is a {@link javax.management.remote.JMXServiceURL
44 JMXServiceURL}. The protocol part of this address is
45 <code>rmi</code> for a connector that uses the default RMI
46 transport (JRMP).</p>
47
48 <p>There are two forms for RMI connector addresses:</p>
49
50 <ul>
51 <li>
52 In the <em>JNDI form</em>, the URL indicates <em>where to find
53 an RMI stub for the connector</em>. This RMI stub is a Java
54 object of type {@link javax.management.remote.rmi.RMIServer
55 RMIServer} that gives remote access to the connector server.
56 With this address form, the RMI stub is obtained from an
57 external directory entry included in the URL. An external
58 directory is any directory recognized by {@link javax.naming
59 JNDI}, typically the RMI registry, LDAP, or COS Naming.
60
61 <li>
62 In the <em>encoded form</em>, the URL directly includes the
63 information needed to connect to the connector server. When
64 using RMI/JRMP, the encoded form is the serialized RMI stub
65 for the server object, encoded using BASE64 without embedded
66 newlines.
67 </ul>
68
69 <p>Addresses are covered in more detail below.</p>
70
71
72 <h3>Creating an RMI connector server</h3>
73
74 <p>The usual way to create an RMI connector server is to supply an
75 RMI connector address to the method {@link
76 javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer
77 JMXConnectorServerFactory.newJMXConnectorServer}. The MBean
78 server to which the connector server is attached can be
79 specified as a parameter to that method. Alternatively, the
80 connector server can be registered as an MBean in that MBean
81 server.</p>
82
83 <p>An RMI connector server can also be created by constructing an
84 instance of {@link
85 javax.management.remote.rmi.RMIConnectorServer
86 RMIConnectorServer}, explicitly or through the MBean server's
87 <code>createMBean</code> method.</p>
88
89 <h4>Choosing the RMI transport</h4>
90
91 <p>You can choose the RMI transport by specifying
92 <code>rmi</code> in the <code><em>protocol</em></code> part of the
93 <code>serviceURL</code> when creating the connector server. You
94 can also create specialized connector servers by instantiating
95 an appropriate subclass of {@link
96 javax.management.remote.rmi.RMIServerImpl RMIServerImpl} and
97 supplying it to the <code>RMIConnectorServer</code>
98 constructor.</p>
99
100
101 <h4><a name="servergen">Connector addresses generated by the
102 server</a></h4>
103
104 <p>If the <code>serviceURL</code> you specify has an empty URL
105 path (after the optional host and port), or if you do not
106 specify a <code>serviceURL</code>, then the connector server
107 will fabricate a new <code>JMXServiceURL</code> that clients can
108 use to connect:</p>
109
110 <ul>
111
112 <li><p>If the <code>serviceURL</code> looks like:</p>
113
114 <pre>
115 <code>service:jmx:rmi://<em>host</em>:<em>port</em></code>
116 </pre>
117
118 <p>then the connector server will generate an {@link
119 javax.management.remote.rmi.RMIJRMPServerImpl
120 RMIJRMPServerImpl} and the returned <code>JMXServiceURL</code>
121 looks like:</p>
122
123 <pre>
124 <code>service:jmx:rmi://<em>host</em>:<em>port</em>/stub/<em>XXXX</em></code>
125 </pre>
126
127 <p>where <code><em>XXXX</em></code> is the serialized form of the
128 stub for the generated object, encoded in BASE64 without
129 newlines.</p>
130
131 <li><p>If there is no <code>serviceURL</code>, there must be a
132 user-provided <code>RMIServerImpl</code>. The connector server
133 will generate a <code>JMXServiceURL</code> using the <code>rmi</code>
134 form.</p>
135
136 </ul>
137
138 <p>The <code><em>host</em></code> in a user-provided
139 <code>serviceURL</code> is optional. If present, it is copied
140 into the generated <code>JMXServiceURL</code> but otherwise
141 ignored. If absent, the generated <code>JXMServiceURL</code>
142 will have the local host name.</p>
143
144 <p>The <code><em>port</em></code> in a user-provided
145 <code>serviceURL</code> is also optional. If present, it is
146 also copied into the generated <code>JMXServiceURL</code>;
147 otherwise, the generated <code>JMXServiceURL</code> has no port.
148 For an <code>serviceURL</code> using the <code>rmi</code>
149 protocol, the <code><em>port</em></code>, if present, indicates
150 what port the generated remote object should be exported on. It
151 has no other effect.</p>
152
153 <p>If the user provides an <code>RMIServerImpl</code> rather than a
154 <code>JMXServiceURL</code>, then the generated
155 <code>JMXServiceURL</code> will have the local host name in its
156 <code><em>host</em></code> part and no
157 <code><em>port</em></code>.</p>
158
159
160 <h4><a name="directory">Connector addresses based on directory
161 entries</a></h4>
162
163 <p>As an alternative to the generated addresses just described,
164 the <code>serviceURL</code> address supplied when creating a
165 connector server can specify a <em>directory address</em> in
166 which to store the provided or generated <code>RMIServer</code>
167 stub. This directory address is then used by both client and
168 server.</p>
169
170 <p>In this case, the <code>serviceURL</code> has the following form:</p>
171
172 <pre>
173 <code>service:jmx:rmi://<em>host</em>:<em>port</em>/jndi/<em>jndi-name</em></code>
174 </pre>
175
176 <p>Here, <code><em>jndi-name</em></code> is a string that can be
177 supplied to {@link javax.naming.InitialContext#bind
178 javax.naming.InitialContext.bind}.</p>
179
180 <p>As usual, the <code><em>host</em></code> and
181 <code>:<em>port</em></code> can be omitted.</p>
182
183 <p>The connector server will generate an
184 <code>RMIServerImpl</code> based on the protocol
185 (<code>rmi</code>) and the <code><em>port</em></code> if any. When
186 the connector server is started, it will derive a stub from this
187 object using its {@link
188 javax.management.remote.rmi.RMIServerImpl#toStub toStub} method
189 and store the object using the given
190 <code><em>jndi-name</em></code>. The properties defined by the
191 JNDI API are consulted as usual.</p>
192
193 <p>For example, if the <code>JMXServiceURL</code> is:
194
195 <pre>
196 <code>service:jmx:rmi://ignoredhost/jndi/rmi://myhost/myname</code>
197 </pre>
198
199 then the connector server will generate an
200 <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
201 name
202
203 <pre>
204 <code>rmi://myhost/myname</code>
205 </pre>
206
207 which means entry <code>myname</code> in the RMI registry
208 running on the default port of host <code>myhost</code>. Note
209 that the RMI registry only allows registration from the local
210 host. So, in this case, <code>myhost</code> must be the name
211 (or a name) of the host that the connector server is running
212 on.
213
214 <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
215 specifies the RMI
216 connector, while the second <code>rmi:</code> specifies the RMI
217 registry.
218
219 <p>As another example, if the <code>JMXServiceURL</code> is:
220
221 <pre>
222 <code>service:jmx:rmi://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that</code>
223 </pre>
224
225 then the connector server will generate an
226 <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
227 name
228
229 <pre>
230 <code>ldap://dirhost:9999/cn=this,ou=that</code>
231 </pre>
232
233 which means entry <code>cn=this,ou=that</code> in the LDAP
234 directory running on port 9999 of host <code>dirhost</code>.
235
236 <p>If the <code>JMXServiceURL</code> is:
237
238 <pre>
239 <code>service:jmx:rmi://ignoredhost/jndi/cn=this,ou=that</code>
240 </pre>
241
242 then the connector server will generate an
243 <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
244 name
245
246 <pre>
247 <code>cn=this,ou=that</code>
248 </pre>
249
250 For this case to work, the JNDI API must have been configured
251 appropriately to supply the information about what directory to
252 use.
253
254 <p>In these examples, the host name <code>ignoredhost</code> is
255 not used by the connector server or its clients. It can be
256 omitted, for example:</p>
257
258 <pre>
259 <code>service:jmx:rmi:///jndi/cn=this,ou=that</code>
260 </pre>
261
262 <p>However, it is good practice to use the name of the host
263 where the connector server is running. This is often different
264 from the name of the directory host.</p>
265
266
267 <h4>Connector server attributes</h4>
268
269 <p>When using the default JRMP transport, RMI socket factories can
270 be specified using the attributes
271 <code>jmx.remote.rmi.client.socket.factory</code> and
272 <code>jmx.remote.rmi.server.socket.factory</code> in the
273 <code>environment</code> given to the
274 <code>RMIConnectorServer</code> constructor. The values of these
275 attributes must be of type {@link
276 java.rmi.server.RMIClientSocketFactory} and {@link
277 java.rmi.server.RMIServerSocketFactory}, respectively. These
278 factories are used when creating the RMI objects associated with
279 the connector.</p>
280
281 <h3>Creating an RMI connector client</h3>
282
283 <p>An RMI connector client is usually constructed using {@link
284 javax.management.remote.JMXConnectorFactory}, with a
285 <code>JMXServiceURL</code> that has <code>rmi</code> as its protocol.</p>
286
287 <p>If the <code>JMXServiceURL</code> was generated by the server,
288 as described above under <a href="#servergen">"connector
289 addresses generated by the server"</a>, then the client will
290 need to obtain it directly or indirectly from the server.
291 Typically, the server makes the <code>JMXServiceURL</code>
292 available by storing it in a file or a lookup service.</p>
293
294 <p>If the <code>JMXServiceURL</code> uses the directory syntax, as
295 described above under <a href="#directory">"connector addresses
296 based on directory entries"</a>, then the client may obtain it
297 as just explained, or client and server may both know the
298 appropriate directory entry to use. For example, if the
299 connector server for the Whatsit agent uses the entry
300 <code>whatsit-agent-connector</code> in the RMI registry on host
301 <code>myhost</code>, then client and server can both know
302 that the appropriate <code>JMXServiceURL</code> is:</p>
303
304 <pre>
305 <code>service:jmx:rmi:///jndi/rmi://myhost/whatsit-agent-connector</code>
306 </pre>
307
308 <p>If you have an RMI stub of type {@link
309 javax.management.remote.rmi.RMIServer RMIServer}, you can
310 construct an RMI connection directly by using the appropriate
311 constructor of {@link javax.management.remote.rmi.RMIConnector
312 RMIConnector}.</p>
313
314 <h3>Dynamic code downloading</h3>
315
316 <p>If an RMI connector client or server receives from its peer an
317 instance of a class that it does not know, and if dynamic code
318 downloading is active for the RMI connection, then the class can
319 be downloaded from a codebase specified by the peer. The
320 article <a
321 href="{@docRoot}/../technotes/guides/rmi/codebase.html"><em>Dynamic
322 code downloading using Java RMI</em></a> explains this in more
323 detail.</p>
324
325
326 @see <a href="{@docRoot}/../technotes/guides/rmi/index.html">
327 Java™ Remote Method
328 Invocation (RMI)</a>
329
330 @see <a href="{@docRoot}/../technotes/guides/jndi/index.html">
331 Java Naming and Directory Interface™ (JNDI)</a>
332
333 @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045,
334 section 6.8, "Base64 Content-Transfer-Encoding"</a>
335
336
337 @since 1.5
338
339 </body>
340 </html>