jdk/src/java.management.rmi/share/classes/javax/management/remote/rmi/package.html
author uvangapally
Tue, 01 Aug 2017 10:33:47 +0530
changeset 46050 f51c14dc540f
parent 44858 7183899b064b
permissions -rw-r--r--
8181895: javax management docs contain links to technotes Summary: Edited links to point to Alternate paths Reviewed-by: rriggs Contributed-by: ujwal.vangapally@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>RMI connector</title>
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
<!--
46050
f51c14dc540f 8181895: javax management docs contain links to technotes
uvangapally
parents: 44858
diff changeset
     5
Copyright (c) 2002, 2017, 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>The RMI connector is a connector for the JMX Remote API that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
      uses RMI to transmit client requests to a remote MBean server.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
      This package defines the classes that the user of an RMI
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
      connector needs to reference directly, for both the client and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
      server sides.  It also defines certain classes that the user
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
      will not usually reference directly, but that must be defined so
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
      that different implementations of the RMI connector can
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
      interoperate.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
    39
    <p>The RMI connector supports the JRMP transport for RMI.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
    <p>Like most connectors in the JMX Remote API, an RMI connector
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
      usually has an address, which
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
      is a {@link javax.management.remote.JMXServiceURL
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
      JMXServiceURL}.  The protocol part of this address is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
      <code>rmi</code> for a connector that uses the default RMI
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
    46
      transport (JRMP).</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
    <p>There are two forms for RMI connector addresses:</p>
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>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
	In the <em>JNDI form</em>, the URL indicates <em>where to find
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
	an RMI stub for the connector</em>.  This RMI stub is a Java
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
	object of type {@link javax.management.remote.rmi.RMIServer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
	RMIServer} that gives remote access to the connector server.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
	With this address form, the RMI stub is obtained from an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
	external directory entry included in the URL.  An external
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
	directory is any directory recognized by {@link javax.naming
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
	JNDI}, typically the RMI registry, LDAP, or COS Naming.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
      <li>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
	In the <em>encoded form</em>, the URL directly includes the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
	information needed to connect to the connector server.  When
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
	using RMI/JRMP, the encoded form is the serialized RMI stub
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
	for the server object, encoded using BASE64 without embedded
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
    66
	newlines.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
    </ul>
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
    68
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
    <p>Addresses are covered in more detail below.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
    <h3>Creating an RMI connector server</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
    <p>The usual way to create an RMI connector server is to supply an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
      RMI connector address to the method {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
      javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
      JMXConnectorServerFactory.newJMXConnectorServer}.  The MBean
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
      server to which the connector server is attached can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
      specified as a parameter to that method.  Alternatively, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
      connector server can be registered as an MBean in that MBean
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
      server.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
    <p>An RMI connector server can also be created by constructing an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
      instance of {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
      javax.management.remote.rmi.RMIConnectorServer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
      RMIConnectorServer}, explicitly or through the MBean server's
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
      <code>createMBean</code> method.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
    <h4>Choosing the RMI transport</h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
    91
    <p>You can choose the RMI transport by specifying
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
    92
      <code>rmi</code> in the <code><em>protocol</em></code> part of the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
      <code>serviceURL</code> when creating the connector server.  You
21278
ef8a3a2a72f2 8022746: List of spelling errors in API doc
malenkov
parents: 14917
diff changeset
    94
      can also create specialized connector servers by instantiating
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
      an appropriate subclass of {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
      javax.management.remote.rmi.RMIServerImpl RMIServerImpl} and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
      supplying it to the <code>RMIConnectorServer</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
      constructor.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
44858
7183899b064b 8179415: Update java.management and java.management.rmi to be HTML-5 friendly
ksrini
parents: 43503
diff changeset
   101
    <h4><a id="servergen">Connector addresses generated by the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
	server</a></h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
    <p>If the <code>serviceURL</code> you specify has an empty URL
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
      path (after the optional host and port), or if you do not
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
      specify a <code>serviceURL</code>, then the connector server
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
      will fabricate a new <code>JMXServiceURL</code> that clients can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
      use to connect:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
      <li><p>If the <code>serviceURL</code> looks like:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
	<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
	<code>service:jmx:rmi://<em>host</em>:<em>port</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
	</pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
	<p>then the connector server will generate an {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
	javax.management.remote.rmi.RMIJRMPServerImpl
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
	RMIJRMPServerImpl} and the returned <code>JMXServiceURL</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
	looks like:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
	<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
	<code>service:jmx:rmi://<em>host</em>:<em>port</em>/stub/<em>XXXX</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
	</pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
	<p>where <code><em>XXXX</em></code> is the serialized form of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
	stub for the generated object, encoded in BASE64 without
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
	newlines.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
      <li><p>If there is no <code>serviceURL</code>, there must be a
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   132
	user-provided <code>RMIServerImpl</code>.  The connector server
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   133
        will generate a <code>JMXServiceURL</code> using the <code>rmi</code>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
	form.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
    </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
    <p>The <code><em>host</em></code> in a user-provided
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
      <code>serviceURL</code> is optional.  If present, it is copied
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
      into the generated <code>JMXServiceURL</code> but otherwise
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
      ignored.  If absent, the generated <code>JXMServiceURL</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
      will have the local host name.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
    <p>The <code><em>port</em></code> in a user-provided
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
      <code>serviceURL</code> is also optional.  If present, it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
      also copied into the generated <code>JMXServiceURL</code>;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
      otherwise, the generated <code>JMXServiceURL</code> has no port.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
      For an <code>serviceURL</code> using the <code>rmi</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
      protocol, the <code><em>port</em></code>, if present, indicates
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
      what port the generated remote object should be exported on.  It
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
      has no other effect.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
    <p>If the user provides an <code>RMIServerImpl</code> rather than a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
      <code>JMXServiceURL</code>, then the generated
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
      <code>JMXServiceURL</code> will have the local host name in its
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
      <code><em>host</em></code> part and no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
      <code><em>port</em></code>.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
44858
7183899b064b 8179415: Update java.management and java.management.rmi to be HTML-5 friendly
ksrini
parents: 43503
diff changeset
   160
    <h4><a id="directory">Connector addresses based on directory
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
	entries</a></h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
    <p>As an alternative to the generated addresses just described,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
      the <code>serviceURL</code> address supplied when creating a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
      connector server can specify a <em>directory address</em> in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
      which to store the provided or generated <code>RMIServer</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
      stub.  This directory address is then used by both client and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
      server.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   170
    <p>In this case, the <code>serviceURL</code> has the following form:</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
    <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
    <code>service:jmx:rmi://<em>host</em>:<em>port</em>/jndi/<em>jndi-name</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
    </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
    <p>Here, <code><em>jndi-name</em></code> is a string that can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
      supplied to {@link javax.naming.InitialContext#bind
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
      javax.naming.InitialContext.bind}.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
    <p>As usual, the <code><em>host</em></code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
      <code>:<em>port</em></code> can be omitted.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
    <p>The connector server will generate an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
      <code>RMIServerImpl</code> based on the protocol
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   185
      (<code>rmi</code>) and the <code><em>port</em></code> if any.  When
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
      the connector server is started, it will derive a stub from this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
      object using its {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
      javax.management.remote.rmi.RMIServerImpl#toStub toStub} method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
      and store the object using the given
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
      <code><em>jndi-name</em></code>.  The properties defined by the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
      JNDI API are consulted as usual.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
    <p>For example, if the <code>JMXServiceURL</code> is:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
      <code>service:jmx:rmi://ignoredhost/jndi/rmi://myhost/myname</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
      then the connector server will generate an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
      <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
      name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
      <code>rmi://myhost/myname</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
      which means entry <code>myname</code> in the RMI registry
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
      running on the default port of host <code>myhost</code>.  Note
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
      that the RMI registry only allows registration from the local
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
      host.  So, in this case, <code>myhost</code> must be the name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
      (or a name) of the host that the connector server is running
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 23010
diff changeset
   212
      on.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
    <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
      specifies the RMI
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
      connector, while the second <code>rmi:</code> specifies the RMI
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 23010
diff changeset
   217
      registry.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
    <p>As another example, if the <code>JMXServiceURL</code> is:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
      <pre>
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   222
      <code>service:jmx:rmi://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that</code>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
      then the connector server will generate an
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   226
      <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
      name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
      <code>ldap://dirhost:9999/cn=this,ou=that</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
      which means entry <code>cn=this,ou=that</code> in the LDAP
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 23010
diff changeset
   234
      directory running on port 9999 of host <code>dirhost</code>.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
90ce3da70b43 Initial load
duke
parents:
diff changeset
   236
    <p>If the <code>JMXServiceURL</code> is:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
90ce3da70b43 Initial load
duke
parents:
diff changeset
   238
      <pre>
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   239
      <code>service:jmx:rmi://ignoredhost/jndi/cn=this,ou=that</code>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
90ce3da70b43 Initial load
duke
parents:
diff changeset
   242
      then the connector server will generate an
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   243
      <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
      name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
      <code>cn=this,ou=that</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   248
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   249
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
      For this case to work, the JNDI API must have been configured
90ce3da70b43 Initial load
duke
parents:
diff changeset
   251
      appropriately to supply the information about what directory to
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 23010
diff changeset
   252
      use.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
    <p>In these examples, the host name <code>ignoredhost</code> is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
      not used by the connector server or its clients.  It can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   256
      omitted, for example:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
      <pre>
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   259
      <code>service:jmx:rmi:///jndi/cn=this,ou=that</code>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   260
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   261
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
    <p>However, it is good practice to use the name of the host
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
      where the connector server is running.  This is often different
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
      from the name of the directory host.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
90ce3da70b43 Initial load
duke
parents:
diff changeset
   266
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
    <h4>Connector server attributes</h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   268
90ce3da70b43 Initial load
duke
parents:
diff changeset
   269
    <p>When using the default JRMP transport, RMI socket factories can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   270
      be specified using the attributes
90ce3da70b43 Initial load
duke
parents:
diff changeset
   271
      <code>jmx.remote.rmi.client.socket.factory</code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
      <code>jmx.remote.rmi.server.socket.factory</code> in the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
      <code>environment</code> given to the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   274
      <code>RMIConnectorServer</code> constructor.  The values of these
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
      attributes must be of type {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
      java.rmi.server.RMIClientSocketFactory} and {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   277
      java.rmi.server.RMIServerSocketFactory}, respectively.  These
90ce3da70b43 Initial load
duke
parents:
diff changeset
   278
      factories are used when creating the RMI objects associated with
90ce3da70b43 Initial load
duke
parents:
diff changeset
   279
      the connector.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   280
90ce3da70b43 Initial load
duke
parents:
diff changeset
   281
    <h3>Creating an RMI connector client</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   282
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
    <p>An RMI connector client is usually constructed using {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
      javax.management.remote.JMXConnectorFactory}, with a
32639
339de1317e84 8043937: Drop support for the IIOP transport from the JMX RMIConnector
jbachorik
parents: 30678
diff changeset
   285
      <code>JMXServiceURL</code> that has <code>rmi</code> as its protocol.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   286
90ce3da70b43 Initial load
duke
parents:
diff changeset
   287
    <p>If the <code>JMXServiceURL</code> was generated by the server,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
      as described above under <a href="#servergen">"connector
90ce3da70b43 Initial load
duke
parents:
diff changeset
   289
      addresses generated by the server"</a>, then the client will
90ce3da70b43 Initial load
duke
parents:
diff changeset
   290
      need to obtain it directly or indirectly from the server.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   291
      Typically, the server makes the <code>JMXServiceURL</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   292
      available by storing it in a file or a lookup service.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   293
90ce3da70b43 Initial load
duke
parents:
diff changeset
   294
    <p>If the <code>JMXServiceURL</code> uses the directory syntax, as
90ce3da70b43 Initial load
duke
parents:
diff changeset
   295
      described above under <a href="#directory">"connector addresses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
      based on directory entries"</a>, then the client may obtain it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
      as just explained, or client and server may both know the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   298
      appropriate directory entry to use.  For example, if the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   299
      connector server for the Whatsit agent uses the entry
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
      <code>whatsit-agent-connector</code> in the RMI registry on host
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
      <code>myhost</code>, then client and server can both know
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
      that the appropriate <code>JMXServiceURL</code> is:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
90ce3da70b43 Initial load
duke
parents:
diff changeset
   304
    <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
    <code>service:jmx:rmi:///jndi/rmi://myhost/whatsit-agent-connector</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
    </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
    <p>If you have an RMI stub of type {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   309
      javax.management.remote.rmi.RMIServer RMIServer}, you can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   310
      construct an RMI connection directly by using the appropriate
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
      constructor of {@link javax.management.remote.rmi.RMIConnector
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
      RMIConnector}.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   313
90ce3da70b43 Initial load
duke
parents:
diff changeset
   314
    <h3>Dynamic code downloading</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   315
90ce3da70b43 Initial load
duke
parents:
diff changeset
   316
    <p>If an RMI connector client or server receives from its peer an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   317
      instance of a class that it does not know, and if dynamic code
90ce3da70b43 Initial load
duke
parents:
diff changeset
   318
      downloading is active for the RMI connection, then the class can
46050
f51c14dc540f 8181895: javax management docs contain links to technotes
uvangapally
parents: 44858
diff changeset
   319
      be downloaded from a codebase specified by the peer.
f51c14dc540f 8181895: javax management docs contain links to technotes
uvangapally
parents: 44858
diff changeset
   320
      {@extLink rmi_guide Java RMI Guide} explains this in more detail.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   321
90ce3da70b43 Initial load
duke
parents:
diff changeset
   322
    @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   323
    section 6.8, "Base64 Content-Transfer-Encoding"</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   324
90ce3da70b43 Initial load
duke
parents:
diff changeset
   325
90ce3da70b43 Initial load
duke
parents:
diff changeset
   326
    @since 1.5
90ce3da70b43 Initial load
duke
parents:
diff changeset
   327
90ce3da70b43 Initial load
duke
parents:
diff changeset
   328
  </body>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   329
</html>