jdk/src/java.management/share/classes/javax/management/remote/package.html
author chegar
Sun, 17 Aug 2014 15:54:13 +0100
changeset 25859 3317bb8137f4
parent 24368 jdk/src/share/classes/javax/management/remote/package.html@2b4801b94265
child 30678 a8b7fd8ede97
permissions -rw-r--r--
8054834: Modular Source Code Reviewed-by: alanb, chegar, ihse, mduigou Contributed-by: alan.bateman@oracle.com, alex.buckley@oracle.com, chris.hegarty@oracle.com, erik.joelsson@oracle.com, jonathan.gibbons@oracle.com, karen.kinnear@oracle.com, magnus.ihse.bursie@oracle.com, mandy.chung@oracle.com, mark.reinhold@oracle.com, paul.sandoz@oracle.com
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
<html>
90ce3da70b43 Initial load
duke
parents:
diff changeset
     2
<head>
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
    <title>JMX<sup><font size="-2">TM</font></sup> Remote API.</title>
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
<!--
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 9693
diff changeset
     5
Copyright (c) 2002, 2014, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    10
published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    12
by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    21
2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    22
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
5551
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    24
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    25
or visit www.oracle.com if you need additional information or have any
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    26
questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
-->
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
</head>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
<body bgcolor="white">
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
      <p>Interfaces for remote access to
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
	JMX MBean servers.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
	This package defines the essential interfaces for making a JMX
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
	MBean server manageable remotely. The specification of this 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
        functionality is completed by Part III of the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
       <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
	JMX Specification, version 1.4</a> PDF document.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
      <p>The JMX specification defines the notion of <b>connectors</b>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
	A connector is attached to a JMX API MBean server and makes it
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
	accessible to remote Java clients. The client end of a
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
	connector exports essentially the same interface as the MBean
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
	server, specifically the {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
	javax.management.MBeanServerConnection MBeanServerConnection}
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
	interface.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
      <p>A connector makes an MBean server remotely accessible through
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
	a given protocol. The JMX Remote API allows the use of different 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
        type of connectors:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
      <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
       <li>The JMX Remote API defines a standard connector,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
	the <b>RMI Connector</b>, which provides remote access to an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
        MBeanServer through RMI.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
       <li>The JMX Remote API also defines an optional connector called 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
        <b>JMXMP Connector</b> implementing the JMX Message Protocol 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
	(JMXMP). As it is optional, it is not part of this bundle (see
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
	note below).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
       <li>User-defined connector protocols are also possible using the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
	{@link javax.management.remote.JMXConnectorFactory
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
	JMXConnectorFactory} and, optionally, the Generic Connector
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 9693
diff changeset
    63
	(not part of this bundle, see note below).
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
      </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
      <p><u>Note</u>: the optional packages implementing
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
        the optional part of the <em>JMX Remote API</em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
        are not included in the <em>Java SE Platform</em> 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
        but are available from the <em>JMX Remote API 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
	<a href="http://java.sun.com/products/JavaManagement/download.html">
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
	Reference Implementation</a></em>.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
      <h3>Connector addresses</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
      <p>Typically, a connector server has an address, represented by the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
	class {@link javax.management.remote.JMXServiceURL
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
	JMXServiceURL}.  An address for the RMI Connector can look
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
	like this:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
      service:jmx:rmi:///jndi/rmi://myhost:1099/myname
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
      <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
        specifies the RMI connector, while the second <code>rmi:</code> 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
        specifies the RMI registry into which the RMI connector server 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
        has stored its stub.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
      <p>The example above shows only one form of address.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
        An address for the RMI Connector can take several forms,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
	as detailed in the documentation for the package
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
	<code>{@link javax.management.remote.rmi}</code>.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
      <h3>Creating a connector server</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
      <p>A connector server is created by constructing an instance of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
	a subclass of {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
	javax.management.remote.JMXConnectorServer
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
	JMXConnectorServer}.  Usually, this instance is created
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
        using the method {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
        javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer(JMXServiceURL,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
        java.util.Map, javax.management.MBeanServer)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
	JMXConnectorServerFactory.newJMXConnectorServer}.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
      <p>Typically, a connector server is associated with an MBean
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
	server either by registering it in that MBean server, or by
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
	supplying the MBean server as a parameter when creating the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
	connector server.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
      <h3>Creating a connector client</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
      <p>A connector client is usually created by supplying the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
	<code>JMXServiceURL</code> of the connector server to connect to 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
        to the {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
	javax.management.remote.JMXConnectorFactory#connect(JMXServiceURL)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
	JMXConnectorFactory.connect} method.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
      <p>For more specialized uses, a connector client can be created
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
	by directly instantiating a class that implements the {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
	javax.management.remote.JMXConnector JMXConnector} interface,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
	for example the class {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
	javax.management.remote.rmi.RMIConnector
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
	RMIConnector}.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
      <h3>Additional client or server parameters</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
      <p>When creating a connector client or server, it is possible to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
	supply an object of type {@link java.util.Map Map} that defines
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
	additional parameters.  Each entry in this Map has a key that is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
	a string and an associated value whose type is appropriate for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
	that key.  The standard keys defined by the JMX Remote API all
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
	begin with the string "<code>jmx.remote.</code>".  The document
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
	<em>JMX Remote API</em> lists these standard keys.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
      <h3>Connection identifiers</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
      <p>Every connection opened by a connector server has a string
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
	identifier, called its <b>connection id</b>.  This identifier
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
	appears in the {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
	javax.management.remote.JMXConnectionNotification
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
	JMXConnectionNotification} events emitted by the connector
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
	server, in the list returned by {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
	javax.management.remote.JMXConnectorServerMBean#getConnectionIds()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
	getConnectionIds()}, and in the value
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
	returned by the client's {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
	javax.management.remote.JMXConnector#getConnectionId()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
	getConnectionId()} method.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
      <p>As an example, a connection ID can look something like this:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
rmi://192.18.1.9 username 1
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
      <p>The formal grammar for connection ids that follow this
9266
121fb370f179 7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents: 5551
diff changeset
   157
         convention is as follows (using the grammar notation from section 2.4 of 
121fb370f179 7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents: 5551
diff changeset
   158
         <em>The Java&trade; Language Specification</em>):</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
<em>ConnectionId:</em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
    <em>Protocol</em> : <em>ClientAddress<sub>opt</sub></em> Space <em>ClientId<sub>opt</sub></em> Space <em>ArbitraryText</em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
<em>ClientAddress:</em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
    // <em>HostAddress</em> <em>ClientPort<sub>opt</sub></em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
<em>ClientPort</em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
    : <em>HostPort</em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
      <p>The <code><em>Protocol</em></code> is a protocol that would
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
	be recognized by {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
	javax.management.remote.JMXConnectorFactory
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
	JMXConnectorFactory}.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
      <p>The <code><em>ClientAddress</em></code> is the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
	address and port of the connecting client, if these can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
	determined, otherwise nothing.  The
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
	<code><em>HostAddress</em></code> is the Internet address of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
	the host that the client is connecting from, in numeric or DNS
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
	form.  Numeric IPv6 addresses are enclosed in square brackets
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
	<code>[]</code>.  The <code><em>HostPort</em></code> is the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
	decimal port number that the client is connecting from.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
      <p>The <code><em>ClientId</em></code> is the identity of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
	client entity, typically a string returned by {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
	javax.management.remote.JMXPrincipal#getName()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
	JMXPrincipal.getName()}.  This string must not contain
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
	spaces.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
      <p>The <code><em>ArbitraryText</em></code> is any additional
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
	text that the connector server adds when creating the client id.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
	At a minimum, it must be enough to distinguish this connection
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
	ID from the ID of any other connection currently opened by this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
	connector server.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
    @see <a href="{@docRoot}/../technotes/guides/jmx/">
9693
ee89bfc8fa66 7031754: javax.management docs need to be updated to replace Java SE 6 occurrences
fparain
parents: 9266
diff changeset
   198
      Java Platform documentation on JMX technology</a>,
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
    in particular the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
    <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
      JMX Specification, version 1.4</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
    
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
    @since 1.5
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
    </body>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
</html>