[jboss-cvs] JBossRemoting/docs/guide/en ...
Ron Sigal
ron_sigal at yahoo.com
Mon Jul 31 04:33:50 EDT 2006
User: rsigal
Date: 06/07/31 04:33:50
Modified: docs/guide/en chap5.xml
Log:
JBREM-559: Polished the socket / server socket factory configuration materials.
Revision Changes Path
1.3 +108 -88 JBossRemoting/docs/guide/en/chap5.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap5.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap5.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- chap5.xml 31 Jul 2006 05:03:42 -0000 1.2
+++ chap5.xml 31 Jul 2006 08:33:50 -0000 1.3
@@ -534,6 +534,12 @@
<section>
<title>Transports (Invokers)</title>
+ <para>This section covers configuration issues for each of the transports,
+ beginning with a set of properties that apply to all transports. The
+ material in a later section in this chapter,
+ <xref linkend="section-socket-factories"/>, also applies to all
+ transports.</para>
+
<section>
<title>Server Invokers</title>
@@ -857,16 +863,12 @@
<section>
<title>SSL Socket Invoker</title>
- <para>Supports all the configuration attributes as the Socket Invoker,
- plus the following:</para>
-
- <para><emphasis role="bold">serverSocketFactory</emphasis> - Sets the
- server socket factory. If want ssl support use a server socket factory
- that supports ssl. The only requirement is that the server socket
- factory value must be an ObjectName, meaning the server socket factory
- implementation must be an MBean and also MUST implement the
- <code>org.jboss.remoting.security.ServerSocketFactoryMBean</code>
- interface.</para>
+ <para>Supports all the configuration attributes as the Socket Invoker.
+ The main difference is that the SSL Socket Invoker uses an
+ <classname>SSLServerSocket</classname> by default, created by an
+ <classname>SSLServerSocketFactory</classname>. See section
+ <xref linkend="section-socket-factories"/> for more information.
+ </para>
</section>
<section>
@@ -875,6 +877,15 @@
<para><emphasis role="bold">registryPort</emphasis> - the port on
which to create the RMI registry. The default is 3455. This also needs
to have the isParam attribute set to true.</para>
+
+ <para><emphasis role="bold">Note.</emphasis> The RMI
+ server invoker creates a socket factory and passes it to a client
+ invoker along with the RMI stub, so the socket factory must be
+ serializable. Therefore, if a
+ socket factory is passed in to the server invoker by one of the
+ methods discussed in section <xref linkend="section-socket-factories"/>,
+ then the user is responsible for supplying
+ a serializable socket factory.</para>
</section>
<section>
@@ -883,37 +894,20 @@
<para>This is essentially identical to the RMI invoker, except that it
creates SSL socket and server socket factories by default.</para>
- <para><emphasis role="bold">Note.</emphasis> Both the RMI and SSL RMI
- server invokers create a socket factory and pass it to a client
- invoker along with the RMI stub. Therefore, the socket factory must be
+ <para><emphasis role="bold">Note.</emphasis> The SSL RMI
+ server invoker create a socket factory and passes it to a client
+ invoker along with the RMI stub, so the socket factory must be
serializable. If the SSL RMI server invoker is allowed to create an
<classname>SSLSocketFactory</classname> from SSL parameters, it will
take care to create a serializable socket factory. However, if a
socket factory is passed in to the server invoker by one of the
- methods discussed earlier, then the user is responsible for supplying
- a serializable socket factory.</para>
-
- <para>The rules discussed above for configuring socket and server
- socket factories apply to the SSL RMI transport, but there is a twist,
- since the server invoker creates the (client) socket factory and
- packages it with its own stub. The server invoker creates a copy of
- <classname>org.jboss.remoting.transport.rmi.ssl.SerializableSSLClientSocketFactory</classname>,
- which is essentially just a holder for the configuration map passed to
- the server invoker, with any parameters removed which concern trust
- store and key store configuration. On the client side, when a client
- SSL RMI invoker is created, it stores its own configuration map in a
- static variable which the transferred
- <classname>SerializableSSLClientSocketFactory</classname> can retrieve
- and merge with the configuration information it brought with it from
- the server. In particular, if a socket factory is explicitly passed to
- the client invoker, then
- <classname>SerializableSSLClientSocketFactory</classname> will use it.
- If not, then <classname>SerializableSSLClientSocketFactory</classname>
- will use any key store and trust store information passed to the
- client to create and configure a socket factory.</para>
+ methods discussed in section <xref linkend="section-socket-factories"/>,
+ then the user is responsible for supplying
+ a serializable socket factory.
+ See <xref linkend="subsection-sslrmi"/> for more information.</para>
</section>
- <section>
+ <section id="section-http-invoker" xreflabel="HTTP Invoker">
<title>HTTP Invoker</title>
<para>The HTTP server invoker implementation is based on the Apache
@@ -989,17 +983,15 @@
<para>Supports all the configuration attributes as the HTTP Invoker,
plus the following:</para>
- <para><emphasis role="bold">serverSocketFactory</emphasis> - Sets the
- server socket factory. If want ssl support, use a server socket
- factory that supports ssl. The only requirement is that the server
- socket factory value must be an ObjectName, meaning the server socket
- factory implementation must be an MBean and also MUST implement the
- <code>org.jboss.remoting.security.ServerSocketFactoryMBean</code>
- interface.</para>
-
<para><emphasis role="bold">SSLImplementation</emphasis> - Sets the
Tomcat SSLImplementation to use. This should always be
<code>org.jboss.remoting.transport.coyote.ssl.RemotingSSLImplementation</code>.</para>
+
+ <para>The main difference with the HTTP invoker is that the
+ HTTPS Invoker uses an
+ <classname>SSLServerSocket</classname> by default, created by an
+ <classname>SSLServerSocketFactory</classname>. See section
+ <xref linkend="section-socket-factories"/> for more information.</para>
</section>
<section>
@@ -1142,7 +1134,7 @@
for the InvokerLocator attribute is the exact url used to access the
servlet for the servlet invoker (more on how to define this below),
with the exception of the protocol being servlet instead of http. This
- is important because if using automatic discovery, as this is the
+ is important if using automatic discovery, as this is the
locator url that will be discovered and used by clients to connect to
this server invoker.</para>
@@ -1314,7 +1306,7 @@
</section>
<section>
- <title id="section-multiplex" xreflabel="Multiplex Invoker">Multiplex
+ <title id="section-multiplex-invoker" xreflabel="Multiplex Invoker">Multiplex
Invoker</title>
<para>The multiplex invoker is intended to replicate the functionality
@@ -1929,7 +1921,7 @@
demo.jboss.com:8080.</para>
<para>For complete examples see the section <xref
- linkend="section-multiplex-invokers" />.</para>
+ linkend="section-multiplex-invoker" />.</para>
<orderedlist>
<listitem>
@@ -2211,7 +2203,9 @@
which calls the same method that client invokers use to get a socket
factory. Moreover, if necessary, it will look for a
<classname>ServerSocketFactoryMBean</classname> to get SSL information
- when configuring a socket factory.</para>
+ when configuring a socket factory. See section
+ <xref linkend="section-socket-factories"/> for more information.
+ </para>
</section>
</section>
@@ -2653,7 +2647,8 @@
org.jboss.test.remoting.configuration.SocketClientConfigurationTestCase.</para>
</section>
- <section>
+ <section id="section-socket-factories"
+ xreflabel="Socket factories and server socket factories">
<title>Socket factories and server socket factories</title>
<para>All current transports depend on sockets and server sockets, and the
@@ -2680,8 +2675,8 @@
factories, and these apply to all transports.
</para>
- <section>
- <title id="section-ssf-serverside" xreflabel="Server socket factories">
+ <section id="section-ssf-serverside" xreflabel="Server socket factories">
+ <title>
Server socket factories.
</title>
<para>For <classname>ServerSocketFactory</classname>s, there are
@@ -3429,11 +3424,19 @@
<bridgehead>https</bridgehead>
- <para>The https transport is a bit different from the sslsocket in
- configuration since the implementation is based off the Tomcat
- connectors. The first major difference is the transport protocol keyword
- to identify it, which is 'https'.</para>
+ <para>Configuration of the https transport is a bit different from
+ that of the other transports since the implementation is based off the Tomcat
+ connectors. One difference is that, in order to use SSL connections,
+ the <code>SSLImplementation</code> attribute
+ must be set and must always have the value
+ <classname>org.jboss.remoting.transport.coyote.ssl.RemotingSSLImplementation</classname>.
+ The <code>SSLImplementation</code> is used by the Tomcat connector to
+ create <classname>ServerSocketFactory</classname>s, and
+ <classname>RemotingSSLImplementation</classname> presents Tomcat with
+ the <classname>ServerSocketFactory</classname> configured according to
+ the options described above.</para>
+ <!--
<para>Next is defining the SSL implementation and server socket factory
to be used. The SSL implementation to be used can be set via the
'SSLImplementation' attribute and should always have a value of
@@ -3443,7 +3446,7 @@
javax.management.ObjectName value for an implementation of the
<code>org.jboss.remoting.security.ServerSocketFactoryMBean</code>
interface, which should already be registered with the MBeanServer and
- running (more details on this in a minute).</para>
+ running (more details on this in a minute).</para>-->
<para>An example of setting up https via service.xml configuration would
be:</para>
@@ -3456,11 +3459,6 @@
<attribute name="Configuration">
<config>
<invoker transport="https">
- <!-- The following is for setting the server socket factory. If want ssl support -->
- <!-- use a server socket factory that supports ssl. The only requirement is that -->
- <!-- the server socket factory value must be an ObjectName, meaning the -->
- <!-- server socket factory implementation must be a MBean and also -->
- <!-- MUST implement the org.jboss.remoting.security.ServerSocketFactoryMBean interface. -->
<attribute name="serverSocketFactory">jboss.remoting:service=ServerSocketFactory,type=SSL</attribute>
<attribute name="SSLImplementation">org.jboss.remoting.transport.coyote.ssl.RemotingSSLImplementation</attribute>
<attribute name="serverBindAddress">${jboss.bind.address}</attribute>
@@ -3476,27 +3474,15 @@
</mbean>
</programlisting>
- <para>Notice that the 'serverSocketFactory' attribute has a value of
- 'jboss.remoting:service=ServerSocketFactory,type=SSL', which is not
- defined in the configuration snippet. More on how to define this in the
- next section.</para>
-
- <para>One of the major changes related to using the Tomcat connectors
- with regards to SSL is that everything within Tomcat is defined via
- properties configuration and there is no external API for making changes
- during runtime. This means that there is no way to set server socket
- factory implementation programatically, other than via configuration (so
- cannot call setServerSocketFactory() method on the server invoker as
- could with the ssl socket invoker). This also means that if not running
- within the JBoss Application Server container, but running stand alone,
- will need to setup an MBeanServer and register the server socket factory
- with it programatically. For an example of how to do this
- programatically, can refer to
- org.jboss.test.remoting.transport.http.ssl.basic.HTTPSInvokerTestServer.</para>
+ <para>See section <xref linkend="section-SSLServerSocketFactoryService"/>
+ below for a discussion of the
+ "jboss.remoting:service=ServerSocketFactory,type=SSL'
+ MBean that appears in this configuration element.</para>
- <para>The configuration for SSL support only works when using the java
+ <para>Note that the configuration for SSL support only works when using the java
based http processor and not with the APR based transport. See section
- 4.7 for more information on using the APR based transport.</para>
+ <xref linkend="section-http-invoker"/>
+ for more information on using the APR based transport.</para>
<bridgehead>sslmultiplex</bridgehead>
@@ -3512,6 +3498,39 @@
new <classname>SSLServerSocketFactory</classname> configured with an
updated keystore.</para>
+ <bridgehead id="subsection-sslrmi" xreflabel="sslrmi">sslrmi</bridgehead>
+
+ <para>The rules discussed in <xref linkend="section-socket-factories"/>
+ for configuring socket and server
+ socket factories apply to the SSL RMI transport, but there is a twist,
+ since the server invoker creates the (client) socket factory and
+ packages it with its own stub. It follows that the socket factory must be
+ serializable. If the SSL RMI server invoker is allowed to create an
+ <classname>SSLSocketFactory</classname> from SSL parameters, it will
+ take care to create a serializable socket factory. In particular,
+ the server invoker creates a copy of
+ <classname>org.jboss.remoting.transport.rmi.ssl.SerializableSSLClientSocketFactory</classname>,
+ which is essentially just a holder for the configuration map passed to
+ the server invoker, with any parameters removed which concern trust
+ store and key store configuration. On the client side, when a client
+ SSL RMI invoker is created, it stores its own configuration map in a
+ static variable which the transferred
+ <classname>SerializableSSLClientSocketFactory</classname> can retrieve
+ and merge with the configuration information it brought with it from
+ the server. In particular, if a socket factory is explicitly passed to
+ the client invoker, then
+ <classname>SerializableSSLClientSocketFactory</classname> will use it.
+ If not, then <classname>SerializableSSLClientSocketFactory</classname>
+ will use any key store and trust store information passed to the
+ client to create and configure a socket factory.</para>
+
+ <para><emphasis role="bold">Note.</emphasis> If instead of using
+ <classname>SerializableSSLClientSocketFactory</classname>, a
+ socket factory is passed in to the server invoker by one of the
+ methods discussed in section <xref linkend="section-socket-factories"/>,
+ then the user is responsible for supplying
+ a serializable socket factory.</para>
+
<bridgehead>sslsocket</bridgehead>
<para>In addition to the various configuration options discussed above,
the sslsocket transport exposes the</para>
@@ -3930,7 +3949,8 @@
</programlisting>
</section>
- <section>
+ <section id="section-SSLServerSocketFactoryService"
+ xreflabel="SSLServerSocketFactoryService">
<title>SSLServerSocketFactoryService</title>
<para>Although any server socket factory can be set for the various
More information about the jboss-cvs-commits
mailing list