Skip to content

D
dragonwell11

openanolis / dragonwell11

通知 7
Star 2
Fork 0
D
dragonwell11

体验新版 GitCode，发现更多精彩内容 >>

切换分支/标签
查找文件 普通视图历史永久链接Permalink
package.html 15.8 KB
Newer Older
D
Initial load  
duke 已提交
1 2 3 4 
<html>
<head>
    <title>RMI connector</title>
<!--
O
6943119: Rebrand source copyright notices  
ohair 已提交
5 
Copyright (c) 2002, 2006, Oracle and/or its affiliates. All rights reserved.
D
Initial load  
duke 已提交
6 7 8 9 
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
O
6943119: Rebrand source copyright notices  
ohair 已提交
10 
published by the Free Software Foundation.  Oracle designates this
D
Initial load  
duke 已提交
11 
particular file as subject to the "Classpath" exception as provided
O
6943119: Rebrand source copyright notices  
ohair 已提交
12 
by Oracle in the LICENSE file that accompanied this code.
D
Initial load  
duke 已提交
13 14 15 16 17 18 19 20 21 22 23 

This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).

You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
O
6956202: Fix a few missed rebranding issues, please contact lines etc.  
ohair 已提交
24 25 26 
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
D
Initial load  
duke 已提交
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 
-->
</head>
<body bgcolor="white">
    <p>The RMI connector is a connector for the JMX Remote API that
      uses RMI to transmit client requests to a remote MBean server.
      This package defines the classes that the user of an RMI
      connector needs to reference directly, for both the client and
      server sides.  It also defines certain classes that the user
      will not usually reference directly, but that must be defined so
      that different implementations of the RMI connector can
      interoperate.</p>

    <p>The RMI connector supports both the JRMP and the IIOP transports
      for RMI.</p>

    <p>Like most connectors in the JMX Remote API, an RMI connector
      usually has an address, which
      is a {@link javax.management.remote.JMXServiceURL
      JMXServiceURL}.  The protocol part of this address is
      <code>rmi</code> for a connector that uses the default RMI
      transport (JRMP), or <code>iiop</code> for a connector that
      uses RMI/IIOP.</p>

    <p>There are two forms for RMI connector addresses:</p>

    <ul>
      <li>
	In the <em>JNDI form</em>, the URL indicates <em>where to find
	an RMI stub for the connector</em>.  This RMI stub is a Java
	object of type {@link javax.management.remote.rmi.RMIServer
	RMIServer} that gives remote access to the connector server.
	With this address form, the RMI stub is obtained from an
	external directory entry included in the URL.  An external
	directory is any directory recognized by {@link javax.naming
	JNDI}, typically the RMI registry, LDAP, or COS Naming.

      <li>
	In the <em>encoded form</em>, the URL directly includes the
	information needed to connect to the connector server.  When
	using RMI/JRMP, the encoded form is the serialized RMI stub
	for the server object, encoded using BASE64 without embedded
	newlines.  When using RMI/IIOP, the encoded form is the CORBA
	IOR for the server object.
    </ul>
    
    <p>Addresses are covered in more detail below.</p>


    <h3>Creating an RMI connector server</h3>

    <p>The usual way to create an RMI connector server is to supply an
      RMI connector address to the method {@link
      javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer
      JMXConnectorServerFactory.newJMXConnectorServer}.  The MBean
      server to which the connector server is attached can be
      specified as a parameter to that method.  Alternatively, the
      connector server can be registered as an MBean in that MBean
      server.</p>

    <p>An RMI connector server can also be created by constructing an
      instance of {@link
      javax.management.remote.rmi.RMIConnectorServer
      RMIConnectorServer}, explicitly or through the MBean server's
      <code>createMBean</code> method.</p>

    <h4>Choosing the RMI transport</h4>

    <p>You can choose the RMI transport (JRMP or IIOP) by specifying
      <code>rmi</code> or <code>iiop</code> in the
      <code><em>protocol</em></code> part of the
      <code>serviceURL</code> when creating the connector server.  You
      can also create specialised connector servers by instantiating
      an appropriate subclass of {@link
      javax.management.remote.rmi.RMIServerImpl RMIServerImpl} and
      supplying it to the <code>RMIConnectorServer</code>
      constructor.</p>


    <h4><a name="servergen">Connector addresses generated by the
	server</a></h4>

    <p>If the <code>serviceURL</code> you specify has an empty URL
      path (after the optional host and port), or if you do not
      specify a <code>serviceURL</code>, then the connector server
      will fabricate a new <code>JMXServiceURL</code> that clients can
      use to connect:</p>

    <ul>

      <li><p>If the <code>serviceURL</code> looks like:</p>

	<pre>
	<code>service:jmx:rmi://<em>host</em>:<em>port</em></code>
	</pre>

	<p>then the connector server will generate an {@link
	javax.management.remote.rmi.RMIJRMPServerImpl
	RMIJRMPServerImpl} and the returned <code>JMXServiceURL</code>
	looks like:</p>

	<pre>
	<code>service:jmx:rmi://<em>host</em>:<em>port</em>/stub/<em>XXXX</em></code>
	</pre>

	<p>where <code><em>XXXX</em></code> is the serialized form of the
	stub for the generated object, encoded in BASE64 without
	newlines.</p>

      <li><p>If the <code>serviceURL</code> looks like:</p>

	<pre>
	<code>service:jmx:iiop://<em>host</em>:<em>port</em></code>
	</pre>
	
	<p>then the connector server will generate an {@link
	javax.management.remote.rmi.RMIIIOPServerImpl
	RMIIIOPServerImpl} and the returned
	<code>JMXServiceURL</code> looks like:</p>

	<pre>
	<code>service:jmx:iiop://<em>host</em>:<em>port</em>/ior/IOR:<em>XXXX</em></code>
	</pre>

	<p>where <code>IOR:<em>XXXX</em></code> is the standard CORBA
	encoding of the Interoperable Object Reference for the
	generated object.</p>

      <li><p>If there is no <code>serviceURL</code>, there must be a
	user-provided <code>RMIServerImpl</code>.  If the {@link
	javax.management.remote.rmi.RMIServerImpl#toStub toStub}
	method on this object returns an instance of {@link
	javax.rmi.CORBA.Stub}, then the connector server will generate
	a <code>JMXServiceURL</code> using the <code>iiop</code>
	form above.  Otherwise, it will generate a
	<code>JMXServiceURL</code> using the <code>rmi</code>
	form.</p>

    </ul>

    <p>The <code><em>host</em></code> in a user-provided
      <code>serviceURL</code> is optional.  If present, it is copied
      into the generated <code>JMXServiceURL</code> but otherwise
      ignored.  If absent, the generated <code>JXMServiceURL</code>
      will have the local host name.</p>

    <p>The <code><em>port</em></code> in a user-provided
      <code>serviceURL</code> is also optional.  If present, it is
      also copied into the generated <code>JMXServiceURL</code>;
      otherwise, the generated <code>JMXServiceURL</code> has no port.
      For an <code>serviceURL</code> using the <code>rmi</code>
      protocol, the <code><em>port</em></code>, if present, indicates
      what port the generated remote object should be exported on.  It
      has no other effect.</p>

    <p>If the user provides an <code>RMIServerImpl</code> rather than a
      <code>JMXServiceURL</code>, then the generated
      <code>JMXServiceURL</code> will have the local host name in its
      <code><em>host</em></code> part and no
      <code><em>port</em></code>.</p>


    <h4><a name="directory">Connector addresses based on directory
	entries</a></h4>

    <p>As an alternative to the generated addresses just described,
      the <code>serviceURL</code> address supplied when creating a
      connector server can specify a <em>directory address</em> in
      which to store the provided or generated <code>RMIServer</code>
      stub.  This directory address is then used by both client and
      server.</p>

    <p>In this case, the <code>serviceURL</code> has one of these two
      forms:</p>

    <pre>
    <code>service:jmx:rmi://<em>host</em>:<em>port</em>/jndi/<em>jndi-name</em></code>
    <code>service:jmx:iiop://<em>host</em>:<em>port</em>/jndi/<em>jndi-name</em></code>
    </pre>

    <p>Here, <code><em>jndi-name</em></code> is a string that can be
      supplied to {@link javax.naming.InitialContext#bind
      javax.naming.InitialContext.bind}.</p>

    <p>As usual, the <code><em>host</em></code> and
      <code>:<em>port</em></code> can be omitted.</p>

    <p>The connector server will generate an
      <code>RMIServerImpl</code> based on the protocol
      (<code>rmi</code> or <code>iiop</code>) and, for
      <code>rmi</code>, the <code><em>port</em></code> if any.  When
      the connector server is started, it will derive a stub from this
      object using its {@link
      javax.management.remote.rmi.RMIServerImpl#toStub toStub} method
      and store the object using the given
      <code><em>jndi-name</em></code>.  The properties defined by the
      JNDI API are consulted as usual.</p>

    <p>For example, if the <code>JMXServiceURL</code> is:

      <pre>
      <code>service:jmx:rmi://ignoredhost/jndi/rmi://myhost/myname</code>
      </pre>

      then the connector server will generate an
      <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
      name

      <pre>
      <code>rmi://myhost/myname</code>
      </pre>

      which means entry <code>myname</code> in the RMI registry
      running on the default port of host <code>myhost</code>.  Note
      that the RMI registry only allows registration from the local
      host.  So, in this case, <code>myhost</code> must be the name
      (or a name) of the host that the connector server is running
      on.</p>

    <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
      specifies the RMI
      connector, while the second <code>rmi:</code> specifies the RMI
      registry.</p>

    <p>As another example, if the <code>JMXServiceURL</code> is:

      <pre>
      <code>service:jmx:iiop://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that</code>
      </pre>

      then the connector server will generate an
      <code>RMIIIOPServerImpl</code> and store its stub using the JNDI
      name

      <pre>
      <code>ldap://dirhost:9999/cn=this,ou=that</code>
      </pre>

      which means entry <code>cn=this,ou=that</code> in the LDAP
      directory running on port 9999 of host <code>dirhost</code>.</p>

    <p>If the <code>JMXServiceURL</code> is:

      <pre>
      <code>service:jmx:iiop://ignoredhost/jndi/cn=this,ou=that</code>
      </pre>

      then the connector server will generate an
      <code>RMIIIOPServerImpl</code> and store its stub using the JNDI
      name

      <pre>
      <code>cn=this,ou=that</code>
      </pre>

      For this case to work, the JNDI API must have been configured
      appropriately to supply the information about what directory to
      use.</p>

    <p>In these examples, the host name <code>ignoredhost</code> is
      not used by the connector server or its clients.  It can be
      omitted, for example:</p>

      <pre>
      <code>service:jmx:iiop:///jndi/cn=this,ou=that</code>
      </pre>

    <p>However, it is good practice to use the name of the host
      where the connector server is running.  This is often different
      from the name of the directory host.</p>


    <h4>Connector server attributes</h4>

    <p>When using the default JRMP transport, RMI socket factories can
      be specified using the attributes
      <code>jmx.remote.rmi.client.socket.factory</code> and
      <code>jmx.remote.rmi.server.socket.factory</code> in the
      <code>environment</code> given to the
      <code>RMIConnectorServer</code> constructor.  The values of these
      attributes must be of type {@link
      java.rmi.server.RMIClientSocketFactory} and {@link
      java.rmi.server.RMIServerSocketFactory}, respectively.  These
      factories are used when creating the RMI objects associated with
      the connector.</p>

    <h3>Creating an RMI connector client</h3>

    <p>An RMI connector client is usually constructed using {@link
      javax.management.remote.JMXConnectorFactory}, with a
      <code>JMXServiceURL</code> that has <code>rmi</code> or
      <code>iiop</code> as its protocol.</p>

    <p>If the <code>JMXServiceURL</code> was generated by the server,
      as described above under <a href="#servergen">"connector
      addresses generated by the server"</a>, then the client will
      need to obtain it directly or indirectly from the server.
      Typically, the server makes the <code>JMXServiceURL</code>
      available by storing it in a file or a lookup service.</p>

    <p>If the <code>JMXServiceURL</code> uses the directory syntax, as
      described above under <a href="#directory">"connector addresses
      based on directory entries"</a>, then the client may obtain it
      as just explained, or client and server may both know the
      appropriate directory entry to use.  For example, if the
      connector server for the Whatsit agent uses the entry
      <code>whatsit-agent-connector</code> in the RMI registry on host
      <code>myhost</code>, then client and server can both know
      that the appropriate <code>JMXServiceURL</code> is:</p>

    <pre>
    <code>service:jmx:rmi:///jndi/rmi://myhost/whatsit-agent-connector</code>
    </pre>

    <p>If you have an RMI stub of type {@link
      javax.management.remote.rmi.RMIServer RMIServer}, you can
      construct an RMI connection directly by using the appropriate
      constructor of {@link javax.management.remote.rmi.RMIConnector
      RMIConnector}.</p>


    <h3>Specifying an ORB for the RMI/IIOP connector</h3>

    <p>When using the IIOP transport, the client and server can
      specify what ORB to use
      with the attribute <code>java.naming.corba.orb</code>.
      Connection to the ORB happens at {@link 
      javax.management.remote.rmi.RMIConnectorServer#start() start} time 
      for the connector server, and at {@link 
      javax.management.remote.rmi.RMIConnector#connect(java.util.Map) 
      connect} time for the connector client.
      If the <code>java.naming.corba.orb</code> attribute is contained
      in the environment Map, then its value (an {@link 
      org.omg.CORBA.ORB ORB}), is used to connect the IIOP Stubs. 
      Otherwise, a new org.omg.CORBA.ORB is created by calling {@link 
      org.omg.CORBA.ORB
      org.omg.CORBA.ORB.init((String[])null,(Properties)null)}.  A
      later RMI connector client or server in the same JVM can reuse
      this ORB, or it can create another one in the same way.</p>

     <p>If the <code>java.naming.corba.orb</code> attribute is 
      specified and does not point to an {@link org.omg.CORBA.ORB ORB},
      then an <code>{@link java.lang.IllegalArgumentException}</code> 
      will be thrown.</p>

     <p>The mechanism described here does not apply when the IIOP
      Remote objects (Stubs or Servers) are created and connected to
      an ORB manually before being passed to the RMIConnector and
      RMIConnectorServer.</p>


    <h3>Dynamic code downloading</h3>

    <p>If an RMI connector client or server receives from its peer an
      instance of a class that it does not know, and if dynamic code
      downloading is active for the RMI connection, then the class can
      be downloaded from a codebase specified by the peer.  The
      article <a
    href="{@docRoot}/../technotes/guides/rmi/codebase.html"><em>Dynamic
    code downloading using Java RMI</em></a> explains this in more
    detail.</p>

 
    @see <a href="{@docRoot}/../technotes/guides/rmi/index.html">
	Java<sup><font size="-1">TM</font></sup> Remote Method
	Invocation (RMI)</a>

    @see <a href="{@docRoot}/../technotes/guides/jndi/index.html">
	Java Naming and Directory Interface<sup><font
	size="-1">TM</font></sup> (JNDI)</a>

    @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045,
    section 6.8, "Base64 Content-Transfer-Encoding"</a>


    @since 1.5

  </body>
</html>