jdk/src/share/classes/javax/management/remote/package.html - edge/openjdk - Git at Google


            
            <html>

            
            <head>

            
                <title>JMX<sup><font size="-2">TM</font></sup> Remote API.</title>

            
            <!--

            
            Copyright (c) 2002, 2011, 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.

            
            -->

            
            </head>

            
            <body bgcolor="white">

            
                  <p>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

            
                   <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">

            
            	JMX Specification, version 1.4</a> PDF document.</p>


                  <p>The JMX specification defines the notion of <b>connectors</b>.

            
            	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.</p>


                  <p>A connector makes an MBean server remotely accessible through

            
            	a given protocol. The JMX Remote API allows the use of different

            
                    type of connectors:


                  <ul>

            
                   <li>The JMX Remote API defines a standard connector,

            
            	the <b>RMI Connector</b>, which provides remote access to an

            
                    MBeanServer through RMI.


                   <li>The JMX Remote API also defines an optional connector called

            
                    <b>JMXMP Connector</b> implementing the JMX Message Protocol

            
            	(JMXMP). As it is optional, it is not part of this bundle (see

            
            	note below).


                   <li>User-defined connector protocols are also possible using the

            
            	{@link javax.management.remote.JMXConnectorFactory

            
            	JMXConnectorFactory} and, optionally, the Generic Connector

            
            	(not part of this bundle, see note below).</p>

            
                  </ul>


                  <p><u>Note</u>: the optional packages implementing

            
                    the optional part of the <em>JMX Remote API</em>

            
                    are not included in the <em>Java SE Platform</em>

            
                    but are available from the <em>JMX Remote API

            
            	<a href="http://java.sun.com/products/JavaManagement/download.html">

            
            	Reference Implementation</a></em>.</p>


                  <h3>Connector addresses</h3>


                  <p>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:</p>


                  <pre>

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

            
                  </pre>


                  <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>

            
                    specifies the RMI connector, while the second <code>rmi:</code>

            
                    specifies the RMI registry into which the RMI connector server

            
                    has stored its stub.


                  <p>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

            
            	<code>{@link javax.management.remote.rmi}</code>.</p>


                  <h3>Creating a connector server</h3>


                  <p>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}.</p>


                  <p>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.</p>


                  <h3>Creating a connector client</h3>


                  <p>A connector client is usually created by supplying the

            
            	<code>JMXServiceURL</code> of the connector server to connect to

            
                    to the {@link

            
            	javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)

            
            	JMXConnectorFactory.connect} method.</p>


                  <p>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 {@link

            
            	javax.management.remote.rmi.RMIConnector

            
            	RMIConnector}.</p>


                  <h3>Additional client or server parameters</h3>


                  <p>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 "<code>jmx.remote.</code>".  The document

            
            	<em>JMX Remote API</em> lists these standard keys.</p>


                  <h3>Connection identifiers</h3>


                  <p>Every connection opened by a connector server has a string

            
            	identifier, called its <b>connection id</b>.  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.</p>


                  <p>As an example, a connection ID can look something like this:</p>


                  <pre>

            
            rmi://192.18.1.9 username 1

            
                  </pre>


                  <p>The formal grammar for connection ids that follow this

            
                     convention is as follows (using the grammar notation from section 2.4 of

            
                     <em>The Java&trade; Language Specification</em>):</p>

            
                  <pre>

            
            <em>ConnectionId:</em>

            
                <em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>


            <em>ClientAddress:</em>

            
                // <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>


            <em>ClientPort</em>

            
                : <em>HostPort</em>

            
                  </pre>


                  <p>The <code><em>Protocol</em></code> is a protocol that would

            
            	be recognized by {@link

            
            	javax.management.remote.JMXConnectorFactory

            
            	JMXConnectorFactory}.</p>


                  <p>The <code><em>ClientAddress</em></code> is the

            
            	address and port of the connecting client, if these can be

            
            	determined, otherwise nothing.  The

            
            	<code><em>HostAddress</em></code> 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

            
            	<code>[]</code>.  The <code><em>HostPort</em></code> is the

            
            	decimal port number that the client is connecting from.</p>


                  <p>The <code><em>ClientId</em></code> 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.</p>


                  <p>The <code><em>ArbitraryText</em></code> 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.</p>


                @see <a href="{@docRoot}/../technotes/guides/jmx/">

            
                  Java Platform documentation on JMX technology</a>,

            
                in particular the

            
                <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">

            
                  JMX Specification, version 1.4</a>


                @since 1.5


                </body>

            
            </html>
	<html>
	<head>
	<title>JMX<sup><font size="-2">TM</font></sup> Remote API.</title>
	<!--
	Copyright (c) 2002, 2011, 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.
	-->
	</head>
	<body bgcolor="white">
	<p>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
	<a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
	JMX Specification, version 1.4</a> PDF document.</p>

	<p>The JMX specification defines the notion of <b>connectors</b>.
	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.</p>

	<p>A connector makes an MBean server remotely accessible through
	a given protocol. The JMX Remote API allows the use of different
	type of connectors:

	<ul>
	<li>The JMX Remote API defines a standard connector,
	the <b>RMI Connector</b>, which provides remote access to an
	MBeanServer through RMI.

	<li>The JMX Remote API also defines an optional connector called
	<b>JMXMP Connector</b> implementing the JMX Message Protocol
	(JMXMP). As it is optional, it is not part of this bundle (see
	note below).

	<li>User-defined connector protocols are also possible using the
	{@link javax.management.remote.JMXConnectorFactory
	JMXConnectorFactory} and, optionally, the Generic Connector
	(not part of this bundle, see note below).</p>
	</ul>

	<p><u>Note</u>: the optional packages implementing
	the optional part of the <em>JMX Remote API</em>
	are not included in the <em>Java SE Platform</em>
	but are available from the <em>JMX Remote API
	<a href="http://java.sun.com/products/JavaManagement/download.html">
	Reference Implementation</a></em>.</p>


	<h3>Connector addresses</h3>

	<p>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:</p>

	<pre>
	service:jmx:rmi:///jndi/rmi://myhost:1099/myname
	</pre>

	<p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
	specifies the RMI connector, while the second <code>rmi:</code>
	specifies the RMI registry into which the RMI connector server
	has stored its stub.

	<p>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
	<code>{@link javax.management.remote.rmi}</code>.</p>

	<h3>Creating a connector server</h3>

	<p>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}.</p>

	<p>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.</p>

	<h3>Creating a connector client</h3>

	<p>A connector client is usually created by supplying the
	<code>JMXServiceURL</code> of the connector server to connect to
	to the {@link
	javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)
	JMXConnectorFactory.connect} method.</p>

	<p>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 {@link
	javax.management.remote.rmi.RMIConnector
	RMIConnector}.</p>

	<h3>Additional client or server parameters</h3>

	<p>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 "<code>jmx.remote.</code>". The document
	<em>JMX Remote API</em> lists these standard keys.</p>

	<h3>Connection identifiers</h3>

	<p>Every connection opened by a connector server has a string
	identifier, called its <b>connection id</b>. 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.</p>

	<p>As an example, a connection ID can look something like this:</p>

	<pre>
	rmi://192.18.1.9 username 1
	</pre>

	<p>The formal grammar for connection ids that follow this
	convention is as follows (using the grammar notation from section 2.4 of
	<em>The Java™ Language Specification</em>):</p>
	<pre>
	<em>ConnectionId:</em>
	<em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>

	<em>ClientAddress:</em>
	// <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>

	<em>ClientPort</em>
	: <em>HostPort</em>
	</pre>

	<p>The <code><em>Protocol</em></code> is a protocol that would
	be recognized by {@link
	javax.management.remote.JMXConnectorFactory
	JMXConnectorFactory}.</p>

	<p>The <code><em>ClientAddress</em></code> is the
	address and port of the connecting client, if these can be
	determined, otherwise nothing. The
	<code><em>HostAddress</em></code> 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
	<code>[]</code>. The <code><em>HostPort</em></code> is the
	decimal port number that the client is connecting from.</p>

	<p>The <code><em>ClientId</em></code> 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.</p>

	<p>The <code><em>ArbitraryText</em></code> 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.</p>


	@see <a href="{@docRoot}/../technotes/guides/jmx/">
	Java Platform documentation on JMX technology</a>,
	in particular the
	<a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
	JMX Specification, version 1.4</a>

	@since 1.5

	</body>
	</html>