|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES All Classes |
See:
Description
Interface Summary | |
---|---|
RMIConnection | RMI object used to forward an MBeanServer request from a client to its MBeanServer implementation on the server side. |
RMIServer | RMI object used to establish connections to an RMI connector. |
Class Summary | |
---|---|
RMIConnectionImpl | Implementation of the RMIConnection interface. |
RMIConnectionImpl_Stub | |
RMIConnector | A connection to a remote RMI connector. |
RMIConnectorServer | A JMX API connector server that creates RMI-based connections from remote clients. |
RMIIIOPServerImpl | An RMIServerImpl that is exported through IIOP and that
creates client connections as RMI objects exported through IIOP. |
RMIJRMPServerImpl | An RMIServer object that is exported through JRMP and that
creates client connections as RMI objects exported through JRMP. |
RMIServerImpl | An RMI object representing a connector server. |
RMIServerImpl_Stub |
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 both the JRMP and the IIOP transports 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), or iiop
for a connector that
uses RMI/IIOP.
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 (JRMP or IIOP) by specifying
rmi
or iiop
in the
protocol
part of the
serviceURL
when creating the connector server. You
can also create specialised 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 the serviceURL
looks like:
service:jmx:iiop://host:port
then the connector server will generate an RMIIIOPServerImpl
and the returned
JMXServiceURL
looks like:
service:jmx:iiop://host:port/ior/IOR:XXXX
where IOR:XXXX
is the standard CORBA
encoding of the Interoperable Object Reference for the
generated object.
If there is no serviceURL
, there must be a
user-provided RMIServerImpl
. If the toStub
method on this object returns an instance of Stub
, then the connector server will generate
a JMXServiceURL
using the iiop
form above. Otherwise, it 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 one of these two
forms:
service:jmx:rmi://host:port/jndi/jndi-name
service:jmx:iiop://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
or iiop
) and, for
rmi
, 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:iiop://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that
then the connector server will generate an
RMIIIOPServerImpl
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:iiop://ignoredhost/jndi/cn=this,ou=that
then the connector server will generate an
RMIIIOPServerImpl
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:iiop:///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
or
iiop
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
.
When using the IIOP transport, the client and server can
specify what ORB to use
with the attribute java.naming.corba.orb
.
Connection to the ORB happens at start
time
for the connector server, and at connect
time for the connector client.
If the java.naming.corba.orb
attribute is contained
in the environment Map, then its value (an ORB
), is used to connect the IIOP Stubs.
Otherwise, a new org.omg.CORBA.ORB is created by calling 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.
If the java.naming.corba.orb
attribute is
specified and does not point to an ORB
,
then an
will be thrown.IllegalArgumentException
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.
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES All Classes |
Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.