0N/A <
title>RMI connector</
title>
2362N/ACopyright (c) 2002, 2006, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 2362N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 2362N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="white">
0N/A <
p>The RMI connector is a connector for the JMX Remote API that
0N/A uses RMI to transmit client requests to a remote MBean server.
0N/A This package defines the classes that the user of an RMI
0N/A connector needs to reference directly, for both the client and
0N/A server sides. It also defines certain classes that the user
0N/A will not usually reference directly, but that must be defined so
0N/A that different implementations of the RMI connector can
0N/A <
p>The RMI connector supports both the JRMP and the IIOP transports
0N/A <
p>Like most connectors in the JMX Remote API, an RMI connector
0N/A usually has an address, which
0N/A JMXServiceURL}. The protocol part of this address is
0N/A <
code>rmi</
code> for a connector that uses the default RMI
0N/A transport (JRMP), or <
code>iiop</
code> for a connector that
0N/A <
p>There are two forms for RMI connector addresses:</
p>
0N/A In the <
em>JNDI form</
em>, the URL indicates <
em>where to find
0N/A an RMI stub for the connector</
em>. This RMI stub is a Java
0N/A RMIServer} that gives remote access to the connector server.
0N/A With this address form, the RMI stub is obtained from an
0N/A external directory entry included in the URL. An external
0N/A JNDI}, typically the RMI registry, LDAP, or COS Naming.
0N/A In the <
em>encoded form</
em>, the URL directly includes the
0N/A information needed to connect to the connector server. When
0N/A using
RMI/
JRMP, the encoded form is the serialized RMI stub
0N/A for the server object, encoded using BASE64 without embedded
0N/A newlines. When using
RMI/
IIOP, the encoded form is the CORBA
0N/A IOR for the server object.
0N/A <
p>Addresses are covered in more detail below.</
p>
0N/A <
h3>Creating an RMI connector server</
h3>
0N/A <
p>The usual way to create an RMI connector server is to supply an
0N/A RMI connector address to the method {@link
0N/A server to which the connector server is attached can be
0N/A specified as a parameter to that method. Alternatively, the
0N/A connector server can be registered as an MBean in that MBean
0N/A <
p>An RMI connector server can also be created by constructing an
0N/A RMIConnectorServer}, explicitly or through the MBean server's
0N/A <
code>createMBean</
code> method.</
p>
0N/A <
h4>Choosing the RMI transport</
h4>
0N/A <
p>You can choose the RMI transport (JRMP or IIOP) by specifying
0N/A <
code>rmi</
code> or <
code>iiop</
code> in the
0N/A <
code><
em>protocol</
em></
code> part of the
0N/A <
code>serviceURL</
code> when creating the connector server. You
0N/A can also create specialised connector servers by instantiating
0N/A an appropriate subclass of {@link
0N/A supplying it to the <
code>RMIConnectorServer</
code>
0N/A <
h4><
a name="servergen">Connector addresses generated by the
0N/A <
p>If the <
code>serviceURL</
code> you specify has an empty URL
0N/A path (after the optional host and port), or if you do not
0N/A specify a <
code>serviceURL</
code>, then the connector server
0N/A will fabricate a new <
code>JMXServiceURL</
code> that clients can
0N/A <
li><
p>If the <
code>serviceURL</
code> looks like:</
p>
0N/A <
code>service:jmx:rmi://<
em>host</
em>:<
em>port</
em></
code>
0N/A <
p>then the connector server will generate an {@link
0N/A RMIJRMPServerImpl} and the returned <
code>JMXServiceURL</
code>
0N/A <
code>service:jmx:rmi://<
em>host</
em>:<
em>port</
em>/stub/<
em>XXXX</
em></
code>
0N/A <
p>where <
code><
em>XXXX</
em></
code> is the serialized form of the
0N/A stub for the generated object, encoded in BASE64 without
0N/A <
li><
p>If the <
code>serviceURL</
code> looks like:</
p>
0N/A <
code>service:jmx:iiop://<
em>host</
em>:<
em>port</
em></
code>
0N/A <
p>then the connector server will generate an {@link
0N/A RMIIIOPServerImpl} and the returned
0N/A <
code>JMXServiceURL</
code> looks like:</
p>
0N/A <
code>service:jmx:iiop://<
em>host</
em>:<
em>port</
em>/
ior/
IOR:<
em>XXXX</
em></
code>
0N/A <
p>where <
code>IOR:<
em>XXXX</
em></
code> is the standard CORBA
0N/A encoding of the Interoperable Object Reference for the
0N/A generated object.</
p>
0N/A <
li><
p>If there is no <
code>serviceURL</
code>, there must be a
0N/A user-provided <
code>RMIServerImpl</
code>. If the {@link
0N/A method on this object returns an instance of {@link
0N/A a <
code>JMXServiceURL</
code> using the <
code>iiop</
code>
0N/A form above. Otherwise, it will generate a
0N/A <
code>JMXServiceURL</
code> using the <
code>rmi</
code>
0N/A <
p>The <
code><
em>host</
em></
code> in a user-provided
0N/A <
code>serviceURL</
code> is optional. If present, it is copied
0N/A into the generated <
code>JMXServiceURL</
code> but otherwise
0N/A ignored. If absent, the generated <
code>JXMServiceURL</
code>
0N/A will have the local host name.</
p>
0N/A <
p>The <
code><
em>port</
em></
code> in a user-provided
0N/A <
code>serviceURL</
code> is also optional. If present, it is
0N/A also copied into the generated <
code>JMXServiceURL</
code>;
0N/A otherwise, the generated <
code>JMXServiceURL</
code> has no port.
0N/A For an <
code>serviceURL</
code> using the <
code>rmi</
code>
0N/A protocol, the <
code><
em>port</
em></
code>, if present, indicates
0N/A what port the generated remote object should be exported on. It
0N/A has no other effect.</
p>
0N/A <
p>If the user provides an <
code>RMIServerImpl</
code> rather than a
0N/A <
code>JMXServiceURL</
code>, then the generated
0N/A <
code>JMXServiceURL</
code> will have the local host name in its
0N/A <
code><
em>host</
em></
code> part and no
0N/A <
code><
em>port</
em></
code>.</
p>
0N/A <
h4><
a name="directory">Connector addresses based on directory
0N/A <
p>As an alternative to the generated addresses just described,
0N/A the <
code>serviceURL</
code> address supplied when creating a
0N/A connector server can specify a <
em>directory address</
em> in
0N/A which to store the provided or generated <
code>RMIServer</
code>
0N/A stub. This directory address is then used by both client and
0N/A <
p>In this case, the <
code>serviceURL</
code> has one of these two
0N/A <
code>service:jmx:rmi://<
em>host</
em>:<
em>port</
em>/jndi/<
em>jndi-name</
em></
code>
0N/A <
code>service:jmx:iiop://<
em>host</
em>:<
em>port</
em>/jndi/<
em>jndi-name</
em></
code>
0N/A <
p>Here, <
code><
em>jndi-name</
em></
code> is a string that can be
0N/A <
p>As usual, the <
code><
em>host</
em></
code> and
0N/A <
code>:<
em>port</
em></
code> can be omitted.</
p>
0N/A <
p>The connector server will generate an
0N/A <
code>RMIServerImpl</
code> based on the protocol
0N/A (<
code>rmi</
code> or <
code>iiop</
code>) and, for
0N/A <
code>rmi</
code>, the <
code><
em>port</
em></
code> if any. When
0N/A the connector server is started, it will derive a stub from this
0N/A object using its {@link
0N/A and store the object using the given
0N/A <
code><
em>jndi-name</
em></
code>. The properties defined by the
0N/A JNDI API are consulted as usual.</
p>
0N/A <
p>For example, if the <
code>JMXServiceURL</
code> is:
0N/A then the connector server will generate an
0N/A <
code>RMIJRMPServerImpl</
code> and store its stub using the JNDI
0N/A which means entry <
code>myname</
code> in the RMI registry
0N/A running on the default port of host <
code>myhost</
code>. Note
0N/A that the RMI registry only allows registration from the local
0N/A host. So, in this case, <
code>myhost</
code> must be the name
0N/A (or a name) of the host that the connector server is running
0N/A <
p>In this <
code>JMXServiceURL</
code>, the first <
code>rmi:</
code>
0N/A connector, while the second <
code>rmi:</
code> specifies the RMI
0N/A <
p>As another example, if the <
code>JMXServiceURL</
code> is:
0N/A then the connector server will generate an
0N/A <
code>RMIIIOPServerImpl</
code> and store its stub using the JNDI
0N/A <
code>ldap://dirhost:
9999/
cn=this,ou=that</
code>
0N/A which means entry <
code>cn=this,ou=that</
code> in the LDAP
0N/A directory running on port 9999 of host <
code>dirhost</
code>.</
p>
0N/A <
p>If the <
code>JMXServiceURL</
code> is:
0N/A then the connector server will generate an
0N/A <
code>RMIIIOPServerImpl</
code> and store its stub using the JNDI
0N/A <
code>cn=this,ou=that</
code>
0N/A For this case to work, the JNDI API must have been configured
0N/A appropriately to supply the information about what directory to
0N/A <
p>In these examples, the host name <
code>ignoredhost</
code> is
0N/A not used by the connector server or its clients. It can be
0N/A omitted, for example:</
p>
0N/A <
code>service:jmx:iiop:///
jndi/
cn=this,ou=that</
code>
0N/A <
p>However, it is good practice to use the name of the host
0N/A where the connector server is running. This is often different
0N/A from the name of the directory host.</
p>
0N/A <
h4>Connector server attributes</
h4>
0N/A <
p>When using the default JRMP transport, RMI socket factories can
0N/A be specified using the attributes
0N/A <
code>environment</
code> given to the
0N/A <
code>RMIConnectorServer</
code> constructor. The values of these
0N/A attributes must be of type {@link
0N/A factories are used when creating the RMI objects associated with
0N/A <
h3>Creating an RMI connector client</
h3>
0N/A <
p>An RMI connector client is usually constructed using {@link
0N/A <
code>JMXServiceURL</
code> that has <
code>rmi</
code> or
0N/A <
code>iiop</
code> as its protocol.</
p>
0N/A <
p>If the <
code>JMXServiceURL</
code> was generated by the server,
0N/A as described above under <
a href="#servergen">"connector
0N/A addresses generated by the server"</
a>, then the client will
0N/A need to obtain it directly or indirectly from the server.
0N/A Typically, the server makes the <
code>JMXServiceURL</
code>
0N/A available by storing it in a file or a lookup service.</
p>
0N/A <
p>If the <
code>JMXServiceURL</
code> uses the directory syntax, as
0N/A described above under <
a href="#directory">"connector addresses
0N/A based on directory entries"</
a>, then the client may obtain it
0N/A as just explained, or client and server may both know the
0N/A appropriate directory entry to use. For example, if the
0N/A connector server for the Whatsit agent uses the entry
0N/A <
code>whatsit-agent-connector</
code> in the RMI registry on host
0N/A <
code>myhost</
code>, then client and server can both know
0N/A that the appropriate <
code>JMXServiceURL</
code> is:</
p>
0N/A <
p>If you have an RMI stub of type {@link
0N/A construct an RMI connection directly by using the appropriate
0N/A <
h3>Specifying an ORB for the
RMI/
IIOP connector</
h3>
0N/A <
p>When using the IIOP transport, the client and server can
0N/A specify what ORB to use
0N/A Connection to the ORB happens at {@link
0N/A for the connector server, and at {@link
0N/A connect} time for the connector client.
0N/A in the environment Map, then its value (an {@link
0N/A later RMI connector client or server in the same JVM can reuse
0N/A this ORB, or it can create another one in the same way.</
p>
0N/A <
p>The mechanism described here does not apply when the IIOP
0N/A Remote objects (Stubs or Servers) are created and connected to
0N/A an ORB manually before being passed to the RMIConnector and
0N/A RMIConnectorServer.</
p>
0N/A <
h3>Dynamic code downloading</
h3>
0N/A <
p>If an RMI connector client or server receives from its peer an
0N/A instance of a class that it does not know, and if dynamic code
0N/A downloading is active for the RMI connection, then the class can
0N/A be downloaded from a codebase specified by the peer. The
0N/A code downloading using Java RMI</
em></
a> explains this in more
0N/A Java<
sup><
font size="-1">TM</
font></
sup> Remote Method
0N/A Invocation (RMI)</
a>
0N/A Java Naming and Directory Interface<
sup><
font 0N/A size="-1">TM</
font></
sup> (JNDI)</
a>
0N/A section 6.8, "Base64 Content-Transfer-Encoding"</
a>