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