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.
The RMI connector supports the JRMP transport for RMI.
Like most connectors in the JMX Remote API, an RMI connector usually has an address, which is a JMXServiceURL
. The protocol part of this address is rmi
for a connector that uses the default RMI transport (JRMP).
There are two forms for RMI connector addresses:
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 JNDI
, typically the RMI registry, LDAP, or COS Naming. Addresses are covered in more detail below.
The usual way to create an RMI connector server is to supply an RMI connector address to the method 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.
An RMI connector server can also be created by constructing an instance of RMIConnectorServer
, explicitly or through the MBean server's createMBean
method.
You can choose the RMI transport by specifying rmi
in the protocol
part of the serviceURL
when creating the connector server. You can also create specialized connector servers by instantiating an appropriate subclass of RMIServerImpl
and supplying it to the RMIConnectorServer
constructor.
If the serviceURL
you specify has an empty URL path (after the optional host and port), or if you do not specify a serviceURL
, then the connector server will fabricate a new JMXServiceURL
that clients can use to connect:
If the serviceURL
looks like:
service:jmx:rmi://host:port
then the connector server will generate an RMIJRMPServerImpl
and the returned JMXServiceURL
looks like:
service:jmx:rmi://host:port/stub/XXXX
where XXXX
is the serialized form of the stub for the generated object, encoded in BASE64 without newlines.
If there is no serviceURL
, there must be a user-provided RMIServerImpl
. The connector server will generate a JMXServiceURL
using the rmi
form.
The host
in a user-provided serviceURL
is optional. If present, it is copied into the generated JMXServiceURL
but otherwise ignored. If absent, the generated JXMServiceURL
will have the local host name.
The port
in a user-provided serviceURL
is also optional. If present, it is also copied into the generated JMXServiceURL
; otherwise, the generated JMXServiceURL
has no port. For an serviceURL
using the rmi
protocol, the port
, if present, indicates what port the generated remote object should be exported on. It has no other effect.
If the user provides an RMIServerImpl
rather than a JMXServiceURL
, then the generated JMXServiceURL
will have the local host name in its host
part and no port
.
As an alternative to the generated addresses just described, the serviceURL
address supplied when creating a connector server can specify a directory address in which to store the provided or generated RMIServer
stub. This directory address is then used by both client and server.
In this case, the serviceURL
has the following form:
service:jmx:rmi://host:port/jndi/jndi-name
Here, jndi-name
is a string that can be supplied to javax.naming.InitialContext.bind
.
As usual, the host
and :port
can be omitted.
The connector server will generate an RMIServerImpl
based on the protocol (rmi
) and the port
if any. When the connector server is started, it will derive a stub from this object using its toStub
method and store the object using the given jndi-name
. The properties defined by the JNDI API are consulted as usual.
For example, if the JMXServiceURL
is:
service:jmx:rmi://ignoredhost/jndi/rmi://myhost/myname
then the connector server will generate an RMIJRMPServerImpl
and store its stub using the JNDI name
rmi://myhost/myname
which means entry myname
in the RMI registry running on the default port of host myhost
. Note that the RMI registry only allows registration from the local host. So, in this case, myhost
must be the name (or a name) of the host that the connector server is running on. In this JMXServiceURL
, the first rmi:
specifies the RMI connector, while the second rmi:
specifies the RMI registry.
As another example, if the JMXServiceURL
is:
service:jmx:rmi://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that
then the connector server will generate an RMIJRMPServerImpl
and store its stub using the JNDI name
ldap://dirhost:9999/cn=this,ou=that
which means entry cn=this,ou=that
in the LDAP directory running on port 9999 of host dirhost
. If the JMXServiceURL
is:
service:jmx:rmi://ignoredhost/jndi/cn=this,ou=that
then the connector server will generate an RMIJRMPServerImpl
and store its stub using the JNDI name
cn=this,ou=that
For this case to work, the JNDI API must have been configured appropriately to supply the information about what directory to use. In these examples, the host name ignoredhost
is not used by the connector server or its clients. It can be omitted, for example:
service:jmx:rmi:///jndi/cn=this,ou=that
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.
When using the default JRMP transport, RMI socket factories can be specified using the attributes jmx.remote.rmi.client.socket.factory
and jmx.remote.rmi.server.socket.factory
in the environment
given to the RMIConnectorServer
constructor. The values of these attributes must be of type RMIClientSocketFactory
and RMIServerSocketFactory
, respectively. These factories are used when creating the RMI objects associated with the connector.
An RMI connector client is usually constructed using JMXConnectorFactory
, with a JMXServiceURL
that has rmi
as its protocol.
If the JMXServiceURL
was generated by the server, as described above under "connector addresses generated by the server", then the client will need to obtain it directly or indirectly from the server. Typically, the server makes the JMXServiceURL
available by storing it in a file or a lookup service.
If the JMXServiceURL
uses the directory syntax, as described above under "connector addresses based on directory entries", 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 whatsit-agent-connector
in the RMI registry on host myhost
, then client and server can both know that the appropriate JMXServiceURL
is:
service:jmx:rmi:///jndi/rmi://myhost/whatsit-agent-connector
If you have an RMI stub of type RMIServer
, you can construct an RMI connection directly by using the appropriate constructor of RMIConnector
.
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. Java RMI Guide explains this in more detail.
Class | Description |
---|---|
RMIConnection | RMI object used to forward an MBeanServer request from a client to its MBeanServer implementation on the server side. |
RMIConnectionImpl | Implementation of the RMIConnection interface. |
RMIConnectionImpl_Stub | RMIConnectionImpl remote stub. |
RMIConnector | A connection to a remote RMI connector. |
RMIConnectorServer | A JMX API connector server that creates RMI-based connections from remote clients. |
RMIJRMPServerImpl | An RMIServer object that is exported through JRMP and that creates client connections as RMI objects exported through JRMP. |
RMIServer | RMI object used to establish connections to an RMI connector. |
RMIServerImpl | An RMI object representing a connector server. |
RMIServerImpl_Stub | RMIServerImpl remote stub. |
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.management.rmi/javax/management/remote/rmi/package-summary.html