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 {@link javax.management.remote.JMXServiceURL
- 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:
- -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 {@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.
- -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
- 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 {@link
- javax.management.remote.rmi.RMIServerImpl 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 {@link
- javax.management.remote.rmi.RMIJRMPServerImpl
- 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 {@link javax.naming.InitialContext#bind
- 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 {@link
- javax.management.remote.rmi.RMIServerImpl#toStub 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 {@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.
An RMI connector client is usually constructed using {@link
- javax.management.remote.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 {@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}.
- -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 Dynamic - code downloading using Java RMI explains this in more - detail.
- - - @see - Java™ Remote Method - Invocation (RMI) - - @see - Java Naming and Directory Interface™ (JNDI) - - @see RFC 2045, - section 6.8, "Base64 Content-Transfer-Encoding" - - - @since 1.5 - - - --- /dev/null 2017-02-01 16:12:57.000000000 +0000 +++ new/jdk/src/java.management.rmi/share/classes/javax/management/remote/rmi/package.html 2017-02-01 16:12:57.000000000 +0000 @@ -0,0 +1,340 @@ + + +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 {@link javax.management.remote.JMXServiceURL
+ 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:
+ +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 {@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.
+ +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
+ 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 {@link
+ javax.management.remote.rmi.RMIServerImpl 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 {@link
+ javax.management.remote.rmi.RMIJRMPServerImpl
+ 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 {@link javax.naming.InitialContext#bind
+ 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 {@link
+ javax.management.remote.rmi.RMIServerImpl#toStub 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 {@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.
An RMI connector client is usually constructed using {@link
+ javax.management.remote.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 {@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}.
+ +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 Dynamic + code downloading using Java RMI explains this in more + detail.
+ + + @see + Java™ Remote Method + Invocation (RMI) + + @see + Java Naming and Directory Interface™ (JNDI) + + @see RFC 2045, + section 6.8, "Base64 Content-Transfer-Encoding" + + + @since 1.5 + + +