jdk/src/share/classes/javax/management/remote/rmi/package.html
author yan
Mon, 12 May 2014 14:33:13 +0400
changeset 24368 2b4801b94265
parent 23010 6dadb192ad81
permissions -rw-r--r--
8038795: Tidy warnings cleanup for javax.management Reviewed-by: dfuchs Contributed-by: Alexander Stepanov <alexander.v.stepanov@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
<!--
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 23010
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>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
14917
bf08557604f8 8001048: JSR-160: Allow IIOP transport to be optional
alanb
parents: 5551
diff changeset
    39
    <p>The RMI connector supports the JRMP transport for RMI, and
bf08557604f8 8001048: JSR-160: Allow IIOP transport to be optional
alanb
parents: 5551
diff changeset
    40
      optionally the IIOP transport.</p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
    <p>Like most connectors in the JMX Remote API, an RMI connector
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
      usually has an address, which
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
      is a {@link javax.management.remote.JMXServiceURL
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
      JMXServiceURL}.  The protocol part of this address is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
      <code>rmi</code> for a connector that uses the default RMI
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
      transport (JRMP), or <code>iiop</code> for a connector that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
      uses RMI/IIOP.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
    <p>There are two forms for RMI connector addresses:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
      <li>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
	In the <em>JNDI form</em>, the URL indicates <em>where to find
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
	an RMI stub for the connector</em>.  This RMI stub is a Java
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
	object of type {@link javax.management.remote.rmi.RMIServer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
	RMIServer} that gives remote access to the connector server.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
	With this address form, the RMI stub is obtained from an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
	external directory entry included in the URL.  An external
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
	directory is any directory recognized by {@link javax.naming
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
	JNDI}, typically the RMI registry, LDAP, or COS Naming.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
      <li>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
	In the <em>encoded form</em>, the URL directly includes the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
	information needed to connect to the connector server.  When
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
	using RMI/JRMP, the encoded form is the serialized RMI stub
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
	for the server object, encoded using BASE64 without embedded
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
	newlines.  When using RMI/IIOP, the encoded form is the CORBA
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
	IOR for the server object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
    </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
    
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
    <p>Addresses are covered in more detail below.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
    <h3>Creating an RMI connector server</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
    <p>The usual way to create an RMI connector server is to supply an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
      RMI connector address to the method {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
      javax.management.remote.JMXConnectorServerFactory#newJMXConnectorServer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
      JMXConnectorServerFactory.newJMXConnectorServer}.  The MBean
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
      server to which the connector server is attached can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
      specified as a parameter to that method.  Alternatively, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
      connector server can be registered as an MBean in that MBean
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
      server.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
    <p>An RMI connector server can also be created by constructing an
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
      instance of {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
      javax.management.remote.rmi.RMIConnectorServer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
      RMIConnectorServer}, explicitly or through the MBean server's
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
      <code>createMBean</code> method.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
    <h4>Choosing the RMI transport</h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
    <p>You can choose the RMI transport (JRMP or IIOP) by specifying
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
      <code>rmi</code> or <code>iiop</code> in the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
      <code><em>protocol</em></code> part of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
      <code>serviceURL</code> when creating the connector server.  You
21278
ef8a3a2a72f2 8022746: List of spelling errors in API doc
malenkov
parents: 14917
diff changeset
    98
      can also create specialized connector servers by instantiating
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
      an appropriate subclass of {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
      javax.management.remote.rmi.RMIServerImpl RMIServerImpl} and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
      supplying it to the <code>RMIConnectorServer</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
      constructor.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
    <h4><a name="servergen">Connector addresses generated by the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
	server</a></h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
    <p>If the <code>serviceURL</code> you specify has an empty URL
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
      path (after the optional host and port), or if you do not
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
      specify a <code>serviceURL</code>, then the connector server
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
      will fabricate a new <code>JMXServiceURL</code> that clients can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
      use to connect:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
      <li><p>If the <code>serviceURL</code> looks like:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
	<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
	<code>service:jmx:rmi://<em>host</em>:<em>port</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
	</pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
	<p>then the connector server will generate an {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
	javax.management.remote.rmi.RMIJRMPServerImpl
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
	RMIJRMPServerImpl} and the returned <code>JMXServiceURL</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
	looks like:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
	<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
	<code>service:jmx:rmi://<em>host</em>:<em>port</em>/stub/<em>XXXX</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
	</pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
	<p>where <code><em>XXXX</em></code> is the serialized form of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
	stub for the generated object, encoded in BASE64 without
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
	newlines.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
      <li><p>If the <code>serviceURL</code> looks like:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
	<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
	<code>service:jmx:iiop://<em>host</em>:<em>port</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
	</pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
	
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
	<p>then the connector server will generate an {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
	javax.management.remote.rmi.RMIIIOPServerImpl
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
	RMIIIOPServerImpl} and the returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
	<code>JMXServiceURL</code> looks like:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
	<pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
	<code>service:jmx:iiop://<em>host</em>:<em>port</em>/ior/IOR:<em>XXXX</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
	</pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
	<p>where <code>IOR:<em>XXXX</em></code> is the standard CORBA
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
	encoding of the Interoperable Object Reference for the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
	generated object.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
      <li><p>If there is no <code>serviceURL</code>, there must be a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
	user-provided <code>RMIServerImpl</code>.  If the {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
	javax.management.remote.rmi.RMIServerImpl#toStub toStub}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
	method on this object returns an instance of {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
	javax.rmi.CORBA.Stub}, then the connector server will generate
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
	a <code>JMXServiceURL</code> using the <code>iiop</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
	form above.  Otherwise, it will generate a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
	<code>JMXServiceURL</code> using the <code>rmi</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
	form.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
    </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
    <p>The <code><em>host</em></code> in a user-provided
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
      <code>serviceURL</code> is optional.  If present, it is copied
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
      into the generated <code>JMXServiceURL</code> but otherwise
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
      ignored.  If absent, the generated <code>JXMServiceURL</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
      will have the local host name.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
    <p>The <code><em>port</em></code> in a user-provided
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
      <code>serviceURL</code> is also optional.  If present, it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
      also copied into the generated <code>JMXServiceURL</code>;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
      otherwise, the generated <code>JMXServiceURL</code> has no port.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
      For an <code>serviceURL</code> using the <code>rmi</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
      protocol, the <code><em>port</em></code>, if present, indicates
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
      what port the generated remote object should be exported on.  It
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
      has no other effect.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
    <p>If the user provides an <code>RMIServerImpl</code> rather than a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
      <code>JMXServiceURL</code>, then the generated
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
      <code>JMXServiceURL</code> will have the local host name in its
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
      <code><em>host</em></code> part and no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
      <code><em>port</em></code>.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
    <h4><a name="directory">Connector addresses based on directory
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
	entries</a></h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
    <p>As an alternative to the generated addresses just described,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
      the <code>serviceURL</code> address supplied when creating a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
      connector server can specify a <em>directory address</em> in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
      which to store the provided or generated <code>RMIServer</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
      stub.  This directory address is then used by both client and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
      server.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
    <p>In this case, the <code>serviceURL</code> has one of these two
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
      forms:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
    <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
    <code>service:jmx:rmi://<em>host</em>:<em>port</em>/jndi/<em>jndi-name</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
    <code>service:jmx:iiop://<em>host</em>:<em>port</em>/jndi/<em>jndi-name</em></code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
    </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
    <p>Here, <code><em>jndi-name</em></code> is a string that can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
      supplied to {@link javax.naming.InitialContext#bind
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
      javax.naming.InitialContext.bind}.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
    <p>As usual, the <code><em>host</em></code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
      <code>:<em>port</em></code> can be omitted.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
    <p>The connector server will generate an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
      <code>RMIServerImpl</code> based on the protocol
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
      (<code>rmi</code> or <code>iiop</code>) and, for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
      <code>rmi</code>, the <code><em>port</em></code> if any.  When
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
      the connector server is started, it will derive a stub from this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
      object using its {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
      javax.management.remote.rmi.RMIServerImpl#toStub toStub} method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
      and store the object using the given
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
      <code><em>jndi-name</em></code>.  The properties defined by the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
      JNDI API are consulted as usual.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
    <p>For example, if the <code>JMXServiceURL</code> is:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
      <code>service:jmx:rmi://ignoredhost/jndi/rmi://myhost/myname</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
      then the connector server will generate an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
      <code>RMIJRMPServerImpl</code> and store its stub using the JNDI
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
      name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
      <code>rmi://myhost/myname</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   236
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
90ce3da70b43 Initial load
duke
parents:
diff changeset
   238
      which means entry <code>myname</code> in the RMI registry
90ce3da70b43 Initial load
duke
parents:
diff changeset
   239
      running on the default port of host <code>myhost</code>.  Note
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
      that the RMI registry only allows registration from the local
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
      host.  So, in this case, <code>myhost</code> must be the name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   242
      (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
   243
      on.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
    <p>In this <code>JMXServiceURL</code>, the first <code>rmi:</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
      specifies the RMI
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
      connector, while the second <code>rmi:</code> specifies the RMI
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 23010
diff changeset
   248
      registry.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   249
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
    <p>As another example, if the <code>JMXServiceURL</code> is:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   251
90ce3da70b43 Initial load
duke
parents:
diff changeset
   252
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
      <code>service:jmx:iiop://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
90ce3da70b43 Initial load
duke
parents:
diff changeset
   256
      then the connector server will generate an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
      <code>RMIIIOPServerImpl</code> and store its stub using the JNDI
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
      name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   259
90ce3da70b43 Initial load
duke
parents:
diff changeset
   260
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   261
      <code>ldap://dirhost:9999/cn=this,ou=that</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
      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
   265
      directory running on port 9999 of host <code>dirhost</code>.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   266
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
    <p>If the <code>JMXServiceURL</code> is:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   268
90ce3da70b43 Initial load
duke
parents:
diff changeset
   269
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   270
      <code>service:jmx:iiop://ignoredhost/jndi/cn=this,ou=that</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   271
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
      then the connector server will generate an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   274
      <code>RMIIIOPServerImpl</code> and store its stub using the JNDI
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
      name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
90ce3da70b43 Initial load
duke
parents:
diff changeset
   277
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   278
      <code>cn=this,ou=that</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   279
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   280
90ce3da70b43 Initial load
duke
parents:
diff changeset
   281
      For this case to work, the JNDI API must have been configured
90ce3da70b43 Initial load
duke
parents:
diff changeset
   282
      appropriately to supply the information about what directory to
24368
2b4801b94265 8038795: Tidy warnings cleanup for javax.management
yan
parents: 23010
diff changeset
   283
      use.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
90ce3da70b43 Initial load
duke
parents:
diff changeset
   285
    <p>In these examples, the host name <code>ignoredhost</code> is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   286
      not used by the connector server or its clients.  It can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   287
      omitted, for example:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
90ce3da70b43 Initial load
duke
parents:
diff changeset
   289
      <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   290
      <code>service:jmx:iiop:///jndi/cn=this,ou=that</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   291
      </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   292
90ce3da70b43 Initial load
duke
parents:
diff changeset
   293
    <p>However, it is good practice to use the name of the host
90ce3da70b43 Initial load
duke
parents:
diff changeset
   294
      where the connector server is running.  This is often different
90ce3da70b43 Initial load
duke
parents:
diff changeset
   295
      from the name of the directory host.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
90ce3da70b43 Initial load
duke
parents:
diff changeset
   298
    <h4>Connector server attributes</h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   299
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
    <p>When using the default JRMP transport, RMI socket factories can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
      be specified using the attributes
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
      <code>jmx.remote.rmi.client.socket.factory</code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
      <code>jmx.remote.rmi.server.socket.factory</code> in the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   304
      <code>environment</code> given to the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
      <code>RMIConnectorServer</code> constructor.  The values of these
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
      attributes must be of type {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
      java.rmi.server.RMIClientSocketFactory} and {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
      java.rmi.server.RMIServerSocketFactory}, respectively.  These
90ce3da70b43 Initial load
duke
parents:
diff changeset
   309
      factories are used when creating the RMI objects associated with
90ce3da70b43 Initial load
duke
parents:
diff changeset
   310
      the connector.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
    <h3>Creating an RMI connector client</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   313
90ce3da70b43 Initial load
duke
parents:
diff changeset
   314
    <p>An RMI connector client is usually constructed using {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   315
      javax.management.remote.JMXConnectorFactory}, with a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   316
      <code>JMXServiceURL</code> that has <code>rmi</code> or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   317
      <code>iiop</code> as its protocol.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   318
90ce3da70b43 Initial load
duke
parents:
diff changeset
   319
    <p>If the <code>JMXServiceURL</code> was generated by the server,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   320
      as described above under <a href="#servergen">"connector
90ce3da70b43 Initial load
duke
parents:
diff changeset
   321
      addresses generated by the server"</a>, then the client will
90ce3da70b43 Initial load
duke
parents:
diff changeset
   322
      need to obtain it directly or indirectly from the server.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   323
      Typically, the server makes the <code>JMXServiceURL</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   324
      available by storing it in a file or a lookup service.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   325
90ce3da70b43 Initial load
duke
parents:
diff changeset
   326
    <p>If the <code>JMXServiceURL</code> uses the directory syntax, as
90ce3da70b43 Initial load
duke
parents:
diff changeset
   327
      described above under <a href="#directory">"connector addresses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   328
      based on directory entries"</a>, then the client may obtain it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   329
      as just explained, or client and server may both know the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   330
      appropriate directory entry to use.  For example, if the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   331
      connector server for the Whatsit agent uses the entry
90ce3da70b43 Initial load
duke
parents:
diff changeset
   332
      <code>whatsit-agent-connector</code> in the RMI registry on host
90ce3da70b43 Initial load
duke
parents:
diff changeset
   333
      <code>myhost</code>, then client and server can both know
90ce3da70b43 Initial load
duke
parents:
diff changeset
   334
      that the appropriate <code>JMXServiceURL</code> is:</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   335
90ce3da70b43 Initial load
duke
parents:
diff changeset
   336
    <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   337
    <code>service:jmx:rmi:///jndi/rmi://myhost/whatsit-agent-connector</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   338
    </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   339
90ce3da70b43 Initial load
duke
parents:
diff changeset
   340
    <p>If you have an RMI stub of type {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
   341
      javax.management.remote.rmi.RMIServer RMIServer}, you can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   342
      construct an RMI connection directly by using the appropriate
90ce3da70b43 Initial load
duke
parents:
diff changeset
   343
      constructor of {@link javax.management.remote.rmi.RMIConnector
90ce3da70b43 Initial load
duke
parents:
diff changeset
   344
      RMIConnector}.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   345
90ce3da70b43 Initial load
duke
parents:
diff changeset
   346
90ce3da70b43 Initial load
duke
parents:
diff changeset
   347
    <h3>Specifying an ORB for the RMI/IIOP connector</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   348
90ce3da70b43 Initial load
duke
parents:
diff changeset
   349
    <p>When using the IIOP transport, the client and server can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   350
      specify what ORB to use
90ce3da70b43 Initial load
duke
parents:
diff changeset
   351
      with the attribute <code>java.naming.corba.orb</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   352
      Connection to the ORB happens at {@link 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   353
      javax.management.remote.rmi.RMIConnectorServer#start() start} time 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   354
      for the connector server, and at {@link 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   355
      javax.management.remote.rmi.RMIConnector#connect(java.util.Map) 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   356
      connect} time for the connector client.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   357
      If the <code>java.naming.corba.orb</code> attribute is contained
90ce3da70b43 Initial load
duke
parents:
diff changeset
   358
      in the environment Map, then its value (an {@link 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   359
      org.omg.CORBA.ORB ORB}), is used to connect the IIOP Stubs. 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   360
      Otherwise, a new org.omg.CORBA.ORB is created by calling {@link 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   361
      org.omg.CORBA.ORB
90ce3da70b43 Initial load
duke
parents:
diff changeset
   362
      org.omg.CORBA.ORB.init((String[])null,(Properties)null)}.  A
90ce3da70b43 Initial load
duke
parents:
diff changeset
   363
      later RMI connector client or server in the same JVM can reuse
90ce3da70b43 Initial load
duke
parents:
diff changeset
   364
      this ORB, or it can create another one in the same way.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   365
90ce3da70b43 Initial load
duke
parents:
diff changeset
   366
     <p>If the <code>java.naming.corba.orb</code> attribute is 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   367
      specified and does not point to an {@link org.omg.CORBA.ORB ORB},
90ce3da70b43 Initial load
duke
parents:
diff changeset
   368
      then an <code>{@link java.lang.IllegalArgumentException}</code> 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   369
      will be thrown.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   370
90ce3da70b43 Initial load
duke
parents:
diff changeset
   371
     <p>The mechanism described here does not apply when the IIOP
90ce3da70b43 Initial load
duke
parents:
diff changeset
   372
      Remote objects (Stubs or Servers) are created and connected to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   373
      an ORB manually before being passed to the RMIConnector and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   374
      RMIConnectorServer.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   375
90ce3da70b43 Initial load
duke
parents:
diff changeset
   376
90ce3da70b43 Initial load
duke
parents:
diff changeset
   377
    <h3>Dynamic code downloading</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   378
90ce3da70b43 Initial load
duke
parents:
diff changeset
   379
    <p>If an RMI connector client or server receives from its peer an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   380
      instance of a class that it does not know, and if dynamic code
90ce3da70b43 Initial load
duke
parents:
diff changeset
   381
      downloading is active for the RMI connection, then the class can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   382
      be downloaded from a codebase specified by the peer.  The
90ce3da70b43 Initial load
duke
parents:
diff changeset
   383
      article <a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   384
    href="{@docRoot}/../technotes/guides/rmi/codebase.html"><em>Dynamic
90ce3da70b43 Initial load
duke
parents:
diff changeset
   385
    code downloading using Java RMI</em></a> explains this in more
90ce3da70b43 Initial load
duke
parents:
diff changeset
   386
    detail.</p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   387
90ce3da70b43 Initial load
duke
parents:
diff changeset
   388
 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   389
    @see <a href="{@docRoot}/../technotes/guides/rmi/index.html">
90ce3da70b43 Initial load
duke
parents:
diff changeset
   390
	Java<sup><font size="-1">TM</font></sup> Remote Method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   391
	Invocation (RMI)</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   392
90ce3da70b43 Initial load
duke
parents:
diff changeset
   393
    @see <a href="{@docRoot}/../technotes/guides/jndi/index.html">
90ce3da70b43 Initial load
duke
parents:
diff changeset
   394
	Java Naming and Directory Interface<sup><font
90ce3da70b43 Initial load
duke
parents:
diff changeset
   395
	size="-1">TM</font></sup> (JNDI)</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   396
90ce3da70b43 Initial load
duke
parents:
diff changeset
   397
    @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   398
    section 6.8, "Base64 Content-Transfer-Encoding"</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   399
90ce3da70b43 Initial load
duke
parents:
diff changeset
   400
90ce3da70b43 Initial load
duke
parents:
diff changeset
   401
    @since 1.5
90ce3da70b43 Initial load
duke
parents:
diff changeset
   402
90ce3da70b43 Initial load
duke
parents:
diff changeset
   403
  </body>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   404
</html>