/* * Copyright (c) 2002, 2025, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /** *

Interfaces for remote access to * JMX MBean servers. * This package defines the essential interfaces for making a JMX * MBean server manageable remotely.

* *

JMX 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 {@link * javax.management.MBeanServerConnection MBeanServerConnection} * interface.

* *

A connector makes an MBean server remotely accessible through * a given protocol. * *

* *

Connector addresses

* *

Typically, a connector server has an address, represented by the * class {@link javax.management.remote.JMXServiceURL * 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 {@link * javax.management.remote.JMXConnectorServer * JMXConnectorServer}. Usually, this instance is created * using the method {@link * javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer(JMXServiceURL, * java.util.Map, javax.management.MBeanServer) * 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 {@link * javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL) * JMXConnectorFactory.connect} method.

* *

For more specialized uses, a connector client can be created * by directly instantiating a class that implements the {@link * javax.management.remote.JMXConnector 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 {@link java.util.Map 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 {@link * javax.management.remote.JMXConnectionNotification * JMXConnectionNotification} events emitted by the connector * server, in the list returned by {@link * javax.management.remote.JMXConnectorServerMBean#getConnectionIds() * getConnectionIds()}, and in the value * returned by the client's {@link * javax.management.remote.JMXConnector#getConnectionId() * 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 {@link * javax.management.remote.JMXConnectorFactory * 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 {@link * javax.management.remote.JMXPrincipal#getName() * 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.

* * * @see * JMX Specification, version 1.4 * * @since 1.5 */ package javax.management.remote;