Module java.management

# Package javax.management.remote

package javax.management.remote

Interfaces for remote access to JMX MBean servers. This package defines the essential interfaces for making a JMX MBean server manageable remotely. The specification of this functionality is completed by Part III of the JMX Specification, version 1.4

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 allows the use of different type of connectors:

- 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 connector called JMXMP Connector implementing the JMX Message Protocol (JMXMP). As it is optional, it is not part of this bundle (see note below).
- User-defined connector protocols are also possible using the `JMXConnectorFactory` and, optionally, the Generic Connector (not part of this bundle, see note below).

Note: the optional packages implementing the optional part of the JMX Remote API are not included in the Java SE Platform but are available from the JMX Remote API Reference Implementation.

## Connector addresses

Typically, a connector server has an address, represented by the class `JMXServiceURL`. An address for the RMI Connector can look like this:

          service:jmx:rmi:///jndi/rmi://myhost:1099/myname

In this `JMXServiceURL`, the first `rmi:` specifies the RMI connector, while the second `rmi:` specifies the RMI registry into which the RMI connector server has stored its stub.

The example above shows only one form of address. 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 the `JMXServiceURL` of the connector server to connect to 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 `getConnectionIds()`, and in the value returned by the client's `getConnectionId()` method.

As an example, a connection ID can look something like this:

    rmi://192.18.1.9 username 1

The formal grammar for connection ids that follow this convention is as follows (using the grammar notation from section 2.4 of The Java Language Specification):

    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.

Since:
  1.5
See Also:
  - JMX Specification, version 1.4

- Related Packages
  Module
  Package
  Description
  java.management
  javax.management
  Provides the core classes for the Java Management Extensions.
  java.management.rmi
  javax.management.remote.rmi
  The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.
- Class
  Description
  JMXAddressable
  Implemented by objects that can have a `JMXServiceURL` address.
  JMXAuthenticator
  Interface to define how remote credentials are converted into a JAAS Subject.
  JMXConnectionNotification
  Notification emitted when a client connection is opened or closed or when notifications are lost.
  JMXConnector
  The client end of a JMX API connector.
  JMXConnectorFactory
  Factory to create JMX API connector clients.
  JMXConnectorProvider
  A provider for creating JMX API connector clients using a given protocol.
  JMXConnectorServer
  Superclass of every connector server.
  JMXConnectorServerFactory
  Factory to create JMX API connector servers.
  JMXConnectorServerMBean
  MBean interface for connector servers.
  JMXConnectorServerProvider
  A provider for creating JMX API connector servers using a given protocol.
  JMXPrincipal
  The identity of a remote client of the JMX Remote API.
  JMXProviderException
  Exception thrown by `JMXConnectorFactory` and `JMXConnectorServerFactory` 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.
  JMXServiceURL
  The address of a JMX API connector server.
  MBeanServerForwarder
  An object of this class implements the MBeanServer interface and wraps another object that also implements that interface.
  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.