JavaTM 2 Platform
Standard Ed. 5.0

Package javax.management.remote

Interfaces for remote access to JMX MBean servers.

See:
          Description

Interface Summary
JMXAuthenticator Interface to define how remote credentials are converted into a JAAS Subject.
JMXConnector The client end of a JMX API connector.
JMXConnectorProvider A provider for creating JMX API connector clients using a given protocol.
JMXConnectorServerMBean MBean interface for connector servers.
JMXConnectorServerProvider A provider for creating JMX API connector servers using a given protocol.
MBeanServerForwarder An object of this class implements the MBeanServer interface and wraps another object that also implements that interface.
 

Class Summary
JMXConnectionNotification Notification emitted when a client connection is opened or closed or when notifications are lost.
JMXConnectorFactory Factory to create JMX API connector clients.
JMXConnectorServer Superclass of every connector server.
JMXConnectorServerFactory Factory to create JMX API connector servers.
JMXPrincipal The identity of a remote client of the JMX Remote API.
JMXServiceURL The address of a JMX API connector server.
NotificationResult Result of a query for buffered notifications.
SubjectDelegationPermission Permission required by an authentication identity to perform operations on behalf of an authorization identity.
TargetedNotification A (Notification, Listener ID) pair.
 

Exception Summary
JMXProviderException Exception thrown by JMXConnectorFactory when a provider exists for the required protocol but cannot be used for some reason.
JMXServerErrorException Exception thrown as the result of a remote MBeanServer method invocation when an Error is thrown while processing the invocation in the remote MBean server.
 

Package javax.management.remote Description

Interfaces for remote access to JMX MBean servers. This package defines the essential interfaces for making a JMX MBean server manageable remotely. The companion document JMX Remote API completes the specification of this interface. It should be available as a PDF document in the same place as this Javadoc specification.

The JMX specification defines the notion of connectors. A connector is attached to a JMX API MBean server and makes it accessible to remote Java clients. The client end of a connector exports essentially the same interface as the MBean server, specifically the MBeanServerConnection interface.

A connector makes an MBean server remotely accessible through a given protocol.
The JMX Remote API defines a standard connector, the RMI Connector, which provides remote access to an MBeanServer through RMI.
The JMX Remote API also defines an optional protocol called JMXMP (JMX Message Protocol). JMXMP is based on serialized Java objects (defined in the optional package javax.management.remote.message) over a TCP connection. The connector that implements this protocol is called the JMXMP Connector. User-defined connector protocols are also possible using the JMXConnectorFactory and, optionally, the Generic Connector (javax.management.remote.generic).

Connector addresses

Typically, a connector has an address, represented by the class JMXServiceURL. An address for the JMXMP Connector looks like this:

      service:jmx:jmxmp://myhost:9876
      

An address for the RMI Connector can take several forms, as detailed in the documentation for the package javax.management.remote.rmi.

Creating a connector server

A connector server is created by constructing an instance of a subclass of JMXConnectorServer. Usually, this instance is created using the method JMXConnectorServerFactory.newJMXConnectorServer.

Typically, a connector server is associated with an MBean server either by registering it in that MBean server, or by supplying the MBean server as a parameter when creating the connector server.

Creating a connector client

A connector client is usually created by supplying a JMXServiceURL to the JMXConnectorFactory.connect method.

For more specialized uses, a connector client can be created by directly instantiating a class that implements the JMXConnector interface, for example the class RMIConnector.

Additional client or server parameters

When creating a connector client or server, it is possible to supply an object of type Map that defines additional parameters. Each entry in this Map has a key that is a string and an associated value whose type is appropriate for that key. The standard keys defined by the JMX Remote API all begin with the string "jmx.remote.". The document JMX Remote API lists these standard keys.

Connection identifiers

Every connection opened by a connector server has a string identifier, called its connection id. This identifier appears in the JMXConnectionNotification events emitted by the connector server, in the list returned by JMXConnectorServerMBean#getConnectionIds(), and in the value returned by the client's getConnectionId() method.

Conventionally, a connection ID looks something like this:

jmxmp://clienthost:6789 clientname xxxyyyzzz
      

The formal grammar for connection ids that follow this convention is as follows (using the grammar notation from The Java Language Specification, Second Edition):

ConnectionId:
    Protocol : ClientAddressopt Space ClientIdopt Space ArbitraryText

ClientAddress:
    // HostAddress ClientPortopt

ClientPort
    : HostPort
      

The Protocol is a protocol that would be recognized by JMXConnectorFactory.

The ClientAddress is the address and port of the connecting client, if these can be determined, otherwise nothing. The HostAddress is the Internet address of the host that the client is connecting from, in numeric or DNS form. Numeric IPv6 addresses are enclosed in square brackets []. The HostPort is the decimal port number that the client is connecting from.

The ClientId is the identity of the client entity, typically a string returned by JMXPrincipal.getName(). This string must not contain spaces.

The ArbitraryText is any additional text that the connector server adds when creating the client id. At a minimum, it must be enough to distinguish this connection ID from the ID of any other connection currently opened by this connector server.


JavaTM 2 Platform
Standard Ed. 5.0

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.