< prev index next >

src/java.management.rmi/share/classes/javax/management/remote/rmi/package.html

Print this page


   1 <html>
   2 <head>
   3     <title>RMI connector</title>
   4 <!--
   5 Copyright (c) 2002, 2019, 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


  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     <h2>Creating an RMI connector server</h2>
  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     <h3>Choosing the RMI transport</h3>
  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     <h3><a id="servergen">Connector addresses generated by the
 102         server</a></h3>
 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 


 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     <h3><a id="directory">Connector addresses based on directory
 161         entries</a></h3>
 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>


 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     <h3>Connector server attributes</h3>
 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     <h2>Creating an RMI connector client</h2>
 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     <h2>Dynamic code downloading</h2>
 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.
 320       {@extLink rmi_guide Java RMI Guide} explains this in more detail.</p>
 321 
 322     @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045,
 323     section 6.8, "Base64 Content-Transfer-Encoding"</a>
 324 
 325 
 326     @since 1.5
 327 
 328   </body>
 329 </html>
   1 <html>
   2 <head>
   3     <title>RMI connector</title>
   4 <!--
   5 Copyright (c) 2002, 2017, 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


  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 id="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 


 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 id="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>


 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.
 320       {@extLink rmi_guide Java RMI Guide} explains this in more detail.</p>
 321 
 322     @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045,
 323     section 6.8, "Base64 Content-Transfer-Encoding"</a>
 324 
 325 
 326     @since 1.5
 327 
 328   </body>
 329 </html>
< prev index next >