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