APIdia Launch Partner
Top Description Fields Constructors Methods
javax.management.remote.rmi

public Class RMIConnectorServer

extends JMXConnectorServer
Class Inheritance
Imports
com.sun.jmx.remote.security.MBeanServerFileAccessController, com.sun.jmx.remote.util.ClassLogger, .EnvHelp, java.io.ByteArrayOutputStream, .IOException, .ObjectInputFilter, .ObjectOutputStream, java.net.MalformedURLException, java.rmi.server.RMIClientSocketFactory, .RMIServerSocketFactory, java.util.Collections, .HashMap, .HashSet, .Hashtable, .Map, .Set, javax.management.InstanceNotFoundException, .MBeanServer, javax.management.remote.JMXAuthenticator, .JMXConnectionNotification, .JMXConnector, .JMXConnectorServer, .JMXServiceURL, .MBeanServerForwarder, javax.naming.InitialContext, .NamingException

A JMX API connector server that creates RMI-based connections from remote clients. Usually, such connector servers are made using JMXConnectorServerFactory. However, specialized applications can use this class directly, for example with an RMIServerImpl object.

Since
1.5

Field Summary

Modifier and TypeField and Description
private JMXServiceURL
address

private final Map<String, ?>
attributes

private String
boundJndiUrl

private static final int
CREATED

public static final String
CREDENTIALS_FILTER_PATTERN

Name of the attribute that specifies an ObjectInputFilter pattern string to filter classes acceptable for RMIServer.newClient() remote method call.

private ClassLoader
defaultClassLoader

private static final char[]
intToAlpha

This array is a lookup table that translates 6-bit positive integer index values into their "Base64 Alphabet" equivalents as specified in Table 1 of RFC 2045.

public static final String
JNDI_REBIND_ATTRIBUTE

Name of the attribute that specifies whether the RMIServer stub that represents an RMI connector server should override an existing stub at the same address.

private static ClassLogger
logger

Hides javax.management.NotificationBroadcasterSupport.logger.

private static final Set<RMIConnectorServer>
openedServers

public static final String
RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the RMIClientSocketFactory for the RMI objects created in conjunction with this connector.

public static final String
RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the RMIServerSocketFactory for the RMI objects created in conjunction with this connector.

private RMIServerImpl
rmiServerImpl

public static final String
SERIAL_FILTER_PATTERN

This attribute defines a pattern from which to create a java.io.ObjectInputFilter that will be used when deserializing objects sent to the JMXConnectorServer by any client.

private static final int
STARTED

private int
state

private static final int
STOPPED

Inherited from javax.management.remote.JMXConnectorServer:
AUTHENTICATOR

Constructor Summary

AccessConstructor and Description
public
RMIConnectorServer(JMXServiceURL
the URL defining how to create the connector server. Cannot be null.
url, Map<String, ?>
attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.
environment)

Makes an RMIConnectorServer.

public
RMIConnectorServer(JMXServiceURL
the URL defining how to create the connector server. Cannot be null.
url, Map<String, ?>
attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.
environment, MBeanServer
the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.
mbeanServer)

Makes an RMIConnectorServer for the given MBean server.

public
RMIConnectorServer(JMXServiceURL
the URL defining how to create the connector server. Cannot be null.
url, Map<String, ?>
attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.
environment, RMIServerImpl
An implementation of the RMIServer interface, consistent with the protocol type specified in url. If this parameter is non null, the protocol type specified by url is not constrained, and is assumed to be valid. Otherwise, only "rmi" will be recognized.
rmiServerImpl, MBeanServer
the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.
mbeanServer)

Makes an RMIConnectorServer for the given MBean server.

Method Summary

Modifier and TypeMethod and Description
pack-priv void
bind(String
URL of the stub in the registry, extracted from the JMXServiceURL.
jndiUrl, Hashtable<?, ?>
A Hashtable containing environment parameters, built from the Map specified at this object creation.
attributes, RMIServer
The object to bind in the registry
rmiServer, boolean
true if the object must be rebound.
rebind)

Bind a stub to a registry.

private static String
byteArrayToBase64(byte[] a)

protected void
connectionClosed(String connectionId, String message, Object userData)

Overrides javax.management.remote.JMXConnectorServer.connectionClosed.

Called by a subclass when a client connection is closed normally.

protected void
connectionFailed(String connectionId, String message, Object userData)

Overrides javax.management.remote.JMXConnectorServer.connectionFailed.

Called by a subclass when a client connection fails.

protected void
connectionOpened(String connectionId, String message, Object userData)

Overrides javax.management.remote.JMXConnectorServer.connectionOpened.

Called by a subclass when a new client connection is opened.

pack-priv static String
encodeJRMPStub(RMIServer rmiServer, Map<String, ?> env)

pack-priv static String
encodeStub(RMIServer rmiServer, Map<String, ?> env)

Returns the IOR of the given rmiServer.

private void
encodeStubInAddress(RMIServer
The stub object to encode in the URL
rmiServer, Map<String, ?>
A Map containing environment parameters, built from the Map specified at this object creation.
attributes)

Encode a stub into the JMXServiceURL.

public JMXServiceURL
getAddress()

Implements javax.management.remote.JMXConnectorServerMBean.getAddress, javax.management.remote.JMXAddressable.getAddress.

The address of this connector server.

public Map<String, ?>
getAttributes()

Implements javax.management.remote.JMXConnectorServerMBean.getAttributes.

The attributes for this connector server.

public synchronized boolean
isActive()

Implements javax.management.remote.JMXConnectorServerMBean.isActive.

Determines whether the connector server is active.

private static IOException
newIOException(String message, Throwable cause)

Construct a new IOException with a nested exception.

private static RMIServerImpl
newJRMPServer(Map<String, ?> env, int port)

pack-priv RMIServerImpl
newServer()

Creates a new RMIServerImpl.

private static RMIServer
objectToBind(RMIServerImpl rmiServer, Map<String, ?> env)

Object that we will bind to the registry.

public synchronized void
setMBeanServerForwarder(MBeanServerForwarder mbsf)

Overrides javax.management.remote.JMXConnectorServer.setMBeanServerForwarder.

Implements javax.management.remote.JMXConnectorServerMBean.setMBeanServerForwarder.

Inserts an object that intercepts requests for the MBean server that arrive through this connector server.

public synchronized void
start()

Implements javax.management.remote.JMXConnectorServerMBean.start.

Activates the connector server, that is starts listening for client connections.

public void
stop()

Implements javax.management.remote.JMXConnectorServerMBean.stop.

Deactivates the connector server, that is, stops listening for client connections.

public JMXConnector

Returns:

a client stub that can be used to make a new connection to this connector server.
toJMXConnector(Map<String, ?>
client connection parameters of the same sort that could be provided to JMXConnector.connect(Map). Can be null, which is equivalent to an empty map.
env)

Overrides javax.management.remote.JMXConnectorServer.toJMXConnector.

Implements javax.management.remote.JMXConnectorServerMBean.toJMXConnector.

Returns a client stub for this connector server.

Inherited from javax.management.remote.JMXConnectorServer:
getConnectionIdsgetMBeanServergetNotificationInfopostDeregisterpostRegisterpreDeregisterpreRegister

Field Detail

addressback to summary
private JMXServiceURL address
attributesback to summary
private final Map<String, ?> attributes
boundJndiUrlback to summary
private String boundJndiUrl
CREATEDback to summary
private static final int CREATED
CREDENTIALS_FILTER_PATTERNback to summary
public static final String CREDENTIALS_FILTER_PATTERN

Name of the attribute that specifies an ObjectInputFilter pattern string to filter classes acceptable for RMIServer.newClient() remote method call.

The filter pattern must be in same format as used in java.io.ObjectInputFilter.Config#createFilter

This list of classes allowed by filter should correspond to the transitive closure of the credentials class (or classes) used by the installed JMXAuthenticator associated with the RMIServer implementation. If the attribute is not set then any class is deemed acceptable.

Since
10
See Also
ObjectInputFilter
defaultClassLoaderback to summary
private ClassLoader defaultClassLoader
intToAlphaback to summary
private static final char[] intToAlpha

This array is a lookup table that translates 6-bit positive integer index values into their "Base64 Alphabet" equivalents as specified in Table 1 of RFC 2045.

JNDI_REBIND_ATTRIBUTEback to summary
public static final String JNDI_REBIND_ATTRIBUTE

Name of the attribute that specifies whether the RMIServer stub that represents an RMI connector server should override an existing stub at the same address. The value associated with this attribute, if any, should be a string that is equal, ignoring case, to "true" or "false". The default value is false.

loggerback to summary
private static ClassLogger logger

Hides javax.management.NotificationBroadcasterSupport.logger.

openedServersback to summary
private static final Set<RMIConnectorServer> openedServers
RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTEback to summary
public static final String RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the RMIClientSocketFactory for the RMI objects created in conjunction with this connector. The value associated with this attribute must be of type RMIClientSocketFactory and can only be specified in the Map argument supplied when creating a connector server.

RMI_SERVER_SOCKET_FACTORY_ATTRIBUTEback to summary
public static final String RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the RMIServerSocketFactory for the RMI objects created in conjunction with this connector. The value associated with this attribute must be of type RMIServerSocketFactory and can only be specified in the Map argument supplied when creating a connector server.

rmiServerImplback to summary
private RMIServerImpl rmiServerImpl
SERIAL_FILTER_PATTERNback to summary
public static final String SERIAL_FILTER_PATTERN

This attribute defines a pattern from which to create a java.io.ObjectInputFilter that will be used when deserializing objects sent to the JMXConnectorServer by any client.

The filter will be called for any class found in the serialized stream sent to server by client, including all JMX defined classes (such as javax.management.ObjectName), all method parameters, and, if present in the stream, all classes transitively referred by the serial form of any deserialized object. The pattern must be in same format as used in java.io.ObjectInputFilter.Config#createFilter. It may define an allow-list of permitted classes, a reject-list of rejected classes, a maximum depth for the deserialized objects, etc.

To be functional, the filter should allow at least all the concrete types in the transitive closure of all objects that might get serialized when serializing all JMX classes referred as parameters in the javax.management.remote.rmi.RMIConnection interface, plus all classes that a client might need to transmit wrapped in marshalled objects in order to interoperate with the MBeans registered in the MBeanServer. That would potentially include all the concrete JMX OpenTypes and the classes they use in their serial form.

Care must be taken when defining such a filter, as defining an allow-list that is too narrow or a reject-list that is too wide may prevent legitimate clients from interoperating with the JMXConnectorServer.

Since
10
STARTEDback to summary
private static final int STARTED
stateback to summary
private int state
STOPPEDback to summary
private static final int STOPPED

Constructor Detail

RMIConnectorServerback to summary
public RMIConnectorServer(JMXServiceURL url, Map<String, ?> environment) throws IOException

Makes an RMIConnectorServer. This is equivalent to calling RMIConnectorServer(directoryURL,environment,null,null)

Parameters
url:JMXServiceURL

the URL defining how to create the connector server. Cannot be null.

environment:Map<String, ?>

attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.

Exceptions
IOException:
if the connector server cannot be created for some reason or if it is inevitable that its start method will fail.
IllegalArgumentException:
if url is null.
MalformedURLException:
if url does not conform to the syntax for an RMI connector, or if its protocol is not recognized by this implementation. Only "rmi" is valid when this constructor is used.
RMIConnectorServerback to summary
public RMIConnectorServer(JMXServiceURL url, Map<String, ?> environment, MBeanServer mbeanServer) throws IOException

Makes an RMIConnectorServer for the given MBean server. This is equivalent to calling RMIConnectorServer(directoryURL,environment,null,mbeanServer)

Parameters
url:JMXServiceURL

the URL defining how to create the connector server. Cannot be null.

environment:Map<String, ?>

attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.

mbeanServer:MBeanServer

the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.

Exceptions
IOException:
if the connector server cannot be created for some reason or if it is inevitable that its start method will fail.
IllegalArgumentException:
if url is null.
MalformedURLException:
if url does not conform to the syntax for an RMI connector, or if its protocol is not recognized by this implementation. Only "rmi" is valid when this constructor is used.
RMIConnectorServerback to summary
public RMIConnectorServer(JMXServiceURL url, Map<String, ?> environment, RMIServerImpl rmiServerImpl, MBeanServer mbeanServer) throws IOException

Makes an RMIConnectorServer for the given MBean server.

Parameters
url:JMXServiceURL

the URL defining how to create the connector server. Cannot be null.

environment:Map<String, ?>

attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.

rmiServerImpl:RMIServerImpl

An implementation of the RMIServer interface, consistent with the protocol type specified in url. If this parameter is non null, the protocol type specified by url is not constrained, and is assumed to be valid. Otherwise, only "rmi" will be recognized.

mbeanServer:MBeanServer

the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.

Exceptions
IOException:
if the connector server cannot be created for some reason or if it is inevitable that its start method will fail.
IllegalArgumentException:
if url is null.
MalformedURLException:
if url does not conform to the syntax for an RMI connector, or if its protocol is not recognized by this implementation. Only "rmi" is recognized when rmiServerImpl is null.
See Also
start

Method Detail

bindback to summary
pack-priv void bind(String jndiUrl, Hashtable<?, ?> attributes, RMIServer rmiServer, boolean rebind) throws NamingException, MalformedURLException

Bind a stub to a registry.

Parameters
jndiUrl:String

URL of the stub in the registry, extracted from the JMXServiceURL.

attributes:Hashtable<?, ?>

A Hashtable containing environment parameters, built from the Map specified at this object creation.

rmiServer:RMIServer

The object to bind in the registry

rebind:boolean

true if the object must be rebound.

byteArrayToBase64back to summary
private static String byteArrayToBase64(byte[] a)
connectionClosedback to summary
protected void connectionClosed(String connectionId, String message, Object userData)

Overrides javax.management.remote.JMXConnectorServer.connectionClosed.

Doc from javax.management.remote.JMXConnectorServer.connectionClosed.

Called by a subclass when a client connection is closed normally. Removes connectionId from the list returned by getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification#CLOSED.

Annotations
@Override
connectionFailedback to summary
protected void connectionFailed(String connectionId, String message, Object userData)

Overrides javax.management.remote.JMXConnectorServer.connectionFailed.

Doc from javax.management.remote.JMXConnectorServer.connectionFailed.

Called by a subclass when a client connection fails. Removes connectionId from the list returned by getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification#FAILED.

Annotations
@Override
connectionOpenedback to summary
protected void connectionOpened(String connectionId, String message, Object userData)

Overrides javax.management.remote.JMXConnectorServer.connectionOpened.

Doc from javax.management.remote.JMXConnectorServer.connectionOpened.

Called by a subclass when a new client connection is opened. Adds connectionId to the list returned by getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification#OPENED.

Annotations
@Override
encodeJRMPStubback to summary
pack-priv static String encodeJRMPStub(RMIServer rmiServer, Map<String, ?> env) throws IOException
encodeStubback to summary
pack-priv static String encodeStub(RMIServer rmiServer, Map<String, ?> env) throws IOException

Returns the IOR of the given rmiServer.

encodeStubInAddressback to summary
private void encodeStubInAddress(RMIServer rmiServer, Map<String, ?> attributes) throws IOException

Encode a stub into the JMXServiceURL.

Parameters
rmiServer:RMIServer

The stub object to encode in the URL

attributes:Map<String, ?>

A Map containing environment parameters, built from the Map specified at this object creation.

getAddressback to summary
public JMXServiceURL getAddress()

Implements javax.management.remote.JMXConnectorServerMBean.getAddress, javax.management.remote.JMXAddressable.getAddress.

Doc from javax.management.remote.JMXConnectorServerMBean.getAddress.

The address of this connector server.

The address returned may not be the exact original JMXServiceURL that was supplied when creating the connector server, since the original address may not always be complete. For example the port number may be dynamically allocated when starting the connector server. Instead the address returned is the actual JMXServiceURL of the JMXConnectorServer. This is the address that clients supply to JMXConnectorFactory#connect(JMXServiceURL).

Note that the address returned may be null if the JMXConnectorServer is not yet active.

getAttributesback to summary
public Map<String, ?> getAttributes()

Implements javax.management.remote.JMXConnectorServerMBean.getAttributes.

Doc from javax.management.remote.JMXConnectorServerMBean.getAttributes.

The attributes for this connector server.

isActiveback to summary
public synchronized boolean isActive()

Implements javax.management.remote.JMXConnectorServerMBean.isActive.

Doc from javax.management.remote.JMXConnectorServerMBean.isActive.

Determines whether the connector server is active. A connector server starts being active when its start method returns successfully and remains active until either its stop method is called or the connector server fails.

newIOExceptionback to summary
private static IOException newIOException(String message, Throwable cause)

Construct a new IOException with a nested exception. The nested exception is set only if JDK >= 1.4

newJRMPServerback to summary
private static RMIServerImpl newJRMPServer(Map<String, ?> env, int port) throws IOException
newServerback to summary
pack-priv RMIServerImpl newServer() throws IOException

Creates a new RMIServerImpl.

objectToBindback to summary
private static RMIServer objectToBind(RMIServerImpl rmiServer, Map<String, ?> env) throws IOException

Object that we will bind to the registry. This object is a stub connected to our RMIServerImpl.

setMBeanServerForwarderback to summary
public synchronized void setMBeanServerForwarder(MBeanServerForwarder mbsf)

Overrides javax.management.remote.JMXConnectorServer.setMBeanServerForwarder.

Implements javax.management.remote.JMXConnectorServerMBean.setMBeanServerForwarder.

Doc from javax.management.remote.JMXConnectorServerMBean.setMBeanServerForwarder.

Inserts an object that intercepts requests for the MBean server that arrive through this connector server. This object will be supplied as the MBeanServer for any new connection created by this connector server. Existing connections are unaffected.

This method can be called more than once with different MBeanServerForwarder objects. The result is a chain of forwarders. The last forwarder added is the first in the chain. In more detail:

  • If this connector server is already associated with an MBeanServer object, then that object is given to mbsf.setMBeanServer. If doing so produces an exception, this method throws the same exception without any other effect.

  • If this connector is not already associated with an MBeanServer object, or if the mbsf.setMBeanServer call just mentioned succeeds, then mbsf becomes this connector server's MBeanServer.

Annotations
@Override
startback to summary
public synchronized void start() throws IOException

Implements javax.management.remote.JMXConnectorServerMBean.start.

Activates the connector server, that is starts listening for client connections. Calling this method when the connector server is already active has no effect. Calling this method when the connector server has been stopped will generate an IOException.

The behavior of this method when called for the first time depends on the parameters that were supplied at construction, as described below.

First, an object of a subclass of RMIServerImpl is required, to export the connector server through RMI:

  • If an RMIServerImpl was supplied to the constructor, it is used.
  • Otherwise, if the JMXServiceURL was null, or its protocol part was rmi, an object of type RMIJRMPServerImpl is created.
  • Otherwise, the implementation can create an implementation-specific RMIServerImpl or it can throw MalformedURLException.

If the given address includes a JNDI directory URL as specified in the package documentation for javax.management.remote.rmi, then this RMIConnectorServer will bootstrap by binding the RMIServerImpl to the given address.

If the URL path part of the JMXServiceURL was empty or a single slash (/), then the RMI object will not be bound to a directory. Instead, a reference to it will be encoded in the URL path of the RMIConnectorServer address (returned by getAddress()). The encodings for rmi are described in the package documentation for javax.management.remote.rmi.

The behavior when the URL path is neither empty nor a JNDI directory URL, or when the protocol is not rmi, is implementation defined, and may include throwing MalformedURLException when the connector server is created or when it is started.

Exceptions
IOException:
if the connector server cannot be started.
IllegalStateException:
if the connector server has not been attached to an MBean server.
stopback to summary
public void stop() throws IOException

Implements javax.management.remote.JMXConnectorServerMBean.stop.

Deactivates the connector server, that is, stops listening for client connections. Calling this method will also close all client connections that were made by this server. After this method returns, whether normally or with an exception, the connector server will not create any new client connections.

Once a connector server has been stopped, it cannot be started again.

Calling this method when the connector server has already been stopped has no effect. Calling this method when the connector server has not yet been started will disable the connector server object permanently.

If closing a client connection produces an exception, that exception is not thrown from this method. A JMXConnectionNotification is emitted from this MBean with the connection ID of the connection that could not be closed.

Closing a connector server is a potentially slow operation. For example, if a client machine with an open connection has crashed, the close operation might have to wait for a network protocol timeout. Callers that do not want to block in a close operation should do it in a separate thread.

This method calls the method close on the connector server's RMIServerImpl object.

If the RMIServerImpl was bound to a JNDI directory by the start method, it is unbound from the directory by this method.

Exceptions
IOException:
if the server cannot be closed cleanly, or if the RMIServerImpl cannot be unbound from the directory. When this exception is thrown, the server has already attempted to close all client connections, if appropriate; to call RMIServerImpl#close(); and to unbind the RMIServerImpl from its directory, if appropriate. All client connections are closed except possibly those that generated exceptions when the server attempted to close them.
toJMXConnectorback to summary
public JMXConnector toJMXConnector(Map<String, ?> env) throws IOException

Overrides javax.management.remote.JMXConnectorServer.toJMXConnector.

Implements javax.management.remote.JMXConnectorServerMBean.toJMXConnector.

Returns a client stub for this connector server. A client stub is a serializable object whose connect method can be used to make one new connection to this connector server.

Parameters
env:Map<String, ?>

client connection parameters of the same sort that could be provided to JMXConnector.connect(Map). Can be null, which is equivalent to an empty map.

Returns:JMXConnector

a client stub that can be used to make a new connection to this connector server.

Exceptions
IOException:
if a communications problem means that a stub cannot be created.
UnsupportedOperationException:
if this connector server does not support the generation of client stubs.
IllegalStateException:
if the JMXConnectorServer is not started (see isActive()).