[jboss-cvs] JBossRemoting/docs/guide/en ...
Tom Elrod
tom.elrod at jboss.com
Thu Aug 10 11:38:59 EDT 2006
User: telrod
Date: 06/08/10 11:38:59
Modified: docs/guide/en chap5.xml
Log:
JBREM-564 - updated doc for system property to be used to set default socket factory implementation to be used.
Revision Changes Path
1.9 +3833 -3931JBossRemoting/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.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- chap5.xml 3 Aug 2006 02:23:39 -0000 1.8
+++ chap5.xml 10 Aug 2006 15:38:59 -0000 1.9
@@ -1,4 +1,5 @@
- <chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
<title>Configuration</title>
<para>This covers the configuration for JBoss Remoting discovery,
@@ -13,31 +14,29 @@
<section>
<title>General transport configuration</title>
- <para> Remoting offers a
- variety of ways of configuring transports on the server side and client
- side. This section presents an overview, and the rest of the chapter
- elaborates the material presented here. For easy reference the
- configuration parameters discussed throughout the chapter are gathered
- together at the end of the chapter in section <xref
- linkend="section-configuration"/></para>
+ <para>Remoting offers a variety of ways of configuring transports on the
+ server side and client side. This section presents an overview, and the
+ rest of the chapter elaborates the material presented here. For easy
+ reference the configuration parameters discussed throughout the chapter
+ are gathered together at the end of the chapter in section <xref
+ linkend="section-configuration" /></para>
<section>
<title>Server side configuration</title>
<para>The heart of the server side is the
<classname>Connector</classname>, and it is through the
- <classname>Connector</classname> that
- the server side of a transport is configured.
- The central goals of configuration on the server side are to establish a
- server invoker and supply it with a set of invocation handlers.
- Only one invoker can be declared per <classname>Connector</classname>.
- Although declaring an invocation handler is
- not required, it should only be omitted in the case of declaring a
- callback server that will not receive direct invocations, but only
- callback messages. Otherwise client invocations can not be processed.
- The invocation handler is the only interface that is required by the
- remoting framework for a user to implement and will be what the remoting
- framework calls upon when receiving invocations.</para>
+ <classname>Connector</classname> that the server side of a transport is
+ configured. The central goals of configuration on the server side are to
+ establish a server invoker and supply it with a set of invocation
+ handlers. Only one invoker can be declared per
+ <classname>Connector</classname>. Although declaring an invocation
+ handler is not required, it should only be omitted in the case of
+ declaring a callback server that will not receive direct invocations,
+ but only callback messages. Otherwise client invocations can not be
+ processed. The invocation handler is the only interface that is required
+ by the remoting framework for a user to implement and will be what the
+ remoting framework calls upon when receiving invocations.</para>
<para>There are two general approaches to server side configuration:
programmatic and declarative. A variety of programmatic techniques work
@@ -46,15 +45,15 @@
particular, the SARDeployer (see The JBoss 4 Application Server Guide on
the labs.jboss.org web site) can read information from a *-service.xml
file and use it to configure MBeans such as
- <classname>Connector</classname>s. </para>
+ <classname>Connector</classname>s.</para>
<section>
<title>Programmatic configuration.</title>
<para>The simplest way to configure a <classname>Connector</classname>
- is to pass an <classname>InvokerLocator</classname>
- to a <classname>Connector</classname> constructor. For example, the
- code fragment</para>
+ is to pass an <classname>InvokerLocator</classname> to a
+ <classname>Connector</classname> constructor. For example, the code
+ fragment</para>
<programlisting>
String locatorURI = "socket://test.somedomain.com:8084";
@@ -72,15 +71,14 @@
it to listen for invocations on port 8084 of host test.somedomain.com,
and passes two configuration parameters, "clientLeasePeriod" and
"timeout". It also supplies the server invoker with an invocation
- handler.
- </para>
+ handler.</para>
<para>One limitation of the <classname>InvokerLocator</classname> is
that it can only represent string values. An alternative that
overcomes this limitation is to pass some or all of the parameters to
the <classname>Connector</classname> by way of a configuration map.
- The following code fragment accomplishes all that the
- previous fragment does, but it passes one parameter by way of the
+ The following code fragment accomplishes all that the previous
+ fragment does, but it passes one parameter by way of the
<classname>InvokerLocator</classname> and passes the other by way of a
configuration map. It also passes in a non-string object, a
<classname>ServerSocketFactory</classname>:</para>
@@ -105,9 +103,9 @@
<code>ServerInvoker.SERVER_SOCKET_FACTORY</code> is
"serverSocketFactory". These configuration map keys are discussed
throughout the chapter and accumulated in section <xref
- linkend="section-configuration"/>. Also, server socket factory
- configuration is covered in
- <xref linkend="section-socket-factories"/>.</para>
+ linkend="section-configuration" />. Also, server socket factory
+ configuration is covered in <xref
+ linkend="section-socket-factories" />.</para>
<para>A third programmatic option is available for those configuration
properties which happen to be server invoker MBean properties. In the
@@ -139,8 +137,7 @@
only works after that method has been called. Also, depending on the
parameter and the transport, this option may or may not be effective
after the call to <methodname>Connector.start()</methodname>, which
- calls <methodname>start()</methodname> on the server invoker.
- </para>
+ calls <methodname>start()</methodname> on the server invoker.</para>
<para>A fourth option, which exists primarily to support the
declarative mode of configuration presented below, is to pass an XML
@@ -160,7 +157,7 @@
buf.append(" <invoker transport=\"socket\">");
buf.append(" <attribute name=\"serverBindAddress\">test.somedomain.com</attribute>");
buf.append(" <attribute name=\"serverBindPort\">8084</attribute>");
- buf.append(" <attribute name=\"clientLeasePeriod\">10000</attribute>");
+ buf.append(" <attribute name=\"clientLeasePeriod\">10000</attribute>");
buf.append(" </invoker>");
buf.append(" <handlers>");
buf.append(" <handler subsystem=\"mock\">");
@@ -182,12 +179,10 @@
xml document. Note also that this method only supports the use of
string values, so it is necessary to include the fully qualified name
of the invocation handler, from which the handler is created by
- calling the default constructor.
- </para>
+ calling the default constructor.</para>
<para>An example of this option in use can be found in
- <classname>org.jboss.test.remoting.configuration.SocketClientConfigurationTestCase</classname>.
- </para>
+ <classname>org.jboss.test.remoting.configuration.SocketClientConfigurationTestCase</classname>.</para>
</section>
<section>
@@ -195,21 +190,21 @@
<para>The configuration option discussed at the end of the previous
section, passing an XML document to the
- <classname>Connector</classname>, works in conjunction with the service
- archive deployer (SARDeployer) inside the JBoss Application Server to
- allow declarative configuration on the server side. In particular, the
- SARDeployer reads XMl documents containing MBean descriptors from files
- whose name has the form "*-service.xml". When it sees a descriptor for
- a <classname>Connector</classname> MBean, it passes the
- descriptor's <code><config></code> element to a newly created
- <classname>Connector</classname>.</para>
+ <classname>Connector</classname>, works in conjunction with the
+ service archive deployer (SARDeployer) inside the JBoss Application
+ Server to allow declarative configuration on the server side. In
+ particular, the SARDeployer reads XMl documents containing MBean
+ descriptors from files whose name has the form "*-service.xml". When
+ it sees a descriptor for a <classname>Connector</classname> MBean, it
+ passes the descriptor's <code><config></code> element to a newly
+ created <classname>Connector</classname>.</para>
<para>There are two ways in which to specify the server invoker
configuration via a service xml file. The first is to specify just the
InvokerLocator attribute as a sub-element of the Connector MBean. For
- example, a possible configuration for a Connector using a socket invoker
- that is listening on port 8084 on the test.somedomain.com address would
- be:</para>
+ example, a possible configuration for a Connector using a socket
+ invoker that is listening on port 8084 on the test.somedomain.com
+ address would be:</para>
<programlisting>
<mbean code="org.jboss.remoting.transport.Connector"
@@ -236,17 +231,17 @@
add CDATA to any locator uri that contains more than one
parameter.</para>
- <para>The other way to configure the Connector and its server invoker in
- greater detail is to provide an <code>invoker</code> sub-element within
- the config element of the Configuration attribute. The only attribute of
- invoker element is transport, which will specify which transport type to
- use (e.g.. socket, rmi, http, or multiplex). All the sub-elements of the
- invoker element will be attribute elements with a name attribute
- specifying the configuration property name and then the value. An
- <code>isParam</code> attribute can also be added to indicate that the
- attribute should be added to the locator uri, in the case the attribute
- needs to be used by the client. An example using this form of
- configuration is as follows:</para>
+ <para>The other way to configure the Connector and its server invoker
+ in greater detail is to provide an <code>invoker</code> sub-element
+ within the config element of the Configuration attribute. The only
+ attribute of invoker element is transport, which will specify which
+ transport type to use (e.g.. socket, rmi, http, or multiplex). All the
+ sub-elements of the invoker element will be attribute elements with a
+ name attribute specifying the configuration property name and then the
+ value. An <code>isParam</code> attribute can also be added to indicate
+ that the attribute should be added to the locator uri, in the case the
+ attribute needs to be used by the client. An example using this form
+ of configuration is as follows:</para>
<programlisting>
<mbean code="org.jboss.remoting.transport.Connector"
@@ -281,28 +276,28 @@
</mbean>
</programlisting>
- <para>Also note that <code>${jboss.bind.address}</code> can be used for
- any of the bind address properties, which will be replaced with the bind
- address specified to JBoss when starting (i.e. via the -b
+ <para>Also note that <code>${jboss.bind.address}</code> can be used
+ for any of the bind address properties, which will be replaced with
+ the bind address specified to JBoss when starting (i.e. via the -b
option).</para>
- <para>All the attributes set in this configuration could be set directly
- in the locator uri of the InvokerLocator attribute value, but would be
- much more difficult to decipher visually and is more prone to editing
- mistakes.</para>
+ <para>All the attributes set in this configuration could be set
+ directly in the locator uri of the InvokerLocator attribute value, but
+ would be much more difficult to decipher visually and is more prone to
+ editing mistakes.</para>
<para>One of the components of a locator uri that can be expressed
within the InvokerLocator attribute is the path. For example, can
- express a locator uri path of 'foo/bar' via the InvokerLocator attribute
- as:</para>
+ express a locator uri path of 'foo/bar' via the InvokerLocator
+ attribute as:</para>
<programlisting> <attribute name="InvokerLocator"><![CDATA[socket://test.somedomain.com:8084/<emphasis
role="bold">foo/bar</emphasis>]]></attribute>
</programlisting>
- <para>To include the path using the Configuration attribute, can include
- a specific 'path' attribute. So the same InvokerLocator can be expressed
- as follows with the Configuration attribute:</para>
+ <para>To include the path using the Configuration attribute, can
+ include a specific 'path' attribute. So the same InvokerLocator can be
+ expressed as follows with the Configuration attribute:</para>
<programlisting>
<attribute name="Configuration">
@@ -318,25 +313,23 @@
<para>Note: The value for the 'path' attribute should NOT start or end
with a / (slash).</para>
</section>
-
</section>
<section>
<title>Client side configuration</title>
- <para>Invoker configuration on the client side parallels configuration on
- the server side, with the exception that (1) it operates in a simpler
+ <para>Invoker configuration on the client side parallels configuration
+ on the server side, with the exception that (1) it operates in a simpler
environment (in particular, it does not assume the presence of an
MBeanServer) and (2) it does not support a declarative option. However,
it does support versions of the first three server side programmatic
- options, with the <classname>Client</classname> class playing the central
- role played by the <classname>Connector</classname> class on the server
- side.</para>
+ options, with the <classname>Client</classname> class playing the
+ central role played by the <classname>Connector</classname> class on the
+ server side.</para>
- <para>Again, the most straightforward form of configuration is to put the
- configuration parameters on the <classname>InvokerLocator</classname>.
- For example, the fragment
- </para>
+ <para>Again, the most straightforward form of configuration is to put
+ the configuration parameters on the
+ <classname>InvokerLocator</classname>. For example, the fragment</para>
<programlisting>
String locatorURI = "socket://test.somedomain.com:8084";
@@ -350,15 +343,14 @@
<para>creates a <classname>Client</classname> using the socket transport
to connect to a server on host test.somedomain.com, listening on port
8084. It also passes in two parameters, "clientMaxPoolSize" and
- "timeout", that will be used by the client invoker.
- </para>
+ "timeout", that will be used by the client invoker.</para>
<para>It is also possible to use configuration maps on the client side.
The following code fragment accomplishes all that the previous fragment
does, but it passes one parameter by way of the
<classname>InvokerLocator</classname> and passes the other by way of a
configuration map. It also passes in a non-string object, a
- <classname>SocketFactory</classname>: </para>
+ <classname>SocketFactory</classname>:</para>
<programlisting>
String locatorURI = "socket://test.somedomain.com:8084";
@@ -376,8 +368,8 @@
"timeout", and the value of <code>Remoting.CUSTOM_SOCKET_FACTORY</code>
is "customSocketFactory". These configuration map keys are discussed
throughout the chapter and accumulated in section <xref
- linkend="section-configuration"/>. Also, socket factory configuration is
- covered in <xref linkend="section-socket-factories"/>.</para>
+ linkend="section-configuration" />. Also, socket factory configuration
+ is covered in <xref linkend="section-socket-factories" />.</para>
<para>Finally, a third programmatic option is available for those
configuration properties which happen to be client invoker MBean
@@ -403,24 +395,22 @@
<para><emphasis role="bold">Note.</emphasis> The
<classname>Client</classname> creates the client invoker during the call
to <methodname>Client.connect()</methodname>, so this option only works
- after that method has been called. </para>
+ after that method has been called.</para>
</section>
-
</section>
<section>
<title>Handlers</title>
<para>Handlers are classes that the invocation is given to on the server
- side (the final target for remoting invocations). To implement a
- handler, all that is needed is to implement the
+ side (the final target for remoting invocations). To implement a handler,
+ all that is needed is to implement the
<code>org.jboss.remoting.ServerInvocationHandler</code> interface. There
- are a two ways in which to register a handler with a Connector. The
- first is to do it programmatically. The second is via service
- configuration. For registering programmatically, can either pass the
- ServerInvocationHandler reference itself or an ObjectName for the
- ServerInvocationHandler (in the case that it is an MBean). To pass the
- handler reference directly, call
+ are a two ways in which to register a handler with a Connector. The first
+ is to do it programmatically. The second is via service configuration. For
+ registering programmatically, can either pass the ServerInvocationHandler
+ reference itself or an ObjectName for the ServerInvocationHandler (in the
+ case that it is an MBean). To pass the handler reference directly, call
<code>Connector::addInvocationHandler(String subsystem,
ServerInvocationHandler handler)</code>. For example (from
<code>org.jboss.remoting.samples.simple.SimpleServer</code>):</para>
@@ -466,9 +456,8 @@
<para>If using a service configuration for starting the Connector and
registering handlers, can either specify the fully qualified class name
- for the handler, which will instantiate the handler instance upon
- startup (which requires there be a void parameter constructor), such
- as:</para>
+ for the handler, which will instantiate the handler instance upon startup
+ (which requires there be a void parameter constructor), such as:</para>
<programlisting>
<handlers>
@@ -481,9 +470,9 @@
<para>where MockServerInvocationHandler will be constructed upon startup
and registered with the Connector as a handler.</para>
- <para>Can also use an ObjectName to specify the handler. The
- configuration is the same, but instead of specifying a fully qualified
- class name, you specify the ObjectName for the handler, such as (can see
+ <para>Can also use an ObjectName to specify the handler. The configuration
+ is the same, but instead of specifying a fully qualified class name, you
+ specify the ObjectName for the handler, such as (can see
<code>mbeanhandler-service.xml</code> under remoting tests for full
example):</para>
@@ -512,8 +501,8 @@
<para>There is also an invocation handler interface that extends the
ServerInvocationHandler interface specifically for handling of input
- streams as well as normal invocations. See the section on sending
- streams for further details. As for Connector configuration, it is the
+ streams as well as normal invocations. See the section on sending streams
+ for further details. As for Connector configuration, it is the
same.</para>
<bridgehead>HTTP handlers</bridgehead>
@@ -521,20 +510,20 @@
<para>Since there is extra information needed when dealing with the http
transport, such as headers and response codes, special consideration is
needed by handlers. The handlers receiving http invocations can get and
- set this extra information via the InvocationRequest that is passed to
- the handler.</para>
+ set this extra information via the InvocationRequest that is passed to the
+ handler.</para>
- <para>Server invoker for the http transport will add the following to
- the InvocationRequest's request payload map:</para>
+ <para>Server invoker for the http transport will add the following to the
+ InvocationRequest's request payload map:</para>
- <para><emphasis role="bold">MethodType</emphasis> - the http request
- type (i.e., GET, POST, PUT, HEADER, OPTIONS). Can use the contant value
+ <para><emphasis role="bold">MethodType</emphasis> - the http request type
+ (i.e., GET, POST, PUT, HEADER, OPTIONS). Can use the contant value
HTTPMetadataConstants.METHODTYPE, if don't want to use the actual string
'MethodType' as the key to the request payload map.</para>
<para><emphasis role="bold">Path</emphasis> - the url path. Can use the
- contant value HTTPMetadataConstants.PATH, if don't want to use the
- actual string 'Path' as the key to the request payload map.</para>
+ contant value HTTPMetadataConstants.PATH, if don't want to use the actual
+ string 'Path' as the key to the request payload map.</para>
<para><emphasis role="bold">HttpVersion</emphasis> - the client's http
version. Can use the contant value HTTPMetadataConstants.HTTPVERSION, if
@@ -553,83 +542,81 @@
(application/octet-stream).</para>
<para>The handlers receiving http invocations can also set the response
- code, response message, and response headers. To do this, will need to
- get the return payload map from the InvocationRequest passed (via its
+ code, response message, and response headers. To do this, will need to get
+ the return payload map from the InvocationRequest passed (via its
getReturnPayload() method). Then populate this map with whatever
properties needed. For response code and message, will need to use the
following keys for the map:</para>
- <para><emphasis role="bold">ResponseCode</emphasis> - Can use the
- constant value HTTPMetaDataConstants.RESPONSE_CODE, if don't want to use
- the actual string 'ResponseCode' as they key. <emphasis
+ <para><emphasis role="bold">ResponseCode</emphasis> - Can use the constant
+ value HTTPMetaDataConstants.RESPONSE_CODE, if don't want to use the actual
+ string 'ResponseCode' as they key. <emphasis
role="bold">IMPORTANT</emphasis> - The value put into map for this key
MUST be of type java.lang.Integer.</para>
<para><emphasis role="bold">ResponseCodeMessage</emphasis> - Can use the
- constant value HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, if don't
- want to use the actual string 'ResponseCodeMessage' as the key. The
- value put into map for this key should be of type
- java.lang.String.</para>
+ constant value HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, if don't want
+ to use the actual string 'ResponseCodeMessage' as the key. The value put
+ into map for this key should be of type java.lang.String.</para>
<para>Is also important to note that ALL http requests will be passed to
the handler. So even OPTIONS, HEAD, and PUT method requests will need to
be handled. So, for example, if want to accept OPTIONS method requests,
would need to populate response map with key of 'Allow' and value of
- 'OPTIONS, POST, GET, HEAD, PUT', in order to tell calling client that
- all these method types are allowed. Can see an example of how to do this
+ 'OPTIONS, POST, GET, HEAD, PUT', in order to tell calling client that all
+ these method types are allowed. Can see an example of how to do this
within
org.jboss.test.remoting.transport.http.method.MethodInvocationHandler.</para>
<para>The PUT request will be handled the same as a POST method request
- and the PUT request payload will be included within the
- InvocationRequest passed to the server handler. It is up to the server
- handler to set the proper resonse code (or throw proper exception) for
- the processing of the PUT request. See <ulink
+ and the PUT request payload will be included within the InvocationRequest
+ passed to the server handler. It is up to the server handler to set the
+ proper resonse code (or throw proper exception) for the processing of the
+ PUT request. See <ulink
url="http://www.ietf.org/rfc/rfc2616.txt?number=2616">
- http://www.ietf.org/rfc/rfc2616.txt?number=2616 </ulink>, section 9.6
- for details on response codes and error responses).</para>
+ http://www.ietf.org/rfc/rfc2616.txt?number=2616 </ulink>, section 9.6 for
+ details on response codes and error responses).</para>
<bridgehead>HTTP Client</bridgehead>
- <para>The HttpClientInvoker will now put the return from
- HttpURLConnection getHeaderFields() method into the metadata map
- passed to the Client's invoke() method (if not null). This means that if
- the caller passes a non-null Map, it can then get the response headers.
- It is important to note that each response header field key in the
- metadata map is associated with a list of response header values, so to
- get a value, would need code similar to:</para>
+ <para>The HttpClientInvoker will now put the return from HttpURLConnection
+ getHeaderFields() method into the metadata map passed to the Client's
+ invoke() method (if not null). This means that if the caller passes a
+ non-null Map, it can then get the response headers. It is important to
+ note that each response header field key in the metadata map is associated
+ with a list of response header values, so to get a value, would need code
+ similar to:</para>
<programlisting>Object response = remotingClient.invoke((Object) null, metadata);
String allowValue = (String) ((List) metadata.get("Allow").get(0);
</programlisting>
<para>Can reference
- org.jboss.test.remoting.transport.http.method.HTTPInvokerTestClient for
- an example of this.</para>
+ org.jboss.test.remoting.transport.http.method.HTTPInvokerTestClient for an
+ example of this.</para>
- <para>Note that when making a http request using the OPTIONS method
- type, the return from the Client's invoke() method will ALWAYS be
- null.</para>
+ <para>Note that when making a http request using the OPTIONS method type,
+ the return from the Client's invoke() method will ALWAYS be null.</para>
<para>Also, if the response code is 400, the response returned will be
that of the error stream and not the standard input stream. So is
important to check for the response code.</para>
- <para>Two values that will always be set within the metadata map passed
- to the Client's invoke() method (when not null), is the response code
- and response message from the server. These can be found using the
+ <para>Two values that will always be set within the metadata map passed to
+ the Client's invoke() method (when not null), is the response code and
+ response message from the server. These can be found using the
keys:</para>
- <para><emphasis role="bold">ResponseCode</emphasis> - Can use the
- constant value HTTPMetaDataConstants.RESPONSE_CODE, if don't want to use
- the actual string 'ResponseCode' as the key. <emphasis
- role="bold">IMPORTANT</emphasis> - The value returned for this key will
- be of type java.lang.Integer.</para>
+ <para><emphasis role="bold">ResponseCode</emphasis> - Can use the constant
+ value HTTPMetaDataConstants.RESPONSE_CODE, if don't want to use the actual
+ string 'ResponseCode' as the key. <emphasis
+ role="bold">IMPORTANT</emphasis> - The value returned for this key will be
+ of type java.lang.Integer.</para>
<para><emphasis role="bold">ResponseCodeMessage</emphasis> - Can use the
- constant value from HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, if
- don't want to use the actual string 'ResponseCodeMessage' as the key.
- The value returned for this key will be of type java.lang.String.</para>
+ constant value from HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, if don't
+ want to use the actual string 'ResponseCodeMessage' as the key. The value
+ returned for this key will be of type java.lang.String.</para>
<para>An example of getting the response code can be found within
org.jboss.test.remoting.transport.http.method.HTTPInvokerTestClient.</para>
@@ -640,16 +627,16 @@
<bridgehead>Domains</bridgehead>
- <para>Detectors have the ability to accept multiple domains. What
- domains that the detector will accept as viewable can either be set
+ <para>Detectors have the ability to accept multiple domains. What domains
+ that the detector will accept as viewable can either be set
programmatically via the method:</para>
<para><code>public void setConfiguration(org.w3c.dom.Element xml)
</code></para>
<para>or by adding to jboss-service.xml configuration for the detector.
- The domains that the detector is currently accepting can be retrieved
- from the method:</para>
+ The domains that the detector is currently accepting can be retrieved from
+ the method:</para>
<para><code>public org.w3c.dom.Element getConfiguration()</code></para>
@@ -658,15 +645,15 @@
<para>There are three possible options for setting up the domains that a
detector will accept. The first is to not call the
- <code>setConfiguration()</code> method (or just not add the
- configuration attribute to the service xml). This will cause the
- detector to use only its domain and is the default behavior. This
- enables it to be backwards compatible with earlier versions of JBoss
- Remoting (JBoss 4, DR2 and before).</para>
-
- <para>The second is to call the <code>setConfiguration()</code> method
- (or add the configuration attribute to the service xml) with the
- following xml element:</para>
+ <code>setConfiguration()</code> method (or just not add the configuration
+ attribute to the service xml). This will cause the detector to use only
+ its domain and is the default behavior. This enables it to be backwards
+ compatible with earlier versions of JBoss Remoting (JBoss 4, DR2 and
+ before).</para>
+
+ <para>The second is to call the <code>setConfiguration()</code> method (or
+ add the configuration attribute to the service xml) with the following xml
+ element:</para>
<programlisting>
<domains>
@@ -680,9 +667,9 @@
detector to accept detections only from the domains specified, and no
others.</para>
- <para>The third and final option is to call the setConfiguration()
- method (or add the configuration attribute to the service xml) with the
- following xml element:</para>
+ <para>The third and final option is to call the setConfiguration() method
+ (or add the configuration attribute to the service xml) with the following
+ xml element:</para>
<programlisting>
<domains>
@@ -692,13 +679,12 @@
<para>This will cause the detector to accept all detections from any
domain.</para>
- <para>By default, remoting detection will ignore any detection message
- the it receives from a server invoker running within its own jvm. To
- disable this, add an element called 'local' to the detector
- configuration (alongside the domain element) to indicate should accept
- detection messages from local server invokers. This will be false by
- default, so maintains the same behavior as previous releases. For
- example:</para>
+ <para>By default, remoting detection will ignore any detection message the
+ it receives from a server invoker running within its own jvm. To disable
+ this, add an element called 'local' to the detector configuration
+ (alongside the domain element) to indicate should accept detection
+ messages from local server invokers. This will be false by default, so
+ maintains the same behavior as previous releases. For example:</para>
<programlisting> <domains>
<domain>domain1</domain>
@@ -729,21 +715,21 @@
<para>The following are configuration attributes for all the remoting
detectors.</para>
- <para><emphasis role="bold">DefaultTimeDelay</emphasis> - amount of
- time, in milliseconds, which can elapse without receiving a detection
- event before suspecting that a server is dead and performing an explicit
+ <para><emphasis role="bold">DefaultTimeDelay</emphasis> - amount of time,
+ in milliseconds, which can elapse without receiving a detection event
+ before suspecting that a server is dead and performing an explicit
invocation on it to verify it is alive. If this invocation, or ping,
fails, the server will be removed from the network registry. The default
is 5000 milliseconds.</para>
- <para><emphasis role="bold">HeartbeatTimeDelay</emphasis> - amount of
- time to wait between sending (and sometimes receiving) detection
- messages. The default is 1000 milliseconds.</para>
+ <para><emphasis role="bold">HeartbeatTimeDelay</emphasis> - amount of time
+ to wait between sending (and sometimes receiving) detection messages. The
+ default is 1000 milliseconds.</para>
<bridgehead>JNDIDetector</bridgehead>
- <para><emphasis role="bold">Port</emphasis> - port to which detector
- will connect for the JNDI server.</para>
+ <para><emphasis role="bold">Port</emphasis> - port to which detector will
+ connect for the JNDI server.</para>
<para><emphasis role="bold">Host</emphasis> - host to which the detector
will connect for the JNDI server.</para>
@@ -752,19 +738,19 @@
string used when connecting to the JNDI server. The default is
<code>org.jnp.interfaces.NamingContextFactory</code> .</para>
- <para><emphasis role="bold">URLPackage</emphasis> - url package string
- to use when connecting to the JNDI server. The default is
+ <para><emphasis role="bold">URLPackage</emphasis> - url package string to
+ use when connecting to the JNDI server. The default is
<code>org.jboss.naming:org.jnp.interfaces</code> .</para>
<para><emphasis role="bold">CleanDetectionNumber</emphasis> - Sets the
number of detection iterations before manually pinging remote server to
- make sure still alive. This is needed since remote server could crash
- and yet still have an entry in the JNDI server, thus making it appear
- that it is still there. The default value is 5.</para>
+ make sure still alive. This is needed since remote server could crash and
+ yet still have an entry in the JNDI server, thus making it appear that it
+ is still there. The default value is 5.</para>
<para>Can either set these programmatically using setter method or as
- attribute within the remoting-service.xml (or anywhere else the service
- is defined). For example:</para>
+ attribute within the remoting-service.xml (or anywhere else the service is
+ defined). For example:</para>
<programlisting>
<mbean code="org.jboss.remoting.detection.jndi.JNDIDetector"
@@ -774,17 +760,17 @@
</mbean>
</programlisting>
- <para>If the JNDIDetector is started without the Host attribute being
- set, it will try to start a local JNP instance (the JBoss JNDI server
+ <para>If the JNDIDetector is started without the Host attribute being set,
+ it will try to start a local JNP instance (the JBoss JNDI server
implementation) on port 1088.</para>
<bridgehead>MulticastDetector</bridgehead>
- <para><emphasis role="bold">DefaultIP</emphasis> - The IP that is used
- to broadcast detection messages on via multicast. To be more specific,
- will be the ip of the multicast group the detector will join. This
- attribute is ignored if the Address has already been set when started.
- Default is 224.1.9.1.</para>
+ <para><emphasis role="bold">DefaultIP</emphasis> - The IP that is used to
+ broadcast detection messages on via multicast. To be more specific, will
+ be the ip of the multicast group the detector will join. This attribute is
+ ignored if the Address has already been set when started. Default is
+ 224.1.9.1.</para>
<para><emphasis role="bold">Port</emphasis> - The port that is used to
broadcast detection messages on via multicast. Default is 2410.</para>
@@ -796,8 +782,8 @@
group that the detector will join. The default will be that of the
DefaultIP if not explicitly set.</para>
- <para>If any of these are set programmatically, need to be done before
- the detector is started (otherwise will use default values).</para>
+ <para>If any of these are set programmatically, need to be done before the
+ detector is started (otherwise will use default values).</para>
</section>
<section>
@@ -805,8 +791,8 @@
<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
+ material in a later section in this chapter, <xref
+ linkend="section-socket-factories" />, also applies to all
transports.</para>
<section>
@@ -818,8 +804,8 @@
<para><emphasis role="bold">serverBindAddress</emphasis> - The address
on which the server binds to listen for requests. The default is an
empty value which indicates the server should be bound to the host
- provided by the locator url, or if this value is null, the local host
- as provided by <code>InetAddress.getLocalHost()</code> .</para>
+ provided by the locator url, or if this value is null, the local host as
+ provided by <code>InetAddress.getLocalHost()</code> .</para>
<para><emphasis role="bold">serverBindPort</emphasis> - The port to
listen for requests on. A value of 0 or less indicates that a free
@@ -842,41 +828,38 @@
<code>org.jboss.util.threadpool.BasicThreadPool</code> used by the
server invoker.</para>
- <para>Note that this value will NOT be retrieved until the first
- one-way (server side) invocation is made. So if the configuration is
- invalid, will not be detected until this first call is made. The
- thread pool can also be accessed or set via the
- <code>OnewayThreadPool</code> property programmatically.</para>
+ <para>Note that this value will NOT be retrieved until the first one-way
+ (server side) invocation is made. So if the configuration is invalid,
+ will not be detected until this first call is made. The thread pool can
+ also be accessed or set via the <code>OnewayThreadPool</code> property
+ programmatically.</para>
<para>Important to note that the default thread pool used for the
- one-way invocations on the server side will block the calling thread
- if all the threads in the pool are in use until one is
- released.</para>
-
+ one-way invocations on the server side will block the calling thread if
+ all the threads in the pool are in use until one is released.</para>
</section>
<section>
<title>Configurations affecting the invoker client</title>
<para>There are some configurations which will impact the invoker
- client. These will be communicated to the client invoker via
- parameters in the Locator URI. These configurations can not be changed
- during runtime, so can only be set up upon initial configuration of
- the server invoker on the server side. The following is a list of
- these and their effects.</para>
-
- <para><emphasis role="bold">clientConnectPort</emphasis> - the port
- the client will use to connect to the remoting server. This would be
- needed in the case that the client will be going through a router that
- forwards requests made externally to a different port
+ client. These will be communicated to the client invoker via parameters
+ in the Locator URI. These configurations can not be changed during
+ runtime, so can only be set up upon initial configuration of the server
+ invoker on the server side. The following is a list of these and their
+ effects.</para>
+
+ <para><emphasis role="bold">clientConnectPort</emphasis> - the port the
+ client will use to connect to the remoting server. This would be needed
+ in the case that the client will be going through a router that forwards
+ requests made externally to a different port internally.</para>
+
+ <para><emphasis role="bold">clientConnectAddress</emphasis> - the ip or
+ hostname the client will use to connect to the remoting server. This
+ would be needed in the case that the client will be going through a
+ router that forwards requests made externally to a different ip or host
internally.</para>
- <para><emphasis role="bold">clientConnectAddress</emphasis> - the ip
- or hostname the client will use to connect to the remoting server.
- This would be needed in the case that the client will be going through
- a router that forwards requests made externally to a different ip or
- host internally.</para>
-
<para>If no client connect address or server bind address specified,
will use the local host's address (via
<code>InetAddress.getLocalHost().getHostAddress()</code> ).</para>
@@ -895,9 +878,9 @@
InvokerLocator is also not set, will bind to local host.</para>
<para>If there is a system property called 'remoting.bind_by_host' and
- if is false, will bind by IP address instead of host. Otherwise will
- use host name. This only applies when configured address is 0.0.0.0.
- To facilitate setting this property, the following static variable is
+ if is false, will bind by IP address instead of host. Otherwise will use
+ host name. This only applies when configured address is 0.0.0.0. To
+ facilitate setting this property, the following static variable is
defined in <classname>InvokerLocator</classname>:</para>
<programlisting>
@@ -907,115 +890,113 @@
<para>If the serverBindPort property is set, it will be used. If this
value is 0 or a negative number, then the next available port will be
found and used. If the serverBindPort property is not set, but the
- clientConnectPort property is set, then the next available port will
- be found and used. If neither the serverBindPort nor the
- clientConnectPort is set, then the port specified in the original
- InvokerLocator will be used. If this is 0 or a negative number, then
- the next available port will be found and used. In the case that the
- next available port is used because either the serverBindPort or the
- original InvokerLocator port value was either 0 or negative, the
- InvokerLocator will be updated to reflect the new port value.</para>
+ clientConnectPort property is set, then the next available port will be
+ found and used. If neither the serverBindPort nor the clientConnectPort
+ is set, then the port specified in the original InvokerLocator will be
+ used. If this is 0 or a negative number, then the next available port
+ will be found and used. In the case that the next available port is used
+ because either the serverBindPort or the original InvokerLocator port
+ value was either 0 or negative, the InvokerLocator will be updated to
+ reflect the new port value.</para>
</section>
<section>
<title>Socket Invoker</title>
- <para>The following configuration properties can be set at any time,
- but will not take effect until the socket invoker, on the server side,
- is stopped and restarted.</para>
+ <para>The following configuration properties can be set at any time, but
+ will not take effect until the socket invoker, on the server side, is
+ stopped and restarted.</para>
<para><emphasis role="bold">timeout</emphasis> - The socket timeout
value passed to the Socket.setSoTimeout() method. The default on the
- server side is 60000 (one minute). If the timeout parameter is set,
- its value will also be passed to the client side (see below).</para>
+ server side is 60000 (one minute). If the timeout parameter is set, its
+ value will also be passed to the client side (see below).</para>
- <para><emphasis role="bold">backlog</emphasis> - The preferred number
- of unaccepted incoming connections allowed at a given time. The actual
+ <para><emphasis role="bold">backlog</emphasis> - The preferred number of
+ unaccepted incoming connections allowed at a given time. The actual
number may be greater than the specified backlog. When the queue is
- full, further connection requests are rejected. Must be a positive
- value greater than 0. If the value passed if equal or less than 0,
- then the default value will be assumed. The default value is
- 200.</para>
+ full, further connection requests are rejected. Must be a positive value
+ greater than 0. If the value passed if equal or less than 0, then the
+ default value will be assumed. The default value is 200.</para>
- <para><emphasis role="bold">numAcceptThreads</emphasis> - The number
- of threads that exist for accepting client connections. The default is
+ <para><emphasis role="bold">numAcceptThreads</emphasis> - The number of
+ threads that exist for accepting client connections. The default is
1.</para>
<para><emphasis role="bold">maxPoolSize</emphasis> - The number of
server threads for processing client. The default is 300.</para>
- <para><emphasis role="bold">serverSocketClass</emphasis> - specifies
- the fully qualified class name for the custom SocketWrapper
- implementation to use on the server.</para>
+ <para><emphasis role="bold">serverSocketClass</emphasis> - specifies the
+ fully qualified class name for the custom SocketWrapper implementation
+ to use on the server.</para>
<para><emphasis role="bold">socket.check_connection</emphasis> -
indicates if the invoker should try to check the connection before
- re-using it by sending a single byte ping from the client to the
- server and then back from the server. This config needs to be set on
- both client and server to work. This if false by default.</para>
+ re-using it by sending a single byte ping from the client to the server
+ and then back from the server. This config needs to be set on both
+ client and server to work. This if false by default.</para>
<bridgehead>Configurations affecting the Socket invoker
client</bridgehead>
- <para>There are some configurations which will impact the socket
- invoker client. These will be communicated to the client invoker via
- parameters in the Locator URI. These configurations can not be changed
- during runtime, so can only be set up upon initial configuration of
- the socket invoker on the server side. The following is a list of
- these and their effects.</para>
-
- <para><emphasis role="bold">enableTcpNoDelay</emphasis> - can be
- either true or false and will indicate if client socket should have
- TCP_NODELAY turned on or off. TCP_NODELAY is for a specific purpose;
- to disable the Nagle buffering algorithm. It should only be set for
- applications that send frequent small bursts of information without
- getting an immediate response; where timely delivery of data is
- required (the canonical example is mouse movements). The default is
- false.</para>
+ <para>There are some configurations which will impact the socket invoker
+ client. These will be communicated to the client invoker via parameters
+ in the Locator URI. These configurations can not be changed during
+ runtime, so can only be set up upon initial configuration of the socket
+ invoker on the server side. The following is a list of these and their
+ effects.</para>
+
+ <para><emphasis role="bold">enableTcpNoDelay</emphasis> - can be either
+ true or false and will indicate if client socket should have TCP_NODELAY
+ turned on or off. TCP_NODELAY is for a specific purpose; to disable the
+ Nagle buffering algorithm. It should only be set for applications that
+ send frequent small bursts of information without getting an immediate
+ response; where timely delivery of data is required (the canonical
+ example is mouse movements). The default is false.</para>
<para><emphasis role="bold">timeout</emphasis> - The socket timeout
value passed to the Socket.setSoTimeout() method. The default on the
client side is 1800000 (or 30 minutes).</para>
<para><emphasis role="bold">clientMaxPoolSize</emphasis> - the client
- side maximum number of active socket connections. This basically
- equates to the maximum number of concurrent client calls that can be
- made from the socket client invoker. The default is 50.</para>
+ side maximum number of active socket connections. This basically equates
+ to the maximum number of concurrent client calls that can be made from
+ the socket client invoker. The default is 50.</para>
<para><emphasis role="bold">numberOfRetries</emphasis> - number of
- retries to get a socket from the pool. This basically equates to
- number of seconds will wait to get client socket connection from pool
- before timing out. If max retries is reached, will cause a
- CannotConnectException to be thrown (whose cause will be
- SocketException saying how long it waited for socket connection from
- pool). The default is 30 (MAX_RETRIES)</para>
+ retries to get a socket from the pool. This basically equates to number
+ of seconds will wait to get client socket connection from pool before
+ timing out. If max retries is reached, will cause a
+ CannotConnectException to be thrown (whose cause will be SocketException
+ saying how long it waited for socket connection from pool). The default
+ is 30 (MAX_RETRIES)</para>
<para><emphasis role="bold">numberOfCallRetries</emphasis> - number of
retries for making invocation. This is unrelated to numberOfRetries in
- that when this comes into play is after it has already received a
- client socket connection from the pool. However, is possible that the
- socket connection timed out while waiting within the pool. Since not
- doing a connection check by default, will throw away the connection
- and try to get a new one. Will do this for whatever the
- numberOfCallRetries (which defaults to 3) is. However, when reaches
- numberOfCallsRetries - 2, will flush the entire connection pool under
- the assumption that all connections in the pool have timed out and are
- invalid and will start over by creating a new connection. If still
- fails, will throw MarshalException with the cause being the original
+ that when this comes into play is after it has already received a client
+ socket connection from the pool. However, is possible that the socket
+ connection timed out while waiting within the pool. Since not doing a
+ connection check by default, will throw away the connection and try to
+ get a new one. Will do this for whatever the numberOfCallRetries (which
+ defaults to 3) is. However, when reaches numberOfCallsRetries - 2, will
+ flush the entire connection pool under the assumption that all
+ connections in the pool have timed out and are invalid and will start
+ over by creating a new connection. If still fails, will throw
+ MarshalException with the cause being the original
SocketException.</para>
- <para><emphasis role="bold">clientSocketClass</emphasis> - specifies
- the fully qualified class name for the custom SocketWrapper
- implementation to use on the client. Note, will need to make sure this
- is marked as a client parameter (using the 'isParam' attribute).
- Making this change will not affect the marshaller/unmarshaller that is
- used, which may also be a requirement.</para>
+ <para><emphasis role="bold">clientSocketClass</emphasis> - specifies the
+ fully qualified class name for the custom SocketWrapper implementation
+ to use on the client. Note, will need to make sure this is marked as a
+ client parameter (using the 'isParam' attribute). Making this change
+ will not affect the marshaller/unmarshaller that is used, which may also
+ be a requirement.</para>
<para><emphasis role="bold">socket.check_connection</emphasis> -
indicates if the invoker should try to check the connection before
- re-using it by sending a single byte ping from the client to the
- server and then back from the server. This config needs to be set on
- both client and server to work. This if false by default.</para>
+ re-using it by sending a single byte ping from the client to the server
+ and then back from the server. This config needs to be set on both
+ client and server to work. This if false by default.</para>
<para>An example of locator uri for a socket invoker that has
TCP_NODELAY set to false and the client's max pool size of 30 would
@@ -1026,8 +1007,7 @@
</code></para>
<para>To reiterate, these client configurations can only be set within
- the server side configuration and will not change during
- runtime.</para>
+ the server side configuration and will not change during runtime.</para>
<section>
<title>How the Socket Invoker works</title>
@@ -1045,93 +1025,92 @@
and only one, instance of java.net.ServerSocket. Upon being started,
it will also create and start a number of threads to be used for
accepting incoming requests from the ServerSocket. These threads are
- called the accept threads and the number of them created is
- controlled by the 'numAcceptThreads' property. When these accept
- threads are started, they will call accept() on the ServerSocket and
- block until the ServerSocket receives a request from a client, where
- it will return a Socket back to the accept thread who called the
- accept() method. As soon as this happens, the accept thread will try
- to pass off the Socket to another thread for processing. </para>
-
- <para>The threads that actually process the incoming request,
- referred to as server threads, are stored in a pool. The accept
- thread will try to retreive the first available server thread from
- the pool and hand off the Socket for processing. If the pool does
- not contain any available server threads and the max pool size has
- not been reached, a new server thread will be created for
- processing. Otherwise, if the max pool size has been reached, the
- accept thread will wait for one to become available (will wait until
- socket timeout has been reached). The size of the server thread pool
- is defined by the 'maxPoolSize' property. As soon as the accept
- thread has been able to hand off the Socket to a server thread for
- processing, it will loop back to ServerSocket and call accept() on
- it again. This will continue until the socket server invoker is
- stopped.</para>
+ called the accept threads and the number of them created is controlled
+ by the 'numAcceptThreads' property. When these accept threads are
+ started, they will call accept() on the ServerSocket and block until
+ the ServerSocket receives a request from a client, where it will
+ return a Socket back to the accept thread who called the accept()
+ method. As soon as this happens, the accept thread will try to pass
+ off the Socket to another thread for processing.</para>
+
+ <para>The threads that actually process the incoming request, referred
+ to as server threads, are stored in a pool. The accept thread will try
+ to retreive the first available server thread from the pool and hand
+ off the Socket for processing. If the pool does not contain any
+ available server threads and the max pool size has not been reached, a
+ new server thread will be created for processing. Otherwise, if the
+ max pool size has been reached, the accept thread will wait for one to
+ become available (will wait until socket timeout has been reached).
+ The size of the server thread pool is defined by the 'maxPoolSize'
+ property. As soon as the accept thread has been able to hand off the
+ Socket to a server thread for processing, it will loop back to
+ ServerSocket and call accept() on it again. This will continue until
+ the socket server invoker is stopped.</para>
<para>The server thread processing the request will be the thread of
- execution through the unmarshalling of the data, calling on the
- server invocation handler, and marshalling of response back to the
- client. After the response has been sent, the server thread will
- then hold the socket connection and wait for another request to come
- from this client. It will wait until the socket is closed by the
- client, a socket timeout occurs, or receives another request from
- the client in which to process. When the client socket connection
- session is closed, meaning timeout or client closed socket
- connection, then the thread will return itself to the pool.</para>
-
- <para>If all the server threads from the pool are in use, meaning
- have a client connection established, and the pool has reached its
- maximum value, the accept threads (no matter how many there are)
- will have to wait until one of the server threads is available for
- processing. This why having a large number of accept threads does
- not provide any real benefit. If all the accept threads are blocked
- waiting for server thread, new client requests will then be queued
- until it can be accepted. The number of requests that can be queued
- is controlled by the backlog and can be useful in managing sudden
- bursts in requests.</para>
+ execution through the unmarshalling of the data, calling on the server
+ invocation handler, and marshalling of response back to the client.
+ After the response has been sent, the server thread will then hold the
+ socket connection and wait for another request to come from this
+ client. It will wait until the socket is closed by the client, a
+ socket timeout occurs, or receives another request from the client in
+ which to process. When the client socket connection session is closed,
+ meaning timeout or client closed socket connection, then the thread
+ will return itself to the pool.</para>
+
+ <para>If all the server threads from the pool are in use, meaning have
+ a client connection established, and the pool has reached its maximum
+ value, the accept threads (no matter how many there are) will have to
+ wait until one of the server threads is available for processing. This
+ why having a large number of accept threads does not provide any real
+ benefit. If all the accept threads are blocked waiting for server
+ thread, new client requests will then be queued until it can be
+ accepted. The number of requests that can be queued is controlled by
+ the backlog and can be useful in managing sudden bursts in
+ requests.</para>
<para>If take an example with a socket server invoker that has max
- pool set to 300, accept threads is 2, and backlog is 200, will be
- able to make 502 concurrent client calls. The 503rd client request
- will get an exception immediately. However, this does not mean all
- 502 requests will be guaranteed to be processed, only the first 300
- (as they have server threads available to do the processing). If 202
- of the server threads finish processing their requests from their
- initial client connections and the connection is released before the
- timeout for the other 202 that are waiting (200 for backlog and 2
- for accept thread), then they will be processed (of course this is a
- request by request determination).</para>
+ pool set to 300, accept threads is 2, and backlog is 200, will be able
+ to make 502 concurrent client calls. The 503rd client request will get
+ an exception immediately. However, this does not mean all 502 requests
+ will be guaranteed to be processed, only the first 300 (as they have
+ server threads available to do the processing). If 202 of the server
+ threads finish processing their requests from their initial client
+ connections and the connection is released before the timeout for the
+ other 202 that are waiting (200 for backlog and 2 for accept thread),
+ then they will be processed (of course this is a request by request
+ determination).</para>
<bridgehead>client</bridgehead>
<para>When the socket client invoker makes its first invocation, it
will check to see if there is an available socket connection in its
- pool. Since is the first invocation, there will not be and will
- create a new socket connection and use it for making the invocation.
- Then when finished making invocation, will return the still active
- socket connection to the pool. As more client invocations are made,
- is possible for the number of socket connections to reach the
- maximum allowed (which is controlled by 'clientMaxPoolSize'
- property). At this point, when the next client invocation is made,
- it will keep trying to get an available connection from the pool,
- waiting 1 second in between tries for up to maximum number of
- retries (which is controlled by the numberOfRetries property). If
- runs out of retries, will throw SocketException saying how long it
- waited to find available socket connection.</para>
+ pool. Since is the first invocation, there will not be and will create
+ a new socket connection and use it for making the invocation. Then
+ when finished making invocation, will return the still active socket
+ connection to the pool. As more client invocations are made, is
+ possible for the number of socket connections to reach the maximum
+ allowed (which is controlled by 'clientMaxPoolSize' property). At this
+ point, when the next client invocation is made, it will keep trying to
+ get an available connection from the pool, waiting 1 second in between
+ tries for up to maximum number of retries (which is controlled by the
+ numberOfRetries property). If runs out of retries, will throw
+ SocketException saying how long it waited to find available socket
+ connection.</para>
<para>Once the socket client invoker goes get an available socket
- connection from the pool, are not out of the woods yet. There is
- still a possibility that the socket connection returned, while still
+ connection from the pool, are not out of the woods yet. There is still
+ a possibility that the socket connection returned, while still
appearing to be valid, has timed out while sitting in the pool. So if
- discover this while trying to make invocation, will throw it away
- and retry the whole process again. Will do this up to the number set
- by the numberOfCallRetries before throwing an exception. The trick
- here is that when get to numberOfCallRetries -2, will assume that
- any socket connection gotten from the pool will have timed out and
- will flush the pool all together so that the next retry will cause a
- new socket connection to be recreated. A typical scenario when this
- might occur is when have had a burst of client invocations and then
- a long period of inactivity.</para>
+ discover this while trying to make invocation, will throw it away and
+ retry the whole process again. Will do this up to the number set by
+ the numberOfCallRetries before throwing an exception. The trick here
+ is that when get to numberOfCallRetries -2, will assume that any
+ socket connection gotten from the pool will have timed out and will
+ flush the pool all together so that the next retry will cause a new
+ socket connection to be recreated. A typical scenario when this might
+ occur is when have had a burst of client invocations and then a long
+ period of inactivity.</para>
</section>
</section>
@@ -1141,26 +1120,24 @@
<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>
+ <classname>SSLServerSocketFactory</classname>. See section <xref
+ linkend="section-socket-factories" /> for more information.</para>
</section>
<section>
<title>RMI Invoker</title>
- <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>
+ <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>
@@ -1169,29 +1146,28 @@
<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> The SSL 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. If the SSL RMI server invoker is allowed to create an
+ <para><emphasis role="bold">Note.</emphasis> The SSL 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. If the SSL RMI
+ server invoker is allowed to create an
<classname>SSLSocketFactory</classname> from SSL parameters, as
- discussed in section <xref linkend="section-socket-factories"/>, it will
- take care to create a serializable socket factory. However, if a
+ discussed in section <xref linkend="section-socket-factories" />, it
+ will take care to create a serializable socket factory. However, if a
socket factory is passed in to the server invoker (also discussed in
- section <xref linkend="section-socket-factories"/>),
- then the user is responsible for supplying a serializable socket
- factory. See <xref linkend="subsection-sslrmi"/> below for more
- information. </para>
+ section <xref linkend="section-socket-factories" />), then the user is
+ responsible for supplying a serializable socket factory. See <xref
+ linkend="subsection-sslrmi" /> below for more information.</para>
</section>
<section id="section-http-invoker" xreflabel="HTTP Invoker">
<title>HTTP Invoker</title>
<para>The HTTP server invoker implementation is based on the Apache
- Tomcat connector components which support GET, POST, HEAD, OPTIONS,
- and HEAD method types and keep-alive. Therefore, most any
- configuration allowed for Tomcat can be configured for the remoting
- HTTP server invoker. For more information on the configuration
- attributes available for the Tomcat connectors, please refer to <ulink
+ Tomcat connector components which support GET, POST, HEAD, OPTIONS, and
+ HEAD method types and keep-alive. Therefore, most any configuration
+ allowed for Tomcat can be configured for the remoting HTTP server
+ invoker. For more information on the configuration attributes available
+ for the Tomcat connectors, please refer to <ulink
url="http://tomcat.apache.org/tomcat-5.5-doc/config/http.htm">http://tomcat.apache.org/tomcat-5.5-doc/config/http.htm</ulink>.
<!--<link linkend="???">http://tomcat.apache.org/tomcat-5.5-doc/config/http.html</link>-->
So for example, if wanted to set the maximum number of threads to be
@@ -1201,55 +1177,54 @@
serverBindAddress instead) and attribute 'port' (use serverBindPort
instead).</para>
- <para>Note: The http invoker no longer has the configuration
- attributes 'maxNumThreadsHTTP' or 'HTTPThreadPool' as thread pooling
- is now handled within the Tomcat connectors, which does not expose
- external API for setting these.</para>
+ <para>Note: The http invoker no longer has the configuration attributes
+ 'maxNumThreadsHTTP' or 'HTTPThreadPool' as thread pooling is now handled
+ within the Tomcat connectors, which does not expose external API for
+ setting these.</para>
<para>Since the remoting HTTP server invoker implementation is using
Tomcat connectors, is possible to swap out the Tomcat protocol
implementations being used. By default, the protocol being used is
<code>org.apache.coyote.http11.Http11Protocol</code>. However, it is
possible to switch to use the
- <code>org.apache.coyote.http11.Http11AprProtocol</code> protocol,
- which is based on the Apache Portable Runtime (see <ulink
+ <code>org.apache.coyote.http11.Http11AprProtocol</code> protocol, which
+ is based on the Apache Portable Runtime (see <ulink
url="http://tomcat.apache.org/tomcat-5.5-doc/apr.html">http://tomcat.apache.org/tomcat-5.5-doc/apr.html</ulink>
and <ulink url="http://apr.apache.org/">http://apr.apache.org/</ulink>
- for more
- details). If want to use the APR implementation, simply put the
+ for more details). If want to use the APR implementation, simply put the
tcnative-1.dll (or tcnative-1.so) on the system path so can be loaded.
The APR native binaries can be found at <ulink
url="http://tomcat.heanet.ie">http://tomcat.heanet.ie</ulink>.</para>
- <para>Note: There is a bug with release 1.1.1 of APR where get an
- error upon shutting down (see JBREM-277 for more information). This
- does not impact anything while running, but is still an issue when
- shutting down (as upon starting up again, can get major problems).
- This should be fixed in a later release of APR so can just
- replace the 1.1.1 version of tcnative-1.dll with the new one.</para>
+ <para>Note: There is a bug with release 1.1.1 of APR where get an error
+ upon shutting down (see JBREM-277 for more information). This does not
+ impact anything while running, but is still an issue when shutting down
+ (as upon starting up again, can get major problems). This should be
+ fixed in a later release of APR so can just replace the 1.1.1 version of
+ tcnative-1.dll with the new one.</para>
<bridgehead>Client request headers</bridgehead>
- <para>The HTTP Invoker allows for some of the properties to be passed
- as request headers from client caller. The following are possible http
+ <para>The HTTP Invoker allows for some of the properties to be passed as
+ request headers from client caller. The following are possible http
headers and what they mean:</para>
<para><emphasis role="bold">sessionId</emphasis> - is the remoting
session id to identify the client caller. If this is not passed, the
- HTTP server invoker will try to create a session id based on
- information that is passed. Note, this means if the sessionId is not
- passed as part of the header, there is no guarantee that the sessionId
- supplied to the invocation handler will always indicate the request
- from the same client.</para>
-
- <para><emphasis role="bold">subsystem</emphasis> - the subsystem to
- call upon (which invoker handler to call upon). If there is more than
- one handler per Connector, this will need to be set (otherwise will
- just use the only one available).</para>
-
- <para>These request headers are set automatically when using a
- remoting client, but if using another client to send request to the
- HTTP server invoker, may want to add these headers.</para>
+ HTTP server invoker will try to create a session id based on information
+ that is passed. Note, this means if the sessionId is not passed as part
+ of the header, there is no guarantee that the sessionId supplied to the
+ invocation handler will always indicate the request from the same
+ client.</para>
+
+ <para><emphasis role="bold">subsystem</emphasis> - the subsystem to call
+ upon (which invoker handler to call upon). If there is more than one
+ handler per Connector, this will need to be set (otherwise will just use
+ the only one available).</para>
+
+ <para>These request headers are set automatically when using a remoting
+ client, but if using another client to send request to the HTTP server
+ invoker, may want to add these headers.</para>
</section>
<section>
@@ -1262,25 +1237,24 @@
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>
+ <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>
<title>HTTP(S) Client Invoker - proxy and basic authentication</title>
<para>This section covers configuration specific to the HTTP Client
- Invoker only and is NOT related to HTTP(S) invoker configuration on
- the server side (via service xml).</para>
+ Invoker only and is NOT related to HTTP(S) invoker configuration on the
+ server side (via service xml).</para>
<bridgehead>proxy</bridgehead>
- <para>There are a few ways in which to enable http proxy using the
- HTTP client invoker. The first is simply to add the following
- properties to the metadata Map passed on the Client's invoke() method:
+ <para>There are a few ways in which to enable http proxy using the HTTP
+ client invoker. The first is simply to add the following properties to
+ the metadata Map passed on the Client's invoke() method:
<code>http.proxyHost</code> and <code>http.proxyPort</code>.</para>
<para>An example would be:</para>
@@ -1301,11 +1275,11 @@
<para>The http.proxyPort property is not required and if not present,
will use default of 80.</para>
- <para>The other way to enable use of an http proxy server from the
- HTTP client invoker is to set the following system properties (either
- via <code>System.setProperty()</code> method call or via JVM
- arguments): <code>http.proxyHost</code>, <code>http.proxyPort</code>,
- and <code>proxySet</code>.</para>
+ <para>The other way to enable use of an http proxy server from the HTTP
+ client invoker is to set the following system properties (either via
+ <code>System.setProperty()</code> method call or via JVM arguments):
+ <code>http.proxyHost</code>, <code>http.proxyPort</code>, and
+ <code>proxySet</code>.</para>
<para>An example would be setting the following JVM arguments:</para>
@@ -1319,9 +1293,9 @@
<bridgehead>Basic authentication - direct and via proxy</bridgehead>
- <para>The HTTP client invoker also has support for BASIC
- authentication for both proxied and non-proxied invocations. For
- proxied invocations, the following properties need to be set:
+ <para>The HTTP client invoker also has support for BASIC authentication
+ for both proxied and non-proxied invocations. For proxied invocations,
+ the following properties need to be set:
<code>http.proxy.username</code> and
<code>http.proxy.password</code>.</para>
@@ -1329,11 +1303,11 @@
set: <code>http.basic.username</code> and
<code>http.basic.password</code>.</para>
- <para>For setting either proxied or non-proxied properties, can be
- done via the metadata map or system properties (see setting proxy
- properties above for how to). However, for authentication properties,
- values set in the metadata Map will take precedence over those set
- within the system properties.</para>
+ <para>For setting either proxied or non-proxied properties, can be done
+ via the metadata map or system properties (see setting proxy properties
+ above for how to). However, for authentication properties, values set in
+ the metadata Map will take precedence over those set within the system
+ properties.</para>
<para>Note: Only the proxy authentication has been tested using Apache
2.0.48; non-proxied authentication has not.</para>
@@ -1342,12 +1316,12 @@
authentication in this great world of web, not all possible
configurations have been tested (or even supported). If you find a
particular problem or see that a particular implementation is not
- supported, please enter an issue in Jira
- (<ulink url="http://jira.jboss.com">http://jira.jboss.com</ulink>)
- under the JBossRemoting project, as this is where bugs and feature
- requests belong. If after reading the documentation have unanswered
- questions about how to use these features, please post them to the
- remoting forum (<ulink
+ supported, please enter an issue in Jira (<ulink
+ url="http://jira.jboss.com">http://jira.jboss.com</ulink>) under the
+ JBossRemoting project, as this is where bugs and feature requests
+ belong. If after reading the documentation have unanswered questions
+ about how to use these features, please post them to the remoting forum
+ (<ulink
url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=222">
http://www.jboss.org/index.html?module=bb&op=viewforum&f=222
</ulink>).</para>
@@ -1356,31 +1330,30 @@
<para>During the SSL handshake when making client calls using https
transport, if the URL's hostname and the server's identification
- hostname mismatch, a javax.net.ssl.HostnameVerifier implementation
- will be called to determine if this connection should be allowed. The
- default implementation will not allow this. To override this behavior
- to allow this by changing the HostnameVerifier implementation, can use
- the 'org.jboss.security.ignoreHttpsHost' property'. This property can
- either be set using a system property or within the metadata Map
- passed to the Client's invoke() method (which will override both the
- default value and the setting from the system property).</para>
+ hostname mismatch, a javax.net.ssl.HostnameVerifier implementation will
+ be called to determine if this connection should be allowed. The default
+ implementation will not allow this. To override this behavior to allow
+ this by changing the HostnameVerifier implementation, can use the
+ 'org.jboss.security.ignoreHttpsHost' property'. This property can either
+ be set using a system property or within the metadata Map passed to the
+ Client's invoke() method (which will override both the default value and
+ the setting from the system property).</para>
</section>
<section>
<title>Servlet Invoker</title>
- <para>The servlet invoker is a server invoker implementation that uses
- a servlet running within a web container to accept initial client
+ <para>The servlet invoker is a server invoker implementation that uses a
+ servlet running within a web container to accept initial client
invocation requests. The servlet request is then passed on to the
servlet invoker for processing.</para>
<para>The deployment for this particular server invoker is a little
- different than the other server invokers since a web deployment is
- also required. To start, the servlet invoker will need to be
- configured and deployed. This can be done by adding the Connector
- MBean service to an existing service xml or creating a new one. The
- following is an example of how to declare a Connector that uses the
- servlet invoker:</para>
+ different than the other server invokers since a web deployment is also
+ required. To start, the servlet invoker will need to be configured and
+ deployed. This can be done by adding the Connector MBean service to an
+ existing service xml or creating a new one. The following is an example
+ of how to declare a Connector that uses the servlet invoker:</para>
<programlisting>
<mbean code="org.jboss.remoting.transport.Connector"
@@ -1404,18 +1377,18 @@
</mbean>
</programlisting>
- <para>An important point of configuration to note is that the value
- 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 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>
+ <para>An important point of configuration to note is that the value 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 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>
<para>The next step is to configure and deploy the servlet that fronts
the servlet invoker. The pre-built deployment file for this servlet is
- the servlet-invoker.war file (which can be found in lib directory of
- the release distribution or under the output/lib/ directory if doing a
+ the servlet-invoker.war file (which can be found in lib directory of the
+ release distribution or under the output/lib/ directory if doing a
source build). By default, it is actually an exploded war, so the
servlet-invoker.war is actually a directory so that can be more easily
configured (feel free to zip up into an actual war file if prefer). In
@@ -1453,47 +1426,45 @@
</servlet-mapping>
</web-app></programlisting>
- <para>There are two ways in which the servlet can obtain a reference
- to the servlet server invoker it needs to pass its request onto. The
- first is by using the param 'invokerName', as is shown above. The
- value for this should be the JMX ObjectName for the servlet server
- invoker that was deployed as a service mbean (see service xml above).
- The other way is to provide a param 'locatorUrl' with a value that
- matches the locator url of the servlet server invoker to use. In this
- case, will use the InvokerRegistry to find the server invoker instead
- of using JMX, which is useful if not deploying server invoker as a
- mbean service or if want to run in web container other than the JBoss
- application server. Note, one or the other param is required. If both
- are provided, the 'locatorUrl' param take precedence.</para>
+ <para>There are two ways in which the servlet can obtain a reference to
+ the servlet server invoker it needs to pass its request onto. The first
+ is by using the param 'invokerName', as is shown above. The value for
+ this should be the JMX ObjectName for the servlet server invoker that
+ was deployed as a service mbean (see service xml above). The other way
+ is to provide a param 'locatorUrl' with a value that matches the locator
+ url of the servlet server invoker to use. In this case, will use the
+ InvokerRegistry to find the server invoker instead of using JMX, which
+ is useful if not deploying server invoker as a mbean service or if want
+ to run in web container other than the JBoss application server. Note,
+ one or the other param is required. If both are provided, the
+ 'locatorUrl' param take precedence.</para>
<para>This file can be changed to meet any web requirements you might
have, such as adding security (see sslservlet) or changing the actual
url context that the servlet maps to. If the url that the servlet maps
to is changed, will need to change the value for the InvokerLocator in
- the Connector configuration mentioned above. </para>
+ the Connector configuration mentioned above.</para>
<bridgehead>Issues</bridgehead>
- <para>One of the issues of using Servlet invoker is that the
- invocation handlers (those that implement ServerInvocationHandler) can
- not return very much detail in regards to a web context. For example,
- the content type used for the response is the same as that of the
- request.</para>
+ <para>One of the issues of using Servlet invoker is that the invocation
+ handlers (those that implement ServerInvocationHandler) can not return
+ very much detail in regards to a web context. For example, the content
+ type used for the response is the same as that of the request.</para>
</section>
<section>
<title>SSL Servlet Invoker</title>
- <para>The SSL Servlet Invoker is exactly the same as its parent,
- Servlet Invoker, with the exception that it uses the protocol of
- 'sslservlet'. On the server side it is deployed exactly the same as a
- servlet invoker would be but requires setting up ssl within the web
- container (i.e. enabling the ssl connector within Tomcat's
- server.xml). This will usually require specifing a different port as
- well.</para>
+ <para>The SSL Servlet Invoker is exactly the same as its parent, Servlet
+ Invoker, with the exception that it uses the protocol of 'sslservlet'.
+ On the server side it is deployed exactly the same as a servlet invoker
+ would be but requires setting up ssl within the web container (i.e.
+ enabling the ssl connector within Tomcat's server.xml). This will
+ usually require specifing a different port as well.</para>
- <para>An example of the mbean service xml for deploying the ssl
- servlet server invoker would be:</para>
+ <para>An example of the mbean service xml for deploying the ssl servlet
+ server invoker would be:</para>
<programlisting> <?xml version="1.0" encoding="UTF-8"?>
@@ -1516,7 +1487,7 @@
</server> </programlisting>
<para>An example of servlet-invoker.war/WEB-INF/web.xml for the ssl
- server invoker servlet would be: </para>
+ server invoker servlet would be:</para>
<programlisting> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC
@@ -1548,35 +1519,34 @@
<section>
<title>Exception handling for web based clients</title>
- <para>Web based clients, meaning remoting clients that call on web
- based remoting servers (i.e. http, https, servlet, and sslservlet)
- have special needs when it comes to handling exceptions that come from
- the servers they are calling on. The main reason for this is that
- depending on what type of server they are calling on, they might
- receive the error in different formats.</para>
+ <para>Web based clients, meaning remoting clients that call on web based
+ remoting servers (i.e. http, https, servlet, and sslservlet) have
+ special needs when it comes to handling exceptions that come from the
+ servers they are calling on. The main reason for this is that depending
+ on what type of server they are calling on, they might receive the error
+ in different formats.</para>
<para>By default, web based clients will throw an exception when the
response code from the server is greater than 400. The exact exception
type thrown will depend on the type of web server the client is
- interacting with. If it is a JBoss Remoting server (http or https
- server invoker), the exception thrown will be the one originally
- generated on the server side. If the server is not a JBoss Remoting
- server (e.g. JBossAS, Tomcat, Apache Web Server, etc.), the exception
- throw will be
- <code>org.jboss.test.remoting.transport.http.WebServerError</code>.
- The WebServerError's message will be the error html returned by the
- web server. To turn off the throwing of an exception when the web
- server responds with an error, can add config to the configuration map
- passed to the <code>Client.invoke()</code> method where they key is
- <code>HTTPMetadataConstants.NO_THROW_ON_ERROR</code> (actual text
- value 'NoThrowOnError') and a value of of type java.lang.String set to
- 'true'. This will cause the http client invoker to not throw an
- exception, but instead return the data from the web server error
- stream. In the case that the data returned from this error stream is
- of type java.lang.String (i.e. is error html), it will be wrapped in a
+ interacting with. If it is a JBoss Remoting server (http or https server
+ invoker), the exception thrown will be the one originally generated on
+ the server side. If the server is not a JBoss Remoting server (e.g.
+ JBossAS, Tomcat, Apache Web Server, etc.), the exception throw will be
+ <code>org.jboss.test.remoting.transport.http.WebServerError</code>. The
+ WebServerError's message will be the error html returned by the web
+ server. To turn off the throwing of an exception when the web server
+ responds with an error, can add config to the configuration map passed
+ to the <code>Client.invoke()</code> method where they key is
+ <code>HTTPMetadataConstants.NO_THROW_ON_ERROR</code> (actual text value
+ 'NoThrowOnError') and a value of of type java.lang.String set to 'true'.
+ This will cause the http client invoker to not throw an exception, but
+ instead return the data from the web server error stream. In the case
+ that the data returned from this error stream is of type
+ java.lang.String (i.e. is error html), it will be wrapped in a
WebServerError and returned as this type. The raw data from the web
- server can the be retrieved by getting the WebServerError's message.
- </para>
+ server can the be retrieved by getting the WebServerError's
+ message.</para>
</section>
<section id="section-multiplex-invoker" xreflabel="Multiplex Invoker">
@@ -1584,12 +1554,12 @@
<para>The multiplex invoker is intended to replicate the functionality
of the socket invoker with the added feature that it supports multiple
- streams of communication over a single pair of sockets. Multiplexing
- may be motivated by, for example, a desire to conserve socket
- resources or by firewall restrictions on port availability. This
- additional service is made possible by the Multiplex subproject, which
- provides "virtual" sockets and "virtual" server sockets. Please refer
- to the Multiplex documentation at</para>
+ streams of communication over a single pair of sockets. Multiplexing may
+ be motivated by, for example, a desire to conserve socket resources or
+ by firewall restrictions on port availability. This additional service
+ is made possible by the Multiplex subproject, which provides "virtual"
+ sockets and "virtual" server sockets. Please refer to the Multiplex
+ documentation at</para>
<blockquote>
<para><ulink
@@ -1599,15 +1569,15 @@
<para>for further details.</para>
- <para>In a typical multiplexed scenario a
- <classname>Client</classname> on a client host, through a
+ <para>In a typical multiplexed scenario a <classname>Client</classname>
+ on a client host, through a
<classname>MultiplexClientInvoker</classname> <emphasis>C</emphasis>,
could make synchronous method invocations to a
<classname>MultiplexServerInvoker</classname> on a server host, and at
the same time (and over the same TCP connection) asynchronous push
callbacks could be made to a
- <classname>MultiplexServerInvoker</classname> <emphasis>S</emphasis>
- on the client host. In this, the <emphasis role="bold">Prime
+ <classname>MultiplexServerInvoker</classname> <emphasis>S</emphasis> on
+ the client host. In this, the <emphasis role="bold">Prime
Scenario</emphasis>, which motivated the creation of the multiplex
invoker, <emphasis>C</emphasis> and <emphasis>S</emphasis> use two
different virtual sockets but share the same port and same actual
@@ -1615,14 +1585,14 @@
belong to the same <emphasis role="bold">invoker
group</emphasis>.</para>
- <para>One of the primary design goals of the Multiplex subsystem is
- for virtual sockets and virtual server sockets to demonstrate behavior
- as close as possible to their real counterparts, and, indeed, they
+ <para>One of the primary design goals of the Multiplex subsystem is for
+ virtual sockets and virtual server sockets to demonstrate behavior as
+ close as possible to their real counterparts, and, indeed, they
implement complete socket and server socket APIs. However, they are
necessarily different in some respects, and it follows that the
multiplex invoker is somewhat different than the socket invoker. In
- particular, there are three areas specific to the multiplex invoker
- that must be understood in order to use it effectively:</para>
+ particular, there are three areas specific to the multiplex invoker that
+ must be understood in order to use it effectively:</para>
<orderedlist>
<listitem>
@@ -1631,8 +1601,8 @@
</listitem>
<listitem>
- <para>Configuring the client for multiplexed method invocations
- and callbacks</para>
+ <para>Configuring the client for multiplexed method invocations and
+ callbacks</para>
</listitem>
<listitem>
@@ -1647,33 +1617,32 @@
<classname>MultiplexServerInvoker</classname>s, <emphasis
role="bold">master</emphasis> and <emphasis
role="bold">virtual</emphasis>, corresponding to the two kinds of
- virtual server sockets: <classname>MasterServerSocket</classname>
- and <classname>VirtualServerSocket</classname>. Briefly, the
- difference between the two virtual server socket classes is that a
+ virtual server sockets: <classname>MasterServerSocket</classname> and
+ <classname>VirtualServerSocket</classname>. Briefly, the difference
+ between the two virtual server socket classes is that a
<classname>MasterServerSocket</classname> is derived from
<classname>java.net.ServerSocket</classname> and its
- <methodname>accept()</methodname> method is implemented by way of
- the inherited method <methodname>super.accept()</methodname>. A
- <classname>MasterServerSocket</classname> can accept connect
- requests from multiple machines. A
- <classname>VirtualServerSocket</classname>, on the other hand, is
- based on an actual socket connected to another actual socket on some
- host <emphasis>H</emphasis>, and consequently a
- <classname>VirtualServerSocket</classname> can accept connect
- requests only from <emphasis>H</emphasis>.</para>
+ <methodname>accept()</methodname> method is implemented by way of the
+ inherited method <methodname>super.accept()</methodname>. A
+ <classname>MasterServerSocket</classname> can accept connect requests
+ from multiple machines. A <classname>VirtualServerSocket</classname>,
+ on the other hand, is based on an actual socket connected to another
+ actual socket on some host <emphasis>H</emphasis>, and consequently a
+ <classname>VirtualServerSocket</classname> can accept connect requests
+ only from <emphasis>H</emphasis>.</para>
<para>Each multiplex connection depends on a pair of connected real
sockets, one on the client host and one on the server host, and this
- connection is created when an actual socket contacts an actual
- server socket. It follows that a multiplex connection begins with a
+ connection is created when an actual socket contacts an actual server
+ socket. It follows that a multiplex connection begins with a
connection request to a <classname>MasterServerSocket</classname>.
Once the connection is established, it is possible to build up
- <emphasis role="bold">virtual socket groups</emphasis>, consisting
- of virtual sockets (and at most one
+ <emphasis role="bold">virtual socket groups</emphasis>, consisting of
+ virtual sockets (and at most one
<classname>VirtualServerSocket</classname>) revolving around the
- actual socket at each end of the connection. Each virtual socket in
- a socket group at one end is connected to a virtual socket in the
- socket group at the other end.</para>
+ actual socket at each end of the connection. Each virtual socket in a
+ socket group at one end is connected to a virtual socket in the socket
+ group at the other end.</para>
<para>Master and virtual
<classname>MultiplexServerInvoker</classname>s assume the
@@ -1682,39 +1651,38 @@
<classname>VirtualServerSocket</classname>, respectively. That is, a
master <classname>MultiplexServerInvoker</classname> can accept
requests from any host, while a virtual
- <classname>MultiplexServerInvoker</classname> can accept requests
- only from the particular host to which it has a multiplex
- connection. Since a multiplex connection begins with a connection
- request to a <classname>MasterServerSocket</classname>, it follows
- that the use of the multiplex invoker must begin with a connection
- request from the client (made by either a
- <classname>MultiplexClientInvoker</classname> or a virtual
- <classname>MultiplexServerInvoker</classname>: see below) to a
- master <classname>MultiplexServerInvoker</classname> on the server.
- The master <classname>MultiplexServerInvoker</classname> responds by
- "cloning" itself (metaphorically, not necessarily through the use of
- <methodname>clone()</methodname>) into a virtual
- <classname>MultiplexServerInvoker</classname> with the same
- parameters and same set of invocation handlers but with a
+ <classname>MultiplexServerInvoker</classname> can accept requests only
+ from the particular host to which it has a multiplex connection. Since
+ a multiplex connection begins with a connection request to a
+ <classname>MasterServerSocket</classname>, it follows that the use of
+ the multiplex invoker must begin with a connection request from the
+ client (made by either a <classname>MultiplexClientInvoker</classname>
+ or a virtual <classname>MultiplexServerInvoker</classname>: see below)
+ to a master <classname>MultiplexServerInvoker</classname> on the
+ server. The master <classname>MultiplexServerInvoker</classname>
+ responds by "cloning" itself (metaphorically, not necessarily through
+ the use of <methodname>clone()</methodname>) into a virtual
+ <classname>MultiplexServerInvoker</classname> with the same parameters
+ and same set of invocation handlers but with a
<classname>VirtualServerSocket</classname> belonging to a new socket
group. In so doing the master
<classname>MultiplexServerInvoker</classname> builds up a <emphasis
role="bold">server invoker farm</emphasis> of virtual
- <classname>MultiplexServerInvoker</classname>s, each in contact with
- a different <classname>MultiplexClientInvoker</classname> over a
+ <classname>MultiplexServerInvoker</classname>s, each in contact with a
+ different <classname>MultiplexClientInvoker</classname> over a
distinct multiplex connection. The virtual
<classname>MultiplexServerInvoker</classname>s do the actual work of
- responding to method invocation requests, sent by their
- corresponding <classname>MultiplexClientInvoker</classname>s through
- virtual sockets in a socket group at the client end of a multiplex
- connection to virtual sockets created by the
- <classname>VirtualServerSocket</classname> in the socket group at
- the server end of the connection. Note that virtual
+ responding to method invocation requests, sent by their corresponding
+ <classname>MultiplexClientInvoker</classname>s through virtual sockets
+ in a socket group at the client end of a multiplex connection to
+ virtual sockets created by the
+ <classname>VirtualServerSocket</classname> in the socket group at the
+ server end of the connection. Note that virtual
<classname>MultiplexServerInvoker</classname>s share data structures
with the master, so that registering invocation handlers with the
- master makes them available to the members of the farm. The members
- of a master <classname>MultiplexServerInvoker</classname>'s invoker
- farm are accessible by way of the methods</para>
+ master makes them available to the members of the farm. The members of
+ a master <classname>MultiplexServerInvoker</classname>'s invoker farm
+ are accessible by way of the methods</para>
<blockquote>
<orderedlist>
@@ -1730,34 +1698,33 @@
</blockquote>
<para>the latter of which returns a virtual
- <classname>MultiplexServerInvoker</classname> keyed on the address
- to which its <classname>VirtualServerSocket</classname> is
- connected. When the master
- <classname>MultiplexServerInvoker</classname> shuts down, its farm
- of virtual invokers shuts down as well</para>
+ <classname>MultiplexServerInvoker</classname> keyed on the address to
+ which its <classname>VirtualServerSocket</classname> is connected.
+ When the master <classname>MultiplexServerInvoker</classname> shuts
+ down, its farm of virtual invokers shuts down as well</para>
<para>There are two ways of constructing a virtual
<classname>MultiplexServerInvoker</classname>, one being the cloning
- method just discussed. It is also possible to construct one
- directly. Once a multiplex connection is established, a virtual
+ method just discussed. It is also possible to construct one directly.
+ Once a multiplex connection is established, a virtual
<classname>MultiplexServerInvoker</classname> can be created with a
- <classname>VirtualServerSocket</classname> belonging to a socket
- group at one end of the connection. The
+ <classname>VirtualServerSocket</classname> belonging to a socket group
+ at one end of the connection. The
<classname>MultiplexServerInvoker</classname> constructor determines
whether to create a virtual or master invoker according to the
presence or absence of certain parameters, discussed below, that may
- be added to its <classname>InvokerLocator</classname>. Server rules
- 1 through 3 described below result in the construction of a virtual
- <classname>MultiplexServerInvoker</classname>, and server rule 4
- (the absence of these parameters) results in the construction of a
- master <classname>MultiplexServerInvoker</classname>.</para>
+ be added to its <classname>InvokerLocator</classname>. Server rules 1
+ through 3 described below result in the construction of a virtual
+ <classname>MultiplexServerInvoker</classname>, and server rule 4 (the
+ absence of these parameters) results in the construction of a master
+ <classname>MultiplexServerInvoker</classname>.</para>
<para>Setting up the server, then, is simply a matter of starting a
master <classname>MultiplexServerInvoker</classname> with a simple
<classname>InvokerLocator</classname>, unadorned with any parameters
specific to the multiplex invoker. As always, the server invoker is
- not created directly but by way of a
- <classname>Connector</classname>, as in the following:</para>
+ not created directly but by way of a <classname>Connector</classname>,
+ as in the following:</para>
<blockquote>
<programlisting>
@@ -1780,16 +1747,16 @@
followed by starting, on the client host, a
<classname>MultiplexClientInvoker</classname> <emphasis>C</emphasis>
and a virtual <classname>MultiplexServerInvoker</classname>
- <emphasis>S</emphasis> (in either order). The first to start
- initiates a multiplex connection to the master
+ <emphasis>S</emphasis> (in either order). The first to start initiates
+ a multiplex connection to the master
<classname>MultiplexServerInvoker</classname> and requests the
creation of a virtual <classname>MultiplexServerInvoker</classname>.
Note that it is crucial for <emphasis>C</emphasis> and
<emphasis>S</emphasis> to know that they are meant to share a
- multiplex connection, i.e., that they are meant to belong to the
- same invoker group. Consider the following attempt to set up a
- shared connection between hosts bluemonkey.acme.com and
- demo.jboss.com. First, <emphasis>C</emphasis> is initialized on host
+ multiplex connection, i.e., that they are meant to belong to the same
+ invoker group. Consider the following attempt to set up a shared
+ connection between hosts bluemonkey.acme.com and demo.jboss.com.
+ First, <emphasis>C</emphasis> is initialized on host
bluemonkey.acme.com with the <classname>InvokerLocator</classname>
multiplex://demo.jboss.com:8080, and, assuming the absence of an
existing multiplex connection to demo.jboss.com:8080, a new virtual
@@ -1799,33 +1766,31 @@
multiplex://bluemonkey.acme.com:4444, but since it needs to bind to
port 4444, it is unable to share the existing connection. [Actually,
the example is slightly deceptive, since
- multiplex://bluemonkey.acme.com:4040 would result in the creation of
- a master <classname>MultiplexServerInvoker</classname>. But if it
- were suitably extended with the parameters discussed below so that a
+ multiplex://bluemonkey.acme.com:4040 would result in the creation of a
+ master <classname>MultiplexServerInvoker</classname>. But if it were
+ suitably extended with the parameters discussed below so that a
virtual <classname>MultiplexServerInvoker</classname> were created,
the virtual invoker would be unable to share the existing
connection.]</para>
<para>So <emphasis>C</emphasis> and <emphasis>S</emphasis> need to
agree on the address and port of the real socket underlying the
- virtual socket group they are intended to share on the client host
- and the address and port of the real socket underlying the peer
- virtual socket group on the server host. Or, more succintly, they
- must know that they are meant to belong to the same invoker group.
- Note the relationship between an invoker group and the virtual
- socket group which supports it: a
- <classname>MultiplexClientInvoker</classname> uses virtual sockets
- in its underlying virtual socket group, and a
- <classname>MultiplexServerInvoker</classname> in an invoker group
- has a <classname>VirtualServerSocket</classname> that creates
- virtual sockets in the underlying virtual socket group.</para>
-
- <para><emphasis>C</emphasis> and <emphasis>S</emphasis> each get
- half of the information necessary to identify their invoker group
- directly from their respective
- <classname>InvokerLocator</classname>s. In particular,
- <emphasis>C</emphasis> gets the remote address and port, and
- <emphasis>S</emphasis> gets the binding address and port. The
+ virtual socket group they are intended to share on the client host and
+ the address and port of the real socket underlying the peer virtual
+ socket group on the server host. Or, more succintly, they must know
+ that they are meant to belong to the same invoker group. Note the
+ relationship between an invoker group and the virtual socket group
+ which supports it: a <classname>MultiplexClientInvoker</classname>
+ uses virtual sockets in its underlying virtual socket group, and a
+ <classname>MultiplexServerInvoker</classname> in an invoker group has
+ a <classname>VirtualServerSocket</classname> that creates virtual
+ sockets in the underlying virtual socket group.</para>
+
+ <para><emphasis>C</emphasis> and <emphasis>S</emphasis> each get half
+ of the information necessary to identify their invoker group directly
+ from their respective <classname>InvokerLocator</classname>s. In
+ particular, <emphasis>C</emphasis> gets the remote address and port,
+ and <emphasis>S</emphasis> gets the binding address and port. The
additional information may be provided through the use of <emphasis
role="bold">invoker group parameters</emphasis>, which may be
communicated to <emphasis>C</emphasis> and <emphasis>S</emphasis> in
@@ -1835,9 +1800,8 @@
<listitem>
<para>they may be appended to the
<classname>InvokerLocator</classname> passed to the
- <classname>Client</classname> which creates
- <emphasis>C</emphasis> and/or to the
- <classname>InvokerLocator</classname> passed to the
+ <classname>Client</classname> which creates <emphasis>C</emphasis>
+ and/or to the <classname>InvokerLocator</classname> passed to the
<classname>Connector</classname> which creates
<emphasis>S</emphasis></para>
</listitem>
@@ -1856,8 +1820,8 @@
<orderedlist>
<listitem>
- <para>The information can be provided explicitly by way of
- invoker group parameters:</para>
+ <para>The information can be provided explicitly by way of invoker
+ group parameters:</para>
<orderedlist>
<listitem>
@@ -1907,17 +1871,16 @@
<listitem>
<para>If <emphasis>C</emphasis> has a
<emphasis>clientMultiplexId</emphasis> parameter, it will use it
- to attempt to find a
- <classname>MultiplexServerInvoker</classname>
+ to attempt to find a <classname>MultiplexServerInvoker</classname>
<emphasis>S</emphasis> with a
<emphasis>serverMultiplexId</emphasis> parameter with the same
value. If it succeeds, it will retrieve binding host and port
values, create or reuse a suitable multiplex connection to the
- server, and start. Moreover, if <emphasis>S</emphasis> was
- unable to start because of insufficient information (server rule
- 3), then <emphasis>C</emphasis> will supply the missing
- information and <emphasis>S</emphasis> will start. Note that in
- this situation <emphasis>C</emphasis> will ignore any
+ server, and start. Moreover, if <emphasis>S</emphasis> was unable
+ to start because of insufficient information (server rule 3), then
+ <emphasis>C</emphasis> will supply the missing information and
+ <emphasis>S</emphasis> will start. Note that in this situation
+ <emphasis>C</emphasis> will ignore any
<emphasis>multiplexBindHost</emphasis> and
<emphasis>multiplexBindPort</emphasis> parameters passed to
it.</para>
@@ -1927,16 +1890,15 @@
<para>If <emphasis>C</emphasis> does not find a
<classname>MultiplexServerInvoker</classname> through a
multiplexId (either because it did not get a
- <emphasis>clientMultiplexId</emphasis> parameter or because
- there is no <classname>MultiplexServerInvoker</classname> with a
+ <emphasis>clientMultiplexId</emphasis> parameter or because there
+ is no <classname>MultiplexServerInvoker</classname> with a
matching multiplexId), but it does have
<emphasis>multiplexBindHost</emphasis> and
<emphasis>multiplexBindPort</emphasis> parameters, then it will
- create or reuse a suitable multiplex connection to the server,
- and start. Also, if it has a multiplexId, it will advertise
- itself for the benefit of a
- <classname>MultiplexServerInvoker</classname> that may come
- along later (see server rule 1).</para>
+ create or reuse a suitable multiplex connection to the server, and
+ start. Also, if it has a multiplexId, it will advertise itself for
+ the benefit of a <classname>MultiplexServerInvoker</classname>
+ that may come along later (see server rule 1).</para>
</listitem>
<listitem>
@@ -1954,9 +1916,9 @@
<para>If <emphasis>C</emphasis> has neither
<emphasis>clientMultiplexId</emphasis> nor
<emphasis>multiplexBindHost</emphasis> and
- <emphasis>multiplexBindPort</emphasis> parameters, it will
- create or reuse a multiplex connection from an arbitrary local
- port to the host and port given in its
+ <emphasis>multiplexBindPort</emphasis> parameters, it will create
+ or reuse a multiplex connection from an arbitrary local port to
+ the host and port given in its
<classname>InvokerLocator</classname>, and start.</para>
</listitem>
</orderedlist>
@@ -1970,19 +1932,17 @@
<listitem>
<para>If <emphasis>S</emphasis> has a
<emphasis>serverMultiplexId</emphasis> parameter, it will use it
- to attempt to find a
- <classname>MultiplexClientInvoker</classname>
+ to attempt to find a <classname>MultiplexClientInvoker</classname>
<emphasis>C</emphasis> with a matching
<emphasis>clientMultiplexId</emphasis>. If it succeeds, it will
retrieve server host and port values, create a
<classname>VirtualServerSocket</classname>, create or reuse a
- suitable multiplex connection to the server, and start.
- Moreover, if <emphasis>C</emphasis> was unable to start due to
- insufficient information (client rule 3), then
- <emphasis>S</emphasis> will supply the missing information and
- <emphasis>C</emphasis> will start. Note that in this situation
- <emphasis>S</emphasis> will ignore
- <emphasis>multiplexConnectHost</emphasis> and
+ suitable multiplex connection to the server, and start. Moreover,
+ if <emphasis>C</emphasis> was unable to start due to insufficient
+ information (client rule 3), then <emphasis>S</emphasis> will
+ supply the missing information and <emphasis>C</emphasis> will
+ start. Note that in this situation <emphasis>S</emphasis> will
+ ignore <emphasis>multiplexConnectHost</emphasis> and
<emphasis>multiplexConnectPort</emphasis> parameters, if any, in
its <classname>InvokerLocator</classname>.</para>
</listitem>
@@ -1991,17 +1951,16 @@
<para>If <emphasis>S</emphasis> does not find a
<classname>MultiplexClientInvoker</classname> through a
multiplexId (either because it did not get a
- <emphasis>serverMultiplexId</emphasis> parameter or because
- there is no <classname>MultiplexClientInvoker</classname> with a
+ <emphasis>serverMultiplexId</emphasis> parameter or because there
+ is no <classname>MultiplexClientInvoker</classname> with a
matching multiplexId), but it does have
<emphasis>multiplexConnectHost</emphasis> and
- <emphasis>multiplexConnectPort</emphasis> parameters, then it
- will create a <classname>VirtualServerSocket</classname>, create
- or reuse a suitable multiplex connection to the server, and
- start. Also, if it has a multiplexId, it will advertise itself
- for the benefit of a
- <classname>MultiplexClientInvoker</classname> that may come
- along later (see client rule 1).</para>
+ <emphasis>multiplexConnectPort</emphasis> parameters, then it will
+ create a <classname>VirtualServerSocket</classname>, create or
+ reuse a suitable multiplex connection to the server, and start.
+ Also, if it has a multiplexId, it will advertise itself for the
+ benefit of a <classname>MultiplexClientInvoker</classname> that
+ may come along later (see client rule 1).</para>
</listitem>
<listitem>
@@ -2009,10 +1968,10 @@
finds a <classname>MultiplexClientInvoker</classname> with a
matching multiplexId nor has
<emphasis>multiplexConnectHost</emphasis> and
- <emphasis>multiplexConnectPort</emphasis> parameters, then it
- will not start, but it will advertise itself so that it may be
- found later by a <classname>MultiplexClientInvoker</classname>
- (see client rule 1).</para>
+ <emphasis>multiplexConnectPort</emphasis> parameters, then it will
+ not start, but it will advertise itself so that it may be found
+ later by a <classname>MultiplexClientInvoker</classname> (see
+ client rule 1).</para>
</listitem>
<listitem>
@@ -2059,8 +2018,8 @@
<classname>InvokerLocator</classname>
multiplex://demo.jboss.com, the second one, lacking any
constraints on its binding address and port, is certainly not
- prevented from sharing a connection with the first. Rather,
- the function of the invoker group parameters is to
+ prevented from sharing a connection with the first. Rather, the
+ function of the invoker group parameters is to
<emphasis>force</emphasis>
<classname>MultiplexClientInvoker</classname>s and
<classname>MultiplexServerInvoker</classname>s to share a
@@ -2070,19 +2029,18 @@
<listitem>
<para>There are situations in which the method of passing
parameters by way of the configuration map is preferable to
- appending them to an <classname>InvokerLocator</classname>.
- One of the functions of an
- <classname>InvokerLocator</classname> is to identify a server,
- and modifying the content of its
+ appending them to an <classname>InvokerLocator</classname>. One
+ of the functions of an <classname>InvokerLocator</classname> is
+ to identify a server, and modifying the content of its
<classname>InvokerLocator</classname> may interfere with the
ability to locate the server. For example, one of the features
- of JBoss Remoting is the substitution of method calls for
- remote invocations when it discovers that a server runs in the
- same JVM as the client. However, appending multiplex
- parameters to the <classname>InvokerLocator</classname> by
- which the server is identified will prevent the Remoting
- runtime from recognizing the local presence of the server, and
- the optimization will not occur.</para>
+ of JBoss Remoting is the substitution of method calls for remote
+ invocations when it discovers that a server runs in the same JVM
+ as the client. However, appending multiplex parameters to the
+ <classname>InvokerLocator</classname> by which the server is
+ identified will prevent the Remoting runtime from recognizing
+ the local presence of the server, and the optimization will not
+ occur.</para>
</listitem>
<listitem>
@@ -2091,16 +2049,15 @@
<emphasis>clientMultiplexId</emphasis> and
<emphasis>serverMultiplexId</emphasis>. Note, however, that in
this case neither the <classname>Clients</classname> nor the
- <classname>Connector</classname> will be fully initialized
- until after both have been started. If the
+ <classname>Connector</classname> will be fully initialized until
+ after both have been started. If the
<classname>Clients</classname> and the
<classname>Connector</classname> are to be started
- independently, then the other parameters must be used.
- <emphasis role="bold">N.B.</emphasis> If a
- <classname>Client</classname> depends on
- <classname>Connector</classname> in the same invoker group to
- supply binding information, it is an error to call methods
- such as <methodname>Client.connect()</methodname> and
+ independently, then the other parameters must be used. <emphasis
+ role="bold">N.B.</emphasis> If a <classname>Client</classname>
+ depends on <classname>Connector</classname> in the same invoker
+ group to supply binding information, it is an error to call
+ methods such as <methodname>Client.connect()</methodname> and
<methodname>Client.invoke()</methodname> until the
<classname>Connector</classname> has been started.</para>
</listitem>
@@ -2119,24 +2076,24 @@
<para>A virtual socket group will shut down, releasing a real socket
and a number of threads, when (1) its last member has closed and (2)
- the socket group at the remote end of the multiplex connection
- agrees to the proposed shut down. The second condition prevents a
- situation in which a new virtual socket tries to join what it thinks
- is a viable socket group at the same time that the peer socket group
- is shutting down. So for a virtual socket group to shut down, all
- members at both ends of the connection must be closed.</para>
+ the socket group at the remote end of the multiplex connection agrees
+ to the proposed shut down. The second condition prevents a situation
+ in which a new virtual socket tries to join what it thinks is a viable
+ socket group at the same time that the peer socket group is shutting
+ down. So for a virtual socket group to shut down, all members at both
+ ends of the connection must be closed.</para>
- <para>The implication of this negotiated shutdown mechanism is that
- as long as the <classname>VirtualServerSocket</classname> used by a
+ <para>The implication of this negotiated shutdown mechanism is that as
+ long as the <classname>VirtualServerSocket</classname> used by a
virtual <classname>MultiplexServerInvoker</classname> remains open,
- resources at the client end of the connection cannot be freed, and
- for this reason it is important to understand how to close virtual
+ resources at the client end of the connection cannot be freed, and for
+ this reason it is important to understand how to close virtual
<classname>MultiplexServerInvoker</classname>s.</para>
<para>There are three ways in which a virtual
- <classname>MultiplexServerInvoker</classname> that belongs to a
- master <classname>MultiplexServerInvoker</classname>'s invoker farm
- can shut down. <itemizedlist>
+ <classname>MultiplexServerInvoker</classname> that belongs to a master
+ <classname>MultiplexServerInvoker</classname>'s invoker farm can shut
+ down. <itemizedlist>
<listitem>
<para>When a master
<classname>MultiplexServerInvoker</classname> is closed, it
@@ -2151,8 +2108,8 @@
<methodname>MultiplexServerInvoker.getServerInvokers()</methodname>
or
<methodname>MultiplexServerInvoker.getServerInvoker(InetSocketAddress)</methodname>
- on its master <classname>MultiplexServerInvoker</classname>
- and then closed directly.</para>
+ on its master <classname>MultiplexServerInvoker</classname> and
+ then closed directly.</para>
</listitem>
<listitem>
@@ -2166,22 +2123,21 @@
join.</para>
</listitem>
</itemizedlist> The third method insures that without any explicit
- intervention, closing all multiplex invokers on the client (by way
- of calling <methodname>Client.disconnect()</methodname> and
- <methodname>Connector.stop()</methodname>) is guaranteed to result
- in the eventual release of resources. The timeout period may be
- adjusted by setting the <emphasis>timeout</emphasis> parameter (see
- below). Alternatively, the second method, in conjunction with the
- use of
+ intervention, closing all multiplex invokers on the client (by way of
+ calling <methodname>Client.disconnect()</methodname> and
+ <methodname>Connector.stop()</methodname>) is guaranteed to result in
+ the eventual release of resources. The timeout period may be adjusted
+ by setting the <emphasis>timeout</emphasis> parameter (see below).
+ Alternatively, the second method, in conjunction with the use of
<methodname>MultiplexServerInvoker.isSafeToShutdown()</methodname>,
which returns <code>true</code> on
<classname>MultiplexServerInvoker</classname> <code>M</code> if and
- only if (1) <code>M</code> is not virtual, or (2) all of the
- multiplex invokers in the invoker group at the client end of
- <code>M</code>'s connection have shut down. For example, a thread
- could be dedicated to looking for useless
- <classname>MultiplexServerInvoker</classname>s and terminating them
- before their natural expiration through timing out.</para>
+ only if (1) <code>M</code> is not virtual, or (2) all of the multiplex
+ invokers in the invoker group at the client end of <code>M</code>'s
+ connection have shut down. For example, a thread could be dedicated to
+ looking for useless <classname>MultiplexServerInvoker</classname>s and
+ terminating them before their natural expiration through timing
+ out.</para>
</section>
<section>
@@ -2266,8 +2222,8 @@
<para>and then a <classname>MultiplexServerInvoker</classname>
<emphasis>S</emphasis> is created with a matching multiplexId,
- allowing both <emphasis>C</emphasis> and <emphasis>S</emphasis>
- to start:</para>
+ allowing both <emphasis>C</emphasis> and <emphasis>S</emphasis> to
+ start:</para>
<programlisting>
Connector connector = new Connector();
@@ -2287,8 +2243,8 @@
<listitem>
<para>A <classname>MultiplexClientInvoker</classname>
- <emphasis>C</emphasis> starts in an invoker group based on a
- real socket bound to an arbitrary local port:</para>
+ <emphasis>C</emphasis> starts in an invoker group based on a real
+ socket bound to an arbitrary local port:</para>
<programlisting>
String locatorURI = "multiplex://demo.jboss.com:8080";
@@ -2356,16 +2312,16 @@
<section>
<title>Configuration properties</title>
- <para>There are four categories of configuration properties
- supported by the multiplex invoker, the last three of which are
- specific to the multiplex invoker. Properties in categories 2 and 3
- may be configured by appending them to the server's locator URI.
- Properties in categories 2, 3, and 4 may be configured by putting
- their values in a configuration <classname>HashMap</classname> and
- passing the map to a <classname>MultiplexServerInvoker</classname>
- and/or <classname>MultiplexClientInvoker</classname> constructor,
- according to the category. Constants for the property names in
- categories 2, 3, and 4 are found in
+ <para>There are four categories of configuration properties supported
+ by the multiplex invoker, the last three of which are specific to the
+ multiplex invoker. Properties in categories 2 and 3 may be configured
+ by appending them to the server's locator URI. Properties in
+ categories 2, 3, and 4 may be configured by putting their values in a
+ configuration <classname>HashMap</classname> and passing the map to a
+ <classname>MultiplexServerInvoker</classname> and/or
+ <classname>MultiplexClientInvoker</classname> constructor, according
+ to the category. Constants for the property names in categories 2, 3,
+ and 4 are found in
<classname>org.jboss.remoting.transport.multiplex.Multiplex</classname>.
Note that some of them are also found in the older
<classname>org.jboss.remoting.transport.multiplex.MultiplexInvokerConstants</classname>,
@@ -2373,46 +2329,45 @@
<orderedlist numeration="arabic">
<listitem>
- <para>The following properties are managed by ancestor classes
- of <classname>MultiplexServerInvoker</classname>. See the discussion
+ <para>The following properties are managed by ancestor classes of
+ <classname>MultiplexServerInvoker</classname>. See the discussion
under <classname>SocketServerInvoker</classname> for more
information.</para>
- <para><emphasis role="bold">socketTimeout</emphasis> - The
- socket timeout value passed to the
+
+ <para><emphasis role="bold">socketTimeout</emphasis> - The socket
+ timeout value passed to the
<methodname>Socket.setSoTimeout()</methodname> method and the
<methodname>ServerSocket.setSoTimeout()</methodname> method. The
default is 60000 (or 1 minute).</para>
<para><emphasis role="bold">numAcceptThreads</emphasis> - The
- number of threads that exist for accepting client connections.
- The default is 1.</para>
+ number of threads that exist for accepting client connections. The
+ default is 1.</para>
</listitem>
<listitem>
<para>The following properties are intended to be passed to a
- virtual <classname>MultiplexServerInvoker</classname> to
- configure its multiplex connection. These properties are
- specific to the multiplex invoker.</para>
-
- <para><emphasis role="bold">multiplexConnectHost</emphasis> -
- the name or address of the host to which the multiplex
- connection should be made.</para>
-
- <para><emphasis role="bold">multiplexConnectPort</emphasis> -
- the port to which the multiplex connection should be
- made.</para>
+ virtual <classname>MultiplexServerInvoker</classname> to configure
+ its multiplex connection. These properties are specific to the
+ multiplex invoker.</para>
+
+ <para><emphasis role="bold">multiplexConnectHost</emphasis> - the
+ name or address of the host to which the multiplex connection
+ should be made.</para>
+
+ <para><emphasis role="bold">multiplexConnectPort</emphasis> - the
+ port to which the multiplex connection should be made.</para>
<para><emphasis role="bold">serverMultiplexId</emphasis> - a
string that associates a
<classname>MultiplexServerInvoker</classname> with a
- <classname>MultiplexClientInvoker</classname> with which it
- should share a multiplex connection.</para>
+ <classname>MultiplexClientInvoker</classname> with which it should
+ share a multiplex connection.</para>
- <para><emphasis role="bold">multiplex.maxAcceptErrors</emphasis>
- - Master and virtual
- <classname>MultiplexServerInvoker</classname>s keep a counter of
- errors experienced by their server socket, and they terminate
- when this maximum is exceeded. Note that
+ <para><emphasis role="bold">multiplex.maxAcceptErrors</emphasis> -
+ Master and virtual <classname>MultiplexServerInvoker</classname>s
+ keep a counter of errors experienced by their server socket, and
+ they terminate when this maximum is exceeded. Note that
<classname>SSLHandshakeException</classname>s are excluded from
the count, since they could indicate a client rather than server
error.</para>
@@ -2420,28 +2375,28 @@
<listitem>
<para>The following properties are intended to be passed to a
- virtual <classname>MultiplexClientInvoker</classname> to
- configure its multiplex connection. These properties are
- specific to the multiplex invoker.</para>
+ virtual <classname>MultiplexClientInvoker</classname> to configure
+ its multiplex connection. These properties are specific to the
+ multiplex invoker.</para>
<para><emphasis role="bold">multiplexBindHost</emphasis> - the
host name or address to which the local end of the multiplex
connection should be bound.</para>
<para><emphasis role="bold">multiplexBindPort</emphasis> - the
- port to which the local end of the multiplex connection should
- be bound</para>
+ port to which the local end of the multiplex connection should be
+ bound</para>
<para><emphasis role="bold">clientMultiplexId</emphasis> - a
string that associates a
<classname>MultiplexClientInvoker</classname> with a
- <classname>MultiplexServerInvoker</classname> with which it
- should share a multiplex connection.</para>
+ <classname>MultiplexServerInvoker</classname> with which it should
+ share a multiplex connection.</para>
</listitem>
<listitem>
- <para>There is also a set of properties which are specific to
- the Multiplex subsystem internal classes. See the Multiplex
+ <para>There is also a set of properties which are specific to the
+ Multiplex subsystem internal classes. See the Multiplex
documentation at</para>
<blockquote>
@@ -2463,22 +2418,21 @@
transport, except that it will create SSL socket factories and server
socket factories by default.</para>
- <para>The twist to be found with the multiplex transport is that
- virtual <classname>MultiplexServerInvoker</classname>s use a
+ <para>The twist to be found with the multiplex transport is that virtual
+ <classname>MultiplexServerInvoker</classname>s use a
<classname>VirtualServerSocket</classname>, which is based on a client
- rather than a server socket, and consequently they act like a client
- in some ways. In particular, a virtual
+ rather than a server socket, and consequently they act like a client in
+ some ways. In particular, a virtual
<classname>MultiplexServerInvoker</classname> will, in some cases,
attempt to connect to a remote master
- <classname>MultiplexServerInvoker</classname>, for which it will need
- an actual client socket. All of the rules for configuring socket
- factories apply to the <classname>MultiplexServerInvoker</classname>,
- which calls the same method that client invokers use to get a socket
- factory. Moreover, if necessary, it will look for a
+ <classname>MultiplexServerInvoker</classname>, for which it will need an
+ actual client socket. All of the rules for configuring socket factories
+ apply to the <classname>MultiplexServerInvoker</classname>, 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. See section
- <xref linkend="section-socket-factories"/> for more information.
- </para>
+ when configuring a socket factory. See section <xref
+ linkend="section-socket-factories" /> for more information.</para>
</section>
</section>
@@ -2494,44 +2448,43 @@
<para>The easiest way to configure marshalling is to specify nothing at
all. This will prompt the remoting invokers to use their default
marshaller/unmarshallers. For example, the socket invoker will use the
- SerializableMarshaller/SerializableUnMarshaller and the http invoker
- will use the HTTPMarshaller/HTTPUnMarshaller, on both the client and
- server side.</para>
+ SerializableMarshaller/SerializableUnMarshaller and the http invoker will
+ use the HTTPMarshaller/HTTPUnMarshaller, on both the client and server
+ side.</para>
<para>The next easiest way is to specify the data type of the
marshaller/unmarshaller as a parameter to the locator url. This can be
- done by simply adding the key word 'datatype' to the url, such
- as:</para>
+ done by simply adding the key word 'datatype' to the url, such as:</para>
<programlisting>socket://myhost:5400/?datatype=serializable</programlisting>
<para>This can be done for types that are statically bound within the
- <code>MarshalFactory</code>, serializable and http, without requiring
- any extra coding, since they will be available to any user of remoting.
+ <code>MarshalFactory</code>, serializable and http, without requiring any
+ extra coding, since they will be available to any user of remoting.
However, is more likely this will be used for custom marshallers (since
could just use the default data type from the invokers if using the
statically defined types). If using custom marshaller/unmarshaller, will
need to make sure both are added programmatically to the
- <code>MarshalFactory</code> during runtime (on both the client and
- server side). This can be done by the following method call within the
+ <code>MarshalFactory</code> during runtime (on both the client and server
+ side). This can be done by the following method call within the
MarshalFactory:</para>
<programlisting>public static void addMarshaller(String dataType, Marshaller marshaller, UnMarshaller unMarshaller)
</programlisting>
<para>The dataType passed can be any String value desired. For example,
- could add custom InvocationMarshaller and InvocationUnMarshaller with
- the data type of 'invocation'. An example using this data type would
- then be:</para>
+ could add custom InvocationMarshaller and InvocationUnMarshaller with the
+ data type of 'invocation'. An example using this data type would then
+ be:</para>
<programlisting>socket://myhost:5400/?datatype=invocation</programlisting>
<para>One of the problems with using a data type for a custom
- Marshaller/UnMarshaller is having to explicitly code the addition of
- these within the MarshalFactory on both the client and the server. So
- another approach that is a little more flexible is to specify the fully
- qualified class name for both the Marshaller and UnMarshaller on the
- locator url. For example:</para>
+ Marshaller/UnMarshaller is having to explicitly code the addition of these
+ within the MarshalFactory on both the client and the server. So another
+ approach that is a little more flexible is to specify the fully qualified
+ class name for both the Marshaller and UnMarshaller on the locator url.
+ For example:</para>
<programlisting>socket://myhost:5400/?datatype=invocation&
marshaller=org.jboss.invocation.unified.marshall.InvocationMarshaller&
@@ -2598,23 +2551,23 @@
</programlisting>
<para>When this parameter is supplied, the Connector will recognize this
- at startup and create a marshal loader connector automatically, which
- will run on the port specified. The locator url will be exactly the same
- as the original invoker locator, except will be using the socket
- transport protocol and will have all marshalling parameters removed
- (except the dataType). When the remoting client can not load the
+ at startup and create a marshal loader connector automatically, which will
+ run on the port specified. The locator url will be exactly the same as the
+ original invoker locator, except will be using the socket transport
+ protocol and will have all marshalling parameters removed (except the
+ dataType). When the remoting client can not load the
marshaller/unmarshaller for the specified data type, it will try to load
- them from the marshal loader service running on the loader port,
- including any classes they depend on. This will happen automatically and
- no coding is required (only the ability for the client to access the
- server on the specified loader port, so must provide access if running
- through firewall).</para>
+ them from the marshal loader service running on the loader port, including
+ any classes they depend on. This will happen automatically and no coding
+ is required (only the ability for the client to access the server on the
+ specified loader port, so must provide access if running through
+ firewall).</para>
<bridgehead>Compression marshalling</bridgehead>
<para>A compression marshaller/unmarshaller is available as well which
- uses gzip to compress and uncompress large payloads for wire transfer.
- The implementation classes are
+ uses gzip to compress and uncompress large payloads for wire transfer. The
+ implementation classes are
<classname>org.jboss.remoting.marshal.compress.CompressingMarshaller</classname>
and
<classname>org.jboss.remoting.marshal.compress.CompressingUnMarshaller</classname>.
@@ -2632,51 +2585,50 @@
<section>
<title>Callback overview</title>
- <para>Although this section covers callback configuration, will need
- to first cover a little general information about callbacks within
- remoting. There are two models for callbacks, push and pull. In the
- push model, the client will register a callback server via an
- InvokerLocator with the target server. When the target server has a
- callback to deliver, it will call on the callback server directly and
- send the callback message.</para>
+ <para>Although this section covers callback configuration, will need to
+ first cover a little general information about callbacks within
+ remoting. There are two models for callbacks, push and pull. In the push
+ model, the client will register a callback server via an InvokerLocator
+ with the target server. When the target server has a callback to
+ deliver, it will call on the callback server directly and send the
+ callback message.</para>
- <para>The other model, pull callbacks, allows the client to call on
- the target server to collect the callback messages waiting for it. The
+ <para>The other model, pull callbacks, allows the client to call on the
+ target server to collect the callback messages waiting for it. The
target server then has to manage these callback messages on the server
- until the client calls to collect them. Since the server has no
- control of when the client will call to get the callbacks, it has to
- be aware of memory constraints as it manages a growing number of
- callbacks. The way the callback server does this is through use of a
- persistence policy. This policy indicates at what point the server has
- too little free memory available and therefore the callback message
- should be put into a persistent store. This policy can be configured
- via the <code>memPercentCeiling</code> attribute (see more on
- configuring this below).</para>
+ until the client calls to collect them. Since the server has no control
+ of when the client will call to get the callbacks, it has to be aware of
+ memory constraints as it manages a growing number of callbacks. The way
+ the callback server does this is through use of a persistence policy.
+ This policy indicates at what point the server has too little free
+ memory available and therefore the callback message should be put into a
+ persistent store. This policy can be configured via the
+ <code>memPercentCeiling</code> attribute (see more on configuring this
+ below).</para>
<para>By default, the persistent store used by the invokers is the
- <code>org.jboss.remoting.NullCallbackStore</code>. The
- NullCallbackStore will simply throw away the callback to help avoid
- running out of memory. When the persistence policy is triggered and
- the NullCallbackStore is called upon to store the callback, the
- invocation handler making the call will be thrown an IOException with
- the message:</para>
+ <code>org.jboss.remoting.NullCallbackStore</code>. The NullCallbackStore
+ will simply throw away the callback to help avoid running out of memory.
+ When the persistence policy is triggered and the NullCallbackStore is
+ called upon to store the callback, the invocation handler making the
+ call will be thrown an IOException with the message:</para>
- <para><literal>Callback has been lost because not enough free memory
- to hold object.</literal></para>
+ <para><literal>Callback has been lost because not enough free memory to
+ hold object.</literal></para>
<para>and there will be an error in the log stating which object was
lost. In this same scenario, the client will get an instance of the
- <code>org.jboss.remoting.NullCallbackStore.FailedCallback</code>
- class when they call to get their
- callbacks. This class will throw a RuntimeException with the following
- message when <code>getCallbackObject()</code> is called:</para>
+ <code>org.jboss.remoting.NullCallbackStore.FailedCallback</code> class
+ when they call to get their callbacks. This class will throw a
+ RuntimeException with the following message when
+ <code>getCallbackObject()</code> is called:</para>
<para><literal>This is an invalid callback. The server ran out of
memory, so callbacks were lost.</literal></para>
<para>Also, the payload of the callback will be the same string. The
- client will also get any valid callbacks that were kept in memory
- before the persistence policy was triggered.</para>
+ client will also get any valid callbacks that were kept in memory before
+ the persistence policy was triggered.</para>
<para>An example case when using the NullCallbackStore might be when
callback objects A, B, and C are stored in memory because there is
@@ -2687,39 +2639,38 @@
there is still too little free memory, so that is thrown away by the
NullCallbackStore.</para>
- <para>Then the client calls to get its callbacks. It will receive a
- List containing callbacks A, B, C and the FailedCallback. When the
- client asks the FailedCallback for its callback payload, it will throw
- the aforementioned exception.</para>
-
- <para>Besides the default NullCallbackStore, there is a truly
- persistent CallbackStore, which will persist callback messages to disk
- so they will not be lost. The description of the CallbackStore is as
- follows:</para>
+ <para>Then the client calls to get its callbacks. It will receive a List
+ containing callbacks A, B, C and the FailedCallback. When the client
+ asks the FailedCallback for its callback payload, it will throw the
+ aforementioned exception.</para>
+
+ <para>Besides the default NullCallbackStore, there is a truly persistent
+ CallbackStore, which will persist callback messages to disk so they will
+ not be lost. The description of the CallbackStore is as follows:</para>
<para><literal>Acts as a persistent list which writes Serializable
- objects to disk and will retrieve them in same order in which they
- were added (FIFO). Each file will be named according to the current
- time (using System.currentTimeMillis() with the file suffix specified
- (see below). When the object is read and returned by calling the
- getNext() method, the file on disk for that object will be deleted. If
- for some reason the store VM crashes, the objects will still be
- available upon next startup. The attributes to make sure to configure
+ objects to disk and will retrieve them in same order in which they were
+ added (FIFO). Each file will be named according to the current time
+ (using System.currentTimeMillis() with the file suffix specified (see
+ below). When the object is read and returned by calling the getNext()
+ method, the file on disk for that object will be deleted. If for some
+ reason the store VM crashes, the objects will still be available upon
+ next startup. The attributes to make sure to configure
are:</literal></para>
- <para><literal>file path - this determines which directory to write
- the objects. The default value is the property value of
- 'jboss.server.data.dir' and if this is not set, then will be 'data'.
- For example, might be /jboss/server/default/data.</literal></para>
+ <para><literal>file path - this determines which directory to write the
+ objects. The default value is the property value of
+ 'jboss.server.data.dir' and if this is not set, then will be 'data'. For
+ example, might be /jboss/server/default/data.</literal></para>
- <para><literal>file suffix - the file suffix to use for the file
- written for each object stored.</literal></para>
+ <para><literal>file suffix - the file suffix to use for the file written
+ for each object stored.</literal></para>
- <para><literal>This is also a service mbean, so can be run as a
- service within JBoss AS or stand alone.</literal></para>
+ <para><literal>This is also a service mbean, so can be run as a service
+ within JBoss AS or stand alone.</literal></para>
- <para>Custom callback stores can also be implemented and defined
- within configuration. The only requirement is that it implements the
+ <para>Custom callback stores can also be implemented and defined within
+ configuration. The only requirement is that it implements the
org.jboss.remoting.SerializableStore interface and has a void
constructor (only in the case of using a fully qualified classname in
configuration).</para>
@@ -2732,47 +2683,47 @@
<title>Callback Configuration</title>
<para>All callback configuration will need to be defined within the
- invoker configuration, since the invoker is the parent that creates
- the callback servers as needed (when client registers for pull
- callbacks). Example service xml are included below.</para>
+ invoker configuration, since the invoker is the parent that creates the
+ callback servers as needed (when client registers for pull callbacks).
+ Example service xml are included below.</para>
<para><emphasis role="bold">callbackMemCeiling</emphasis> - the
- percentage of free memory available before callbacks will be
- persisted. If the memory heap allocated has reached its maximum value
- and the percent of free memory available is less than the
- callbackMemCeiling, this will trigger persisting of the callback
- message. The default value is 20.</para>
-
- <para>Note: The calculations for this is not always accurate. The
- reason is that total memory used is usually less than the max allowed.
- Thus, the amount of free memory is relative to the total amount
- allocated at that point in time. It is not until the total amount of
- memory allocated is equal to the max it will be allowed to allocate.
- At this point, the amount of free memory becomes relevant. Therefore,
- if the memory percentage ceiling is high, it might not trigger until
- after free memory percentage is well below the ceiling.</para>
+ percentage of free memory available before callbacks will be persisted.
+ If the memory heap allocated has reached its maximum value and the
+ percent of free memory available is less than the callbackMemCeiling,
+ this will trigger persisting of the callback message. The default value
+ is 20.</para>
+
+ <para>Note: The calculations for this is not always accurate. The reason
+ is that total memory used is usually less than the max allowed. Thus,
+ the amount of free memory is relative to the total amount allocated at
+ that point in time. It is not until the total amount of memory allocated
+ is equal to the max it will be allowed to allocate. At this point, the
+ amount of free memory becomes relevant. Therefore, if the memory
+ percentage ceiling is high, it might not trigger until after free memory
+ percentage is well below the ceiling.</para>
<para><emphasis role="bold">callbackStore</emphasis> - specifies the
callback store to be used. The value can be either an MBean ObjectName
- or a fully qualified class name. If using class name, the callback
- store implementation must have a void constructor. The default is to
- use the NullCallbackStore.</para>
+ or a fully qualified class name. If using class name, the callback store
+ implementation must have a void constructor. The default is to use the
+ NullCallbackStore.</para>
<bridgehead>CallbackStore configuration</bridgehead>
- <para>The CallbackStore can be configured via the invoker
- configuration as well.</para>
+ <para>The CallbackStore can be configured via the invoker configuration
+ as well.</para>
<para><emphasis role="bold">StoreFilePath</emphasis> - indicates to
- which directory to write the callback objects. The default value is
- the property value of 'jboss.server.data.dir' and if this is not set,
- then will be 'data'. Will then append 'remoting' and the callback
- client's session id. An example would be
+ which directory to write the callback objects. The default value is the
+ property value of 'jboss.server.data.dir' and if this is not set, then
+ will be 'data'. Will then append 'remoting' and the callback client's
+ session id. An example would be
'data\remoting\5c4o05l-9jijyx-e5b6xyph-1-e5b6xyph-2'.</para>
<para><emphasis role="bold">StoreFileSuffix</emphasis> - indicates the
- file suffix to use for the callback objects written to disk. The
- default value is 'ser'.</para>
+ file suffix to use for the callback objects written to disk. The default
+ value is 'ser'.</para>
<bridgehead>Sample service configuration</bridgehead>
@@ -2801,8 +2752,8 @@
</mbean>
</programlisting>
- <para>Socket transport with callback store specified by MBean
- ObjectName and declaration of CallbackStore as service:</para>
+ <para>Socket transport with callback store specified by MBean ObjectName
+ and declaration of CallbackStore as service:</para>
<programlisting>
<mbean code="org.jboss.remoting.CallbackStore"
@@ -2868,37 +2819,35 @@
<title>Callback Exception Handling</title>
<para>Since performing callbacks can sometimes fail, due to network
- errors or errors produced by the client callback handler, there needs
- to be a mechanism for managing exceptions when delivering callbacks.
- This is handled via use of the
- <code>org.jboss.remoting.callback.CallbackErrorHandler</code>
- interface. Implementations of this interface can be registered with
- the Connector to control the behavior when callback exceptions
- occur.</para>
+ errors or errors produced by the client callback handler, there needs to
+ be a mechanism for managing exceptions when delivering callbacks. This
+ is handled via use of the
+ <code>org.jboss.remoting.callback.CallbackErrorHandler</code> interface.
+ Implementations of this interface can be registered with the Connector
+ to control the behavior when callback exceptions occur.</para>
<para>The implementation of the CallbackErrorHandler interface can be
- specified by setting the 'callbackErrorHandler' attribute to either
- the ObjectName of an MBean instance of the CallbackErrorHandler which
- is already running and registered with the MBeanServer, or can just
- specify the fully qualified class name of the CallbackErrorHandler
+ specified by setting the 'callbackErrorHandler' attribute to either the
+ ObjectName of an MBean instance of the CallbackErrorHandler which is
+ already running and registered with the MBeanServer, or can just specify
+ the fully qualified class name of the CallbackErrorHandler
implementation (which will be constructed on the fly and must have a
- void parameter constructor). The full server invoker configuration
- will be passed along to the CallbackErrorHandler, so if want to add
- extra configuration information in the invoker's configuration for the
+ void parameter constructor). The full server invoker configuration will
+ be passed along to the CallbackErrorHandler, so if want to add extra
+ configuration information in the invoker's configuration for the
callback error handler, it will be available. If no callback error
handler is specified via configuration,
<code>org.jboss.remoting.callback.DefaultCallbackErrorHandler</code>
will be used by default. This implementation will allow up to 5
exceptions to occur when trying to deliver a callback message from the
server to the registered callback listener client (regardless of what
- the cause of the exception is, so could be because could not connect
- or could be because the client actually threw a valid exception).
- After the DefaultCallbackErrorHandler receives its fifth exception, it
- will remove the callback listener from the server invoker handler and
- shut down the callback listener proxy on the server side. The number
- of exceptions the DefaultCallbackErrorHandler will allow before
- removing the listener can by configured by the 'callbackErrorsAllowed'
- attribute.</para>
+ the cause of the exception is, so could be because could not connect or
+ could be because the client actually threw a valid exception). After the
+ DefaultCallbackErrorHandler receives its fifth exception, it will remove
+ the callback listener from the server invoker handler and shut down the
+ callback listener proxy on the server side. The number of exceptions the
+ DefaultCallbackErrorHandler will allow before removing the listener can
+ by configured by the 'callbackErrorsAllowed' attribute.</para>
</section>
</section>
@@ -2927,37 +2876,33 @@
<para>All current transports depend on sockets and server sockets, and the
ability to specify their implementation classes provides considerable
- power in configuring Remoting. Notably, SSL sockets
- and server sockets are the basis of secure communications in Remoting.
- This section covers the configuration of socket factories and server
- socket factories on both the server side and the client side, and then
- focuses on SSL configuration.
- </para>
+ power in configuring Remoting. Notably, SSL sockets and server sockets are
+ the basis of secure communications in Remoting. This section covers the
+ configuration of socket factories and server socket factories on both the
+ server side and the client side, and then focuses on SSL
+ configuration.</para>
<section>
<title>Server side programmatic configuration</title>
- <para>
- All server invokers use server sockets, and it makes sense,
- therefore, to be able to configure server invokers with
- server socket factories. It is also true, though less obvious.
- that server invokers create sockets (other than by way of
- server sockets). When a server invoker makes a push
- callback to a client, it creates a client invoker, which creates a
- socket. Moreover, some server invokers, e.g., the RMI server invoker,
- have their own idiosyncratic uses for socket factories. Remoting offers a
- number of ways of configuring socket factories and server socket
- factories, and these apply to all transports (except for the servlet
- invokers).</para>
+
+ <para>All server invokers use server sockets, and it makes sense,
+ therefore, to be able to configure server invokers with server socket
+ factories. It is also true, though less obvious. that server invokers
+ create sockets (other than by way of server sockets). When a server
+ invoker makes a push callback to a client, it creates a client invoker,
+ which creates a socket. Moreover, some server invokers, e.g., the RMI
+ server invoker, have their own idiosyncratic uses for socket factories.
+ Remoting offers a number of ways of configuring socket factories and
+ server socket factories, and these apply to all transports (except for
+ the servlet invokers).</para>
<section id="section-ssf-serverside" xreflabel="Server socket factories">
- <title>
- Server socket factories.
- </title>
- <para>For <classname>ServerSocketFactory</classname>s, there are
- ten options for programmatic configuration:</para>
+ <title>Server socket factories.</title>
- <orderedlist>
+ <para>For <classname>ServerSocketFactory</classname>s, there are ten
+ options for programmatic configuration:</para>
+ <orderedlist>
<listitem>
<para>Get the <classname>ServerInvoker</classname> by calling
<methodname>Connector.getServerInvoker()</methodname> and call
@@ -2965,29 +2910,25 @@
</listitem>
<listitem>
- <para>Call <methodname>Connector.setServerSocketFactory()</methodname>.
- </para>
+ <para>Call
+ <methodname>Connector.setServerSocketFactory()</methodname>.</para>
</listitem>
<listitem>
- <para>
- Put a constructed <classname>ServerSocketFactory</classname> in a
- configuration map, using key
- <constant>Remoting.CUSTOM_SERVER_SOCKET_FACTORY</constant>,
- and pass the map to one of the <classname>Connector</classname>
- constructors.
- </para>
+ <para>Put a constructed <classname>ServerSocketFactory</classname>
+ in a configuration map, using key
+ <constant>Remoting.CUSTOM_SERVER_SOCKET_FACTORY</constant>, and
+ pass the map to one of the <classname>Connector</classname>
+ constructors.</para>
</listitem>
<listitem>
- <para>
- Create an xml document with root element <code><config></code>,
- setting the <code><serverSocketFactory></code> attribute to
- the name of a <classname>ServerSocketFactoryMBean</classname> and pass
- the document to <methodname>Connector.setConfiguration()</methodname>. For
- example:
-
- <programlisting>
+ <para>Create an xml document with root element
+ <code><config></code>, setting the
+ <code><serverSocketFactory></code> attribute to the name of
+ a <classname>ServerSocketFactoryMBean</classname> and pass the
+ document to <methodname>Connector.setConfiguration()</methodname>.
+ For example: <programlisting>
StringBuffer buf = new StringBuffer();
buf.append("<?xml version=\"1.0\"?>\n");
buf.append("<config>");
@@ -3000,182 +2941,160 @@
ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
connector.setConfiguration(xml.getDocumentElement());
- </programlisting>
- </para>
+ </programlisting></para>
</listitem>
<listitem>
- <para>
- Create an xml document with root element <code><config></code>,
- setting the <code><serverSocketFactory></code> attribute to
- the class name of a <classname>ServerSocketFactory</classname> and pass
- the document to <methodname>Connector.setConfiguration()</methodname>.
- The <code><serverSocketFactory></code> class must have a default
- constructor, which will be used to create a
- <classname>ServerSocketFactory</classname>.
- </para>
+ <para>Create an xml document with root element
+ <code><config></code>, setting the
+ <code><serverSocketFactory></code> attribute to the class
+ name of a <classname>ServerSocketFactory</classname> and pass the
+ document to <methodname>Connector.setConfiguration()</methodname>.
+ The <code><serverSocketFactory></code> class must have a
+ default constructor, which will be used to create a
+ <classname>ServerSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Put the <classname>ObjectName</classname> of a
- <classname>ServerSocketFactoryMBean</classname> in a configuration map,
- using key <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
- and pass the map to one of the <classname>Connector</classname>
- constructors.
- </para>
+ <para>Put the <classname>ObjectName</classname> of a
+ <classname>ServerSocketFactoryMBean</classname> in a configuration
+ map, using key
+ <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>, and pass
+ the map to one of the <classname>Connector</classname>
+ constructors.</para>
</listitem>
<listitem>
- <para>
- Put the class name of a <classname>ServerSocketFactory</classname>
- in a configuration map, using key
- <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
- and pass the map to one of the <classname>Connector</classname> constructors.
- The <code><serverSocketFactory></code> class must have a
- default constructor, which will be used to create a
- <classname>ServerSocketFactory</classname>.
- </para>
+ <para>Put the class name of a
+ <classname>ServerSocketFactory</classname> in a configuration map,
+ using key
+ <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>, and pass
+ the map to one of the <classname>Connector</classname>
+ constructors. The <code><serverSocketFactory></code> class
+ must have a default constructor, which will be used to create a
+ <classname>ServerSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Put a set of SSL parameters, using the keys in
- <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>, in a
- configuration map and pass the map to one of the
- <classname>Connector</classname> constructors. These will be used by
- <classname>SSLSocketBuilder</classname> (see below) to create a
- <classname>CustomSSLServerSocketFactory</classname>.
- </para>
+ <para>Put a set of SSL parameters, using the keys in
+ <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
+ in a configuration map and pass the map to one of the
+ <classname>Connector</classname> constructors. These will be used
+ by <classname>SSLSocketBuilder</classname> (see below) to create a
+ <classname>CustomSSLServerSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Configure an appropriate set of SSL system properties
- and use one of the SSL transports (https, sslmultiplex,
- sslrmi, or sslsocket). The properties will be used to
- create some kind of <classname>SSLServerSocketFactory</classname>,
- as determined by the transport.
- </para>
+ <para>Configure an appropriate set of SSL system properties and
+ use one of the SSL transports (https, sslmultiplex, sslrmi, or
+ sslsocket). The properties will be used to create some kind of
+ <classname>SSLServerSocketFactory</classname>, as determined by
+ the transport.</para>
</listitem>
<listitem>
- <para>
- Use one of the non-SSL transports and do nothing. A default
- <classname>ServerSocketFactory</classname> will be constructed.
- </para>
+ <para>Use one of the non-SSL transports and do nothing. A default
+ <classname>ServerSocketFactory</classname> will be
+ constructed.</para>
</listitem>
</orderedlist>
- <para>
- These options are essentially in descending order of precedence.
- If options 3 and 6, for example, are both
- used, the factory passed in option 3 will prevail.
- Options 4 and 5 are mutually exclusive, as are options 6 and 7.
- Options 1, 2, 3, 5, and 7 are illustrated in
- <classname>FactoryConfigSample</classname>
- and options 4, 6, 8, and 9 are illustrated in
- <classname>FactoryConfigSSLSample</classname>,
- both of which are in package
- <classname>org.jboss.remoting.samples.config.factories</classname>.
- </para>
+ <para>These options are essentially in descending order of precedence.
+ If options 3 and 6, for example, are both used, the factory passed in
+ option 3 will prevail. Options 4 and 5 are mutually exclusive, as are
+ options 6 and 7. Options 1, 2, 3, 5, and 7 are illustrated in
+ <classname>FactoryConfigSample</classname> and options 4, 6, 8, and 9
+ are illustrated in <classname>FactoryConfigSSLSample</classname>, both
+ of which are in package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.</para>
- <para>
- <emphasis role="bold">Timing considerations.</emphasis> The
+ <para><emphasis role="bold">Timing considerations.</emphasis> The
<classname>ServerInvoker</classname>, for any transport, is created
- during the call to <methodname>Connector.create()</methodname>, before which
- option 1 is unavailable. Option 2, on the other hand,
- is only available before the call to
- <methodname>Connector.create()</methodname>.
- Once the <classname>ServerInvoker</classname> has been created, it
- selects a <classname>ServerSocketFactory</classname>, according to
- the rules enumerated above, during the <methodname>create()</methodname>
- phase. For all current transports, the actual
+ during the call to <methodname>Connector.create()</methodname>, before
+ which option 1 is unavailable. Option 2, on the other hand, is only
+ available before the call to
+ <methodname>Connector.create()</methodname>. Once the
+ <classname>ServerInvoker</classname> has been created, it selects a
+ <classname>ServerSocketFactory</classname>, according to the rules
+ enumerated above, during the <methodname>create()</methodname> phase.
+ For all current transports, the actual
<classname>ServerSocket</classname> is created during the call to
<methodname>Connector.start()</methodname>, so that a call to
<methodname>ServerInvoker.setServerSocketFactory()</methodname>
- (option 1) can override the selected <classname>ServerSocketFactory</classname>
- until <methodname>Connector.start()</methodname> is called.
- </para>
+ (option 1) can override the selected
+ <classname>ServerSocketFactory</classname> until
+ <methodname>Connector.start()</methodname> is called.</para>
</section>
<section>
<title>Socket factories</title>
- <para>
- For <classname>SocketFactory</classname>s, there are also ten options
- for programmatic configuration, and they are essentially the same as
- the previous ten. Note, however, that options 5 and 6 are reversed.
- This is because an <classname>ServerSocketFactoryMBean</classname>,
- if it exists, is given precedence over class names:</para>
+
+ <para>For <classname>SocketFactory</classname>s, there are also ten
+ options for programmatic configuration, and they are essentially the
+ same as the previous ten. Note, however, that options 5 and 6 are
+ reversed. This is because an
+ <classname>ServerSocketFactoryMBean</classname>, if it exists, is
+ given precedence over class names:</para>
<orderedlist>
<listitem>
- <para>
- Call <methodname>Connector.setSocketFactory()</methodname>.
- </para>
+ <para>Call
+ <methodname>Connector.setSocketFactory()</methodname>.</para>
</listitem>
<listitem>
- <para>
- Get the <classname>ServerInvoker</classname> by calling
+ <para>Get the <classname>ServerInvoker</classname> by calling
<methodname>Connector.getServerInvoker()</methodname> and call
- <methodname>ServerInvoker.setSocketFactory()</methodname>.
- </para>
+ <methodname>ServerInvoker.setSocketFactory()</methodname>.</para>
</listitem>
<listitem>
- <para>
- Put a constructed <classname>SocketFactory</classname> in a
+ <para>Put a constructed <classname>SocketFactory</classname> in a
configuration map, using key
- <constant>Remoting.CUSTOM_SOCKET_FACTORY</constant>, and pass
- the map to one of the <classname>Connector</classname> constructors.
-
- </para>
+ <constant>Remoting.CUSTOM_SOCKET_FACTORY</constant>, and pass the
+ map to one of the <classname>Connector</classname>
+ constructors.</para>
</listitem>
<listitem>
- <para>
- Create an xml document with root element <code><config></code>,
- setting the <code><serverSocketFactory></code> attribute to
- the name of a <classname>ServerSocketFactoryMBean</classname> and pass
- the document to <methodname>Connector.setConfiguration()</methodname>.
+ <para>Create an xml document with root element
+ <code><config></code>, setting the
+ <code><serverSocketFactory></code> attribute to the name of
+ a <classname>ServerSocketFactoryMBean</classname> and pass the
+ document to <methodname>Connector.setConfiguration()</methodname>.
If the MBean has type
<classname>SSLServerSocketFactoryServiceMBean</classname>, its
configuration information will be gathered and used to construct a
- <classname>CustomSSLSocketFactory</classname>.
- <emphasis role="bold">Note.</emphasis> This method is guaranteed to
- work only for callback client invokers. For other, transport
- specific, socket factory uses, the transport may or may not
- use this information.
- </para>
+ <classname>CustomSSLSocketFactory</classname>. <emphasis
+ role="bold">Note.</emphasis> This method is guaranteed to work
+ only for callback client invokers. For other, transport specific,
+ socket factory uses, the transport may or may not use this
+ information.</para>
</listitem>
<listitem>
- <para>
- Put the <classname>ObjectName</classname> of a
+ <para>Put the <classname>ObjectName</classname> of a
<classname>ServerSocketFactoryMBean</classname> in a configuration
- map, using key <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
- and pass the map to one of the <classname>Connector</classname>
+ map, using key
+ <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>, and pass
+ the map to one of the <classname>Connector</classname>
constructors. If the MBean has type
<classname>SSLServerSocketFactoryServiceMBean</classname>, its
configuration information will be gathered and used to construct a
- <classname>CustomSSLSocketFactory</classname>.
- <emphasis role="bold">Note.</emphasis> This method is guaranteed to
- work only for callback client invokers. For other, transport
- specific, socket factory uses, the transport may or may not
- use this information.
- </para>
+ <classname>CustomSSLSocketFactory</classname>. <emphasis
+ role="bold">Note.</emphasis> This method is guaranteed to work
+ only for callback client invokers. For other, transport specific,
+ socket factory uses, the transport may or may not use this
+ information.</para>
</listitem>
<listitem>
- <para>
- Create an xml document with root element <code><config></code>,
- setting the <code><socketFactory></code> attribute to
- the class name of a <classname>SocketFactory</classname> and pass
- the document to <methodname>Connector.setConfiguration()</methodname>.
- For example:
-
- <programlisting>
+ <para>Create an xml document with root element
+ <code><config></code>, setting the
+ <code><socketFactory></code> attribute to the class name of
+ a <classname>SocketFactory</classname> and pass the document to
+ <methodname>Connector.setConfiguration()</methodname>. For
+ example: <programlisting>
StringBuffer buf = new StringBuffer();
buf.append("<?xml version=\"1.0\"?>\n");
buf.append("<config>");
@@ -3188,104 +3107,88 @@
ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
connector.setConfiguration(xml.getDocumentElement());
- </programlisting>
-
- The <classname>SocketFactory</classname> class must have a
- default constructor, which will be used to create a
- <classname>SocketFactory</classname>.
- </para>
+ </programlisting> The
+ <classname>SocketFactory</classname> class must have a default
+ constructor, which will be used to create a
+ <classname>SocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Put the class name of a <classname>SocketFactory</classname>
+ <para>Put the class name of a <classname>SocketFactory</classname>
in a configuration map, using key
- <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the map
- to one of the <classname>Connector</classname> constructors. The
- <classname>SocketFactory</classname> class
- must have a default constructor.
- </para>
+ <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the
+ map to one of the <classname>Connector</classname> constructors.
+ The <classname>SocketFactory</classname> class must have a default
+ constructor.</para>
</listitem>
<listitem>
- <para>
- Put a set of SSL parameters, using the keys in
+ <para>Put a set of SSL parameters, using the keys in
<classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
in a configuration map and pass the map to one of the
- <classname>Connector</classname> constructors. These will be used by
- <classname>SSLSocketBuilder</classname> (see below) to create a
- <classname>CustomSSLSocketFactory</classname>.
-
- </para>
+ <classname>Connector</classname> constructors. These will be used
+ by <classname>SSLSocketBuilder</classname> (see below) to create a
+ <classname>CustomSSLSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Configure an appropriate set of SSL system properties and use one of
- the SSL transports (https, sslmultiplex, sslrmi, or sslsocket). The
- properties will be used to create some kind of
+ <para>Configure an appropriate set of SSL system properties and
+ use one of the SSL transports (https, sslmultiplex, sslrmi, or
+ sslsocket). The properties will be used to create some kind of
<classname>SSLSocketFactory</classname>, as determined by the
- transport.
- </para>
+ transport.</para>
</listitem>
<listitem>
- <para>
- Use one of the non-SSL transports and do nothing. Ordinary
- <classname>Socket</classname>s will be used.
- </para>
+ <para>Use one of the non-SSL transports and do nothing. Ordinary
+ <classname>Socket</classname>s will be used.</para>
</listitem>
</orderedlist>
<para>Again, these are essentially in descending order of precedence.
Options 1, 2, 3, 6, and 7 are illustrated in
- <classname>FactoryConfigSample</classname>
- and options 4, 5, 8, and 9 are illustrated in
- <classname>FactoryConfigSSLSample</classname>,
- both of which are in package
- <classname>org.jboss.remoting.samples.config.factories</classname>.
- </para>
-
- <para>
- <emphasis role="bold">Timing considerations.</emphasis> A new
- <classname>Client</classname>, with a client invoker, is created
- on the server side whenever a callback listener is registered by a
- call to <methodname>Client.addListener()</methodname>. If a
- <classname>SocketFactory</classname> is supplied by any of options 1 to 5,
- it will be passed to the <classname>Client</classname>. Otherwise, any
- information from options 6 to 9 will be passed to the client invoker,
- which will create a <classname>SocketFactory</classname> according
- to the rules given below in the section on client side socket factory
- configuration. Once <methodname>Connector.create()</methodname>
- has been called,
+ <classname>FactoryConfigSample</classname> and options 4, 5, 8, and 9
+ are illustrated in <classname>FactoryConfigSSLSample</classname>, both
+ of which are in package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.</para>
+
+ <para><emphasis role="bold">Timing considerations.</emphasis> A new
+ <classname>Client</classname>, with a client invoker, is created on
+ the server side whenever a callback listener is registered by a call
+ to <methodname>Client.addListener()</methodname>. If a
+ <classname>SocketFactory</classname> is supplied by any of options 1
+ to 5, it will be passed to the <classname>Client</classname>.
+ Otherwise, any information from options 6 to 9 will be passed to the
+ client invoker, which will create a
+ <classname>SocketFactory</classname> according to the rules given
+ below in the section on client side socket factory configuration. Once
+ <methodname>Connector.create()</methodname> has been called,
<methodname>ServerInvoker.setSocketFactory()</methodname>, may be
called at any time to determine the
- <classname>SocketFactory</classname> used by the next callback
- client invoker.
- </para>
+ <classname>SocketFactory</classname> used by the next callback client
+ invoker.</para>
</section>
</section>
<section>
<title>Client side programmatic configuration</title>
- <para>
- On the client side it is possible to configure socket factories for client
- invokers and to configure server socket factories for callback server invokers.
- Configuration on the client side is largely the same as configuration
- on the server side, with the exception that no
+
+ <para>On the client side it is possible to configure socket factories
+ for client invokers and to configure server socket factories for
+ callback server invokers. Configuration on the client side is largely
+ the same as configuration on the server side, with the exception that no
<classname>MBeanServer</classname> is assumed to be present, and the
<classname>Client</classname> has no facilities for parsing xml
- documents.
- </para>
+ documents.</para>
<section>
<title>Server socket factories.</title>
+
<para>For <classname>ServerSocketFactory</classname>s in callback
- server invokers, there are
- eight options for programmatic configuration, which are identical to
- options 1-3, 5 and 7-10 on the server side (we don't assume the
- existence of an <classname>MBeanServer</classname> on the client
- side:</para>
+ server invokers, there are eight options for programmatic
+ configuration, which are identical to options 1-3, 5 and 7-10 on the
+ server side (we don't assume the existence of an
+ <classname>MBeanServer</classname> on the client side:</para>
<orderedlist>
<listitem>
@@ -3295,29 +3198,25 @@
</listitem>
<listitem>
- <para>Call <methodname>Connector.setServerSocketFactory()</methodname>.
- </para>
+ <para>Call
+ <methodname>Connector.setServerSocketFactory()</methodname>.</para>
</listitem>
<listitem>
- <para>
- Put a constructed <classname>ServerSocketFactory</classname> in a
- configuration map, using key
- <constant>Remoting.CUSTOM_SERVER_SOCKET_FACTORY</constant>,
- and pass the map to one of the <classname>Connector</classname>
- constructors.
- </para>
+ <para>Put a constructed <classname>ServerSocketFactory</classname>
+ in a configuration map, using key
+ <constant>Remoting.CUSTOM_SERVER_SOCKET_FACTORY</constant>, and
+ pass the map to one of the <classname>Connector</classname>
+ constructors.</para>
</listitem>
<listitem>
- <para>
- Create an xml document with root element <code><config></code>,
- setting the <code><serverSocketFactory></code> attribute to
- the class name of a <classname>ServerSocketFactory</classname> and pass
- the document to <methodname>Connector.setConfiguration()</methodname>.
- For example:
-
- <programlisting>
+ <para>Create an xml document with root element
+ <code><config></code>, setting the
+ <code><serverSocketFactory></code> attribute to the class
+ name of a <classname>ServerSocketFactory</classname> and pass the
+ document to <methodname>Connector.setConfiguration()</methodname>.
+ For example: <programlisting>
StringBuffer buf = new StringBuffer();
buf.append("<?xml version=\"1.0\"?>\n");
buf.append("<config>");
@@ -3330,222 +3229,179 @@
ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
connector.setConfiguration(xml.getDocumentElement());
- </programlisting>
-
- The <classname>ServerSocketFactory</classname> class must
- have a default constructor, which will be used to create a
- <classname>ServerSocketFactory</classname>.
- </para>
+ </programlisting> The
+ <classname>ServerSocketFactory</classname> class must have a
+ default constructor, which will be used to create a
+ <classname>ServerSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Put the class name of a <classname>ServerSocketFactory</classname>
- in a configuration map, using key
- <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
- and pass the map to one of the <classname>Connector</classname> constructors.
- The <classname>ServerSocketFactory</classname> class must
- have a default constructor, which will be used to create a
+ <para>Put the class name of a
+ <classname>ServerSocketFactory</classname> in a configuration map,
+ using key
+ <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>, and pass
+ the map to one of the <classname>Connector</classname>
+ constructors. The <classname>ServerSocketFactory</classname> class
+ must have a default constructor, which will be used to create a
<classname>ServerSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Put a set of SSL parameters, using the keys in
- <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>, in a
- configuration map and pass the map to one of the
- <classname>Connector</classname> constructors. These will be used by
- <classname>SSLSocketBuilder</classname> (see below) to create a
- <classname>CustomSSLServerSocketFactory</classname>.
- </para>
+ <para>Put a set of SSL parameters, using the keys in
+ <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
+ in a configuration map and pass the map to one of the
+ <classname>Connector</classname> constructors. These will be used
+ by <classname>SSLSocketBuilder</classname> (see below) to create a
+ <classname>CustomSSLServerSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Configure an appropriate set of SSL system properties
- and use one of the SSL transports (https, sslmultiplex,
- sslrmi, or sslsocket). The properties will be used to
- create some kind of <classname>SSLServerSocketFactory</classname>,
- as determined by the transport.
- </para>
+ <para>Configure an appropriate set of SSL system properties and
+ use one of the SSL transports (https, sslmultiplex, sslrmi, or
+ sslsocket). The properties will be used to create some kind of
+ <classname>SSLServerSocketFactory</classname>, as determined by
+ the transport.</para>
</listitem>
<listitem>
- <para>
- Use one of the non-SSL transports and do nothing. A default
- <classname>ServerSocketFactory</classname> will be constructed.
- </para>
+ <para>Use one of the non-SSL transports and do nothing. A default
+ <classname>ServerSocketFactory</classname> will be
+ constructed.</para>
</listitem>
</orderedlist>
- <para>
- These options are essentially in descending order of precedence.
- For example, if options 3 and 5, for example, are both
- used, the factory passed in options 3 will prevail.
- Options 1, 2, 3, 4, and 5 are illustrated in
- <classname>FactoryConfigSample</classname>
- and options 6 and 7 are illustrated in
- <classname>FactoryConfigSSLSample</classname>,
- both of which are in package
- <classname>org.jboss.remoting.samples.config.factories</classname>.
- </para>
+ <para>These options are essentially in descending order of precedence.
+ For example, if options 3 and 5, for example, are both used, the
+ factory passed in options 3 will prevail. Options 1, 2, 3, 4, and 5
+ are illustrated in <classname>FactoryConfigSample</classname> and
+ options 6 and 7 are illustrated in
+ <classname>FactoryConfigSSLSample</classname>, both of which are in
+ package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.</para>
- <para>
- <emphasis role="bold">Timing considerations.</emphasis> See the
+ <para><emphasis role="bold">Timing considerations.</emphasis> See the
discussion in the section on the creation of server socket factories
- on the server side.
- </para>
+ on the server side.</para>
</section>
<section>
<title>Socket factories.</title>
- <para>
- For <classname>SocketFactory</classname>s in client invokers,
- there are seven options
- for programmatic configuration, and they are essentially the same as
- 1-3 and 5-8 in the previous section (<classname>Client</classname>
- has no facility for parsing xml documents:</para>
- <orderedlist>
+ <para>For <classname>SocketFactory</classname>s in client invokers,
+ there are seven options for programmatic configuration, and they are
+ essentially the same as 1-3 and 5-8 in the previous section
+ (<classname>Client</classname> has no facility for parsing xml
+ documents:</para>
+ <orderedlist>
<listitem>
- <para>
- Get the <classname>ClientInvoker</classname> by calling
+ <para>Get the <classname>ClientInvoker</classname> by calling
<methodname>Client.getInvoker()</methodname> and call
- <methodname>ClientInvoker.setSocketFactory()</methodname>.
- </para>
+ <methodname>ClientInvoker.setSocketFactory()</methodname>.</para>
</listitem>
<listitem>
- <para>
- Call <methodname>Client.setSocketFactory()</methodname>.
- </para>
+ <para>Call
+ <methodname>Client.setSocketFactory()</methodname>.</para>
</listitem>
<listitem>
- <para>
- Put a constructed <classname>SocketFactory</classname> in a
+ <para>Put a constructed <classname>SocketFactory</classname> in a
configuration map, using key
- <constant>Remoting.CUSTOM_SOCKET_FACTORY</constant>, and pass
- the map to one of the <classname>Client</classname> constructors.
-
- </para>
+ <constant>Remoting.CUSTOM_SOCKET_FACTORY</constant>, and pass the
+ map to one of the <classname>Client</classname>
+ constructors.</para>
</listitem>
<listitem>
- <para>
- Put the class name of a <classname>SocketFactory</classname>
+ <para>Put the class name of a <classname>SocketFactory</classname>
in a configuration map, using key
- <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the map
- to one of the <classname>Client</classname> constructors.
- The <classname>SocketFactory</classname> class must
- have a default constructor, which will be used to create a
- <classname>SocketFactory</classname>.
-
- </para>
+ <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the
+ map to one of the <classname>Client</classname> constructors. The
+ <classname>SocketFactory</classname> class must have a default
+ constructor, which will be used to create a
+ <classname>SocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Put a set of SSL parameters, using the keys in
+ <para>Put a set of SSL parameters, using the keys in
<classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
in a configuration map and pass the map to one of the
<classname>Client</classname> constructors. These will be used by
<classname>SSLSocketBuilder</classname> (see below) to create a
- <classname>CustomSSLSocketFactory</classname>.
-
- </para>
+ <classname>CustomSSLSocketFactory</classname>.</para>
</listitem>
<listitem>
- <para>
- Configure an appropriate set of SSL system properties and use one of
- the SSL transports (https, sslmultiplex, sslrmi, or sslsocket). The
- properties will be used to create some kind of
+ <para>Configure an appropriate set of SSL system properties and
+ use one of the SSL transports (https, sslmultiplex, sslrmi, or
+ sslsocket). The properties will be used to create some kind of
<classname>SSLSocketFactory</classname>, as determined by the
- transport.
- </para>
+ transport.</para>
</listitem>
<listitem>
- <para>
- Use one of the non-SSL transports and do nothing. Ordinary
- <classname>Socket</classname>s will be used.
- </para>
+ <para>Use one of the non-SSL transports and do nothing. Ordinary
+ <classname>Socket</classname>s will be used.</para>
</listitem>
</orderedlist>
<para>Again, these are essentially in descending order of precedence.
Options 1, 2, 3, and 4 are illustrated in
- <classname>FactoryConfigSample</classname>
- and options 5 and 6 are illustrated in
- <classname>FactoryConfigSSLSample</classname>,
- both of which are in package
- <classname>org.jboss.remoting.samples.config.factories</classname>.
- </para>
-
- <para>
- <emphasis role="bold">Timing considerations.</emphasis> A
- <classname>SocketFactory</classname> is created in the constructor
- for <classname>RemoteClientInvoker</classname>, the ancestor of
- all current remote client invokers (that is, all client invokers except
- <classname>LocalClientInvoker</classname>, which can make a call
- by reference on a server invoker in the same JVM), but it is
- currently used only by SSL transports, for which the timing
- considerations vary.</para>
+ <classname>FactoryConfigSample</classname> and options 5 and 6 are
+ illustrated in <classname>FactoryConfigSSLSample</classname>, both of
+ which are in package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.</para>
+
+ <para><emphasis role="bold">Timing considerations.</emphasis> A
+ <classname>SocketFactory</classname> is created in the constructor for
+ <classname>RemoteClientInvoker</classname>, the ancestor of all
+ current remote client invokers (that is, all client invokers except
+ <classname>LocalClientInvoker</classname>, which can make a call by
+ reference on a server invoker in the same JVM), but it is currently
+ used only by SSL transports, for which the timing considerations
+ vary.</para>
<orderedlist>
-
<listitem>
- <para>
- <emphasis role="bold">https: </emphasis>
- <classname>HTTPSClientInvoker</classname> sets the
- socket factory on its
- <classname>HttpsURLConnection</classname> each time
- <methodname>Client.invoke()</methodname> is called. Option
- 1 may be used to reset the <classname>SocketFactory</classname>
- for future invocations at any time.
- </para>
+ <para><emphasis role="bold">https: </emphasis>
+ <classname>HTTPSClientInvoker</classname> sets the socket factory
+ on its <classname>HttpsURLConnection</classname> each time
+ <methodname>Client.invoke()</methodname> is called. Option 1 may
+ be used to reset the <classname>SocketFactory</classname> for
+ future invocations at any time.</para>
</listitem>
<listitem>
- <para>
- <emphasis role="bold">sslmultiplex: </emphasis> Whichever
- of <classname>SSLMultiplexClientInvoker</classname> or
- <classname>SSLMultiplexServerInvoker</classname> first
- gets sufficient bind and connect information to create a
- priming socket (see the section on the multiplex invoker for
- a discussion of priming sockets) passes the
- current <classname>SocketFactory</classname> to be
- used to create the actual
- socket that supports the multiplexed connection. This
+ <para><emphasis role="bold">sslmultiplex: </emphasis> Whichever of
+ <classname>SSLMultiplexClientInvoker</classname> or
+ <classname>SSLMultiplexServerInvoker</classname> first gets
+ sufficient bind and connect information to create a priming socket
+ (see the section on the multiplex invoker for a discussion of
+ priming sockets) passes the current
+ <classname>SocketFactory</classname> to be used to create the
+ actual socket that supports the multiplexed connection. This
happens during the call to either
<methodname>Client.connect()</methodname> or
- <methodname>Connector.create()</methodname>. Once the
- actual socket is created, no further configuration is
- possible
- </para>
+ <methodname>Connector.create()</methodname>. Once the actual
+ socket is created, no further configuration is possible</para>
</listitem>
<listitem>
- <para>
- <emphasis role="bold">sslrmi: </emphasis> A
- <classname>SocketFactory</classname>
- is either created or configured for future creation during
- <methodname>Client.create()</methodname>. No further
- configuration is possible.
- </para>
+ <para><emphasis role="bold">sslrmi: </emphasis> A
+ <classname>SocketFactory</classname> is either created or
+ configured for future creation during
+ <methodname>Client.create()</methodname>. No further configuration
+ is possible.</para>
</listitem>
<listitem>
- <para>
- <emphasis role="bold">sslsocket: </emphasis>
+ <para><emphasis role="bold">sslsocket: </emphasis>
<classname>SSLSocketClientInvoker</classname> uses the current
<classname>SocketFactory</classname> to create a new socket
- whenever it runs out of available pooled connections. Option
- 1 may be used to reset the <classname>SocketFactory</classname>
- for future connections at any time.
- </para>
+ whenever it runs out of available pooled connections. Option 1 may
+ be used to reset the <classname>SocketFactory</classname> for
+ future connections at any time.</para>
</listitem>
</orderedlist>
</section>
@@ -3554,19 +3410,17 @@
<section>
<title>Server side configuration in the JBoss Application Server</title>
- <para>
- Everything in the previous two sections applies to configuring socket
- and server socket factories in any environment, including inside the
- JBoss Application Server (JBossAS), but JBossAS adds some new options.
- In particular, the <classname>SARDeployer</classname> (see
- <emphasis>The JBoss 4 Application Server Guide</emphasis>
- on the labs.jboss.org web site) can read information
- from a <code>*-service.xml</code> file, as discussed above in the
- section "General Connector and Invoker configuration," and use it to
- configure MBeans such as <classname>Connector</classname>s.</para>
+ <para>Everything in the previous two sections applies to configuring
+ socket and server socket factories in any environment, including inside
+ the JBoss Application Server (JBossAS), but JBossAS adds some new
+ options. In particular, the <classname>SARDeployer</classname> (see
+ <emphasis>The JBoss 4 Application Server Guide</emphasis> on the
+ labs.jboss.org web site) can read information from a
+ <code>*-service.xml</code> file, as discussed above in the section
+ "General Connector and Invoker configuration," and use it to configure
+ MBeans such as <classname>Connector</classname>s.</para>
- <para>
- An example of a service xml that covers all the different
+ <para>An example of a service xml that covers all the different
transport and service configurations can be found within the
example-service.xml file under the etc directory of the JBoss Remoting
distribution.</para>
@@ -3586,14 +3440,11 @@
</listitem>
<listitem>
- <para>
- the class name of a <classname>ServerSocketFactory</classname>
- with a default constructor.
- </para>
+ <para>the class name of a <classname>ServerSocketFactory</classname>
+ with a default constructor.</para>
</listitem>
</orderedlist>
-
<para>An example of the first case would be:</para>
<programlisting>
@@ -3611,28 +3462,29 @@
<attribute name="numAcceptThreads">1</attribute>
</programlisting>
- <para>The <code>serverSocketFactory</code> attribute is processed
- as follows:</para>
+ <para>The <code>serverSocketFactory</code> attribute is processed as
+ follows:</para>
<orderedlist>
<listitem>
- <para>Take its String value, create an <classname>ObjectName</classname>
- from it, and look up an MBean with that name from the <classname>MBeanServer</classname>
- that the invoker has been registered with (by
- way of the <classname>Connector</classname>). If an MBean with that
- name is found, create a proxy to it of type
+ <para>Take its String value, create an
+ <classname>ObjectName</classname> from it, and look up an MBean with
+ that name from the <classname>MBeanServer</classname> that the
+ invoker has been registered with (by way of the
+ <classname>Connector</classname>). If an MBean with that name is
+ found, create a proxy to it of type
<code>org.jboss.remoting.security.ServerSocketFactoryMBean</code>.
- (Technically, a user could set the
- <code>serverSocketFactory</code> property with the locator url, but the
- preferred method is to use the explicit configuration via the invoker
- element's attribute, as discussed above.)</para>
+ (Technically, a user could set the <code>serverSocketFactory</code>
+ property with the locator url, but the preferred method is to use
+ the explicit configuration via the invoker element's attribute, as
+ discussed above.)</para>
</listitem>
<listitem>
<para>If no MBean is found with a matching
- <classname>ObjectName</classname>,
- treat the <code>serverSocketFactory</code> attribute as a class name
- and try to create an instance using the default constructor.</para>
+ <classname>ObjectName</classname>, treat the
+ <code>serverSocketFactory</code> attribute as a class name and try
+ to create an instance using the default constructor.</para>
</listitem>
</orderedlist>
@@ -3642,22 +3494,22 @@
later.</para>
<para>Note that these two options correspond exactly to options 4 and 5
- in section <xref linkend="section-ssf-serverside"/> (on the server side),
- which is how these two new options are implemented.</para>
+ in section <xref linkend="section-ssf-serverside" /> (on the server
+ side), which is how these two new options are implemented.</para>
<para><emphasis role="bold">Timing considerations.</emphasis> If a
<classname>Connector</classname> is accessed by way of the
<classname>MBeanServer</classname>, then most of the options for
- configuring the server socket factory discussed in
- <xref linkend="section-ssf-serverside"/> are irrelevant since
+ configuring the server socket factory discussed in <xref
+ linkend="section-ssf-serverside" /> are irrelevant since
<classname>ConnectorMBean</classname> does not expose methods for using
- them. However, when a <classname>Connector</classname> that is registered
- with an <classname>MBeanServer</classname> creates a
- server invoker during a call to
- <methodname>Connector.create()</methodname>, it also registers the
- server invoker with the same <classname>MBeanServer</classname>, which
- means that the server invoker is accessible by way of its
- <classname>ObjectName</classname>, which has the form</para>
+ them. However, when a <classname>Connector</classname> that is
+ registered with an <classname>MBeanServer</classname> creates a server
+ invoker during a call to <methodname>Connector.create()</methodname>, it
+ also registers the server invoker with the same
+ <classname>MBeanServer</classname>, which means that the server invoker
+ is accessible by way of its <classname>ObjectName</classname>, which has
+ the form</para>
<programlisting>
jboss.remoting:service=invoker,transport=socket,host=www.jboss.com,port=8765
@@ -3666,9 +3518,9 @@
<para>for example, followed by additional parameter=value pairs. (See
the jmx-console for a running instance of JBossAS at
http://localhost:8080/jmx-console/ to see examples of server invoker
- <classname>ObjectName</classname>s.) Now, if another
- MBean is configured in a <code>*-service.xml</code> file to be
- dependent on the server invoker MBean, e.g.</para>
+ <classname>ObjectName</classname>s.) Now, if another MBean is configured
+ in a <code>*-service.xml</code> file to be dependent on the server
+ invoker MBean, e.g.</para>
<programlisting>
<mbean code="org.jboss.BlueMonkey" name="jboss.remoting:bluemonkey,name=diamond">
@@ -3678,8 +3530,8 @@
</mbean>
</programlisting>
- <para>then <methodname>org.jboss.BlueMonkey.create()</methodname> will have
- access to the designated server invoker after the invoker has been
+ <para>then <methodname>org.jboss.BlueMonkey.create()</methodname> will
+ have access to the designated server invoker after the invoker has been
created but before it has been started, which means that
<methodname>ServerInvoker.setServerSocketFactory()</methodname> will be
effective. (See the <emphasis>The JBoss 4 Application Server
@@ -3692,18 +3544,18 @@
<para>There are now four transports that support SSL: https,
sslmultiplex, sslrmi, and sslsocket (plus sslservlet, which is not
- relevant here). All of the preceding discussion
- applies to each of these, and, moreover, they are all extensions of their
- non-ssl counterparts, so only some ssl specific information will be
- added here.</para>
+ relevant here). All of the preceding discussion applies to each of
+ these, and, moreover, they are all extensions of their non-ssl
+ counterparts, so only some ssl specific information will be added
+ here.</para>
<bridgehead>https</bridgehead>
- <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
+ <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
@@ -3749,15 +3601,15 @@
</mbean>
</programlisting>
- <para>See section <xref linkend="section-SSLServerSocketFactoryService"/>
- below for a discussion of the
- "jboss.remoting:service=ServerSocketFactory,type=SSL"
+ <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>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
- <xref linkend="section-http-invoker"/>
- for more information on using the APR based transport.</para>
+ <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 <xref linkend="section-http-invoker" /> for more information on
+ using the APR based transport.</para>
<bridgehead>sslmultiplex</bridgehead>
@@ -3769,19 +3621,20 @@
</programlisting>
<para>which supports dynamic replacement of server socket factories. The
- principal motivation for this facility is to be able to swap in a
- new <classname>SSLServerSocketFactory</classname> configured with an
- updated keystore.</para>
-
- <bridgehead id="subsection-sslrmi" xreflabel="sslrmi">sslrmi</bridgehead>
-
- <para>The extra twist in the sslrmi invoker is that
- the server invoker creates the (client) socket factory and packages it
- with its own stub, from which it follows that the socket factory must
- be serializable. If the sslrmi server invoker is allowed to create an
+ principal motivation for this facility is to be able to swap in a new
+ <classname>SSLServerSocketFactory</classname> configured with an updated
+ keystore.</para>
+
+ <bridgehead id="subsection-sslrmi"
+ xreflabel="sslrmi">sslrmi</bridgehead>
+
+ <para>The extra twist in the sslrmi invoker is that the server invoker
+ creates the (client) socket factory and packages it with its own stub,
+ from which it follows that the socket factory must be serializable. If
+ the sslrmi 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
+ 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
@@ -3789,21 +3642,22 @@
client 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
+ 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>
+ 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 above, then the user is responsible for supplying
- a serializable socket factory.</para>
+ <classname>SerializableSSLClientSocketFactory</classname>, a socket
+ factory is passed in to the server invoker by one of the methods
+ discussed above, 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>
@@ -3819,19 +3673,17 @@
</programlisting>
<para>which supports dynamic replacement of server socket factories. The
- principal motivation for this facility is to be able to swap in a
- new <classname>SSLServerSocketFactory</classname> configured with an
- updated keystore.</para>
-
+ principal motivation for this facility is to be able to swap in a new
+ <classname>SSLServerSocketFactory</classname> configured with an updated
+ keystore.</para>
</section>
<section>
<title>SSLSocketBuilder</title>
- <para>Throughout this section reference has been made to SSL
- socket factory and server socket factory configuration parameters.
- This subsection will introduce these parameters in the context of
- configuring
+ <para>Throughout this section reference has been made to SSL socket
+ factory and server socket factory configuration parameters. This
+ subsection will introduce these parameters in the context of configuring
<classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
Remoting's flexible, highly customizable master factory for creating
socket and server socket factories. It can be used programmatically on
@@ -3841,28 +3693,27 @@
<para>Once a <classname>SSLSocketBuilder</classname> has been
constructed and configured, a call to its method
- <methodname>createSSLServerSocketFactory()</methodname> will return a custom
- instance of a <classname>SSLServerSocketFactory</classname>, and a
- call to <methodname>createSSLSocketFactory()</methodname> will
- return a custom instance of <classname>SSLSocketFactory</classname>.</para>
-
- <para>
- There are two modes in which the <classname>SSLSocketBuilder</classname>
- can be run. The first is the default mode where all that is needed is to
- declare the <classname>SSLSocketBuilder</classname> and set the system properties
+ <methodname>createSSLServerSocketFactory()</methodname> will return a
+ custom instance of a <classname>SSLServerSocketFactory</classname>, and
+ a call to <methodname>createSSLSocketFactory()</methodname> will return
+ a custom instance of <classname>SSLSocketFactory</classname>.</para>
+
+ <para>There are two modes in which the
+ <classname>SSLSocketBuilder</classname> can be run. The first is the
+ default mode where all that is needed is to declare the
+ <classname>SSLSocketBuilder</classname> and set the system properties
<code>javax.net.ssl.keyStore</code> and
<code>javax.net.ssl.keyStorePassword</code>. This will use the JVM
vendor's default configuration for creating the SSL server socket
factory.</para>
- <para>In order to customize any of the SSL properties, the
- first requirement is that the default mode is turned off. This is
- <emphasis role="bold">IMPORTANT</emphasis> because otherwise, if the
- default mode is not explicitly turned off, all other settings will be
- IGNORED, even if they are explicitly set. To turn off the default mode
- via service xml configuration, set the
- <code>UseSSLServerSocketFactory</code> attribute to false. This can also
- be done programmatically by calling the
+ <para>In order to customize any of the SSL properties, the first
+ requirement is that the default mode is turned off. This is <emphasis
+ role="bold">IMPORTANT</emphasis> because otherwise, if the default mode
+ is not explicitly turned off, all other settings will be IGNORED, even
+ if they are explicitly set. To turn off the default mode via service xml
+ configuration, set the <code>UseSSLServerSocketFactory</code> attribute
+ to false. This can also be done programmatically by calling the
<code>setUseSSLServerSocketFactory()</code> and passing false as the
parameter value.</para>
@@ -3882,7 +3733,6 @@
</listitem>
</orderedlist>
-
<para>The configuration properties for
<classname>SSLSocketBuilder</classname>are as follows:</para>
@@ -3891,249 +3741,305 @@
parameters.</title>
<tgroup cols="5">
+ <colspec colname="c1" colnum="1" />
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3" align="center"/>
- <colspec colname="c4" colnum="4" align="center"/>
- <colspec colname="c5" colnum="5"/>
+ <colspec colname="c2" colnum="2" />
+
+ <colspec align="center" colname="c3" colnum="3" />
+
+ <colspec align="center" colname="c4" colnum="4" />
+
+ <colspec colname="c5" colnum="5" />
<thead>
<row>
- <entry>
- <para>attribute</para>
- </entry>
- <entry>
- <para>key name</para>
- </entry>
- <entry>
- <para>type</para>
- </entry>
- <entry>
- <para>default</para>
- </entry>
- <entry>
- <para>description</para>
- </entry>
+ <entry><para>attribute</para></entry>
+
+ <entry><para>key name</para></entry>
+
+ <entry><para>type</para></entry>
+
+ <entry><para>default</para></entry>
+
+ <entry><para>description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>ClientAuthMode</para></entry>
+
<entry><para>REMOTING_CLIENT_AUTH_MODE</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para>need</para></entry>
- <entry>
- <para>Determines if sockets need or want
- client authentication. This configuration option is only
- useful for sockets in the server mode. Value may be
- "none", "want", or "need".</para></entry>
+
+ <entry><para>Determines if sockets need or want client
+ authentication. This configuration option is only useful for
+ sockets in the server mode. Value may be "none", "want", or
+ "need".</para></entry>
</row>
<row>
<entry><para>KeyAlias</para></entry>
+
<entry><para>REMOTING_KEY_ALIAS</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>The preferred identity in key store to be used by
+
+ <entry><para>The preferred identity in key store to be used by
key managers</para></entry>
</row>
<row>
<entry><para>KeyPassword</para></entry>
+
<entry><para>REMOTING_KEY_PASSWORD</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>Sets the password to use for the keys within the key store.
- This only needs to be set if
- <methodname>setUseSSLServerSocketFactory()</methodname> is set to false
- (otherwise will be ignored). If this value is not set, but
- the key store password is, it will use that value for the
+
+ <entry><para>Sets the password to use for the keys within the
+ key store. This only needs to be set if
+ <methodname>setUseSSLServerSocketFactory()</methodname> is set
+ to false (otherwise will be ignored). If this value is not set,
+ but the key store password is, it will use that value for the
key password.</para></entry>
</row>
<row>
<entry><para>KeyStoreAlgorithm</para></entry>
+
<entry><para>REMOTING_KEY_STORE_ALGORITHM</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para>SunX509</para></entry>
- <entry>
- <para>The algorithm for the key manager factory.</para></entry>
+
+ <entry><para>The algorithm for the key manager
+ factory.</para></entry>
</row>
<row>
<entry><para>KeyStorePassword</para></entry>
+
<entry><para>REMOTING_KEY_STORE_PASSWORD</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>The password
- to use for the key store. This only needs to be set if
- <methodname>setUseSSLServerSocketFactory()</methodname>
- is set to false (otherwise will be
- ignored). The value passed will also be used for the
- key password if the latter attribute is not explicitly
- set.</para></entry>
+
+ <entry><para>The password to use for the key store. This only
+ needs to be set if
+ <methodname>setUseSSLServerSocketFactory()</methodname> is set
+ to false (otherwise will be ignored). The value passed will also
+ be used for the key password if the latter attribute is not
+ explicitly set.</para></entry>
</row>
<row>
<entry><para>KeyStoreType</para></entry>
+
<entry><para>REMOTING_KEY_STORE_TYPE</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para>JKS</para></entry>
- <entry>
- <para>The type to be
- used for the key store. Some
+
+ <entry><para>The type to be used for the key store. Some
acceptable values are JKS (Java Keystore - Sun's keystore
- format), JCEKS (Java Cryptography Extension keystore -
- More secure version of JKS), and PKCS12 (Public-Key
- Cryptography Standards #12 keystore - RSA's Personal
- Information Exchange Syntax Standard). These are not case
- sensitive.</para></entry>
+ format), JCEKS (Java Cryptography Extension keystore - More
+ secure version of JKS), and PKCS12 (Public-Key Cryptography
+ Standards #12 keystore - RSA's Personal Information Exchange
+ Syntax Standard). These are not case sensitive.</para></entry>
</row>
<row>
<entry><para>KeyStoreURL</para></entry>
+
<entry><para>REMOTING_KEY_STORE_FILE_PATH</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>Property used to define where
- <classname>SSLSocketBuilder</classname> will
- look for the keystore file. This can be relative to the thread's
- classloader or can be an absolute path on the file system or
- can be a URL.</para></entry>
+
+ <entry><para>Property used to define where
+ <classname>SSLSocketBuilder</classname> will look for the
+ keystore file. This can be relative to the thread's classloader
+ or can be an absolute path on the file system or can be a
+ URL.</para></entry>
</row>
<row>
<entry><para>Provider</para></entry>
+
<entry><para>none</para></entry>
+
<entry><para>java.security.Provider</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>Java Security API implementation to use.</para></entry>
+
+ <entry><para>Java Security API implementation to
+ use.</para></entry>
</row>
<row>
<entry><para>ProviderName</para></entry>
+
<entry><para>REMOTING_SSL_PROVIDER_NAME</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>Name of Java Security API implementation to use.
+
+ <entry><para>Name of Java Security API implementation to use.
</para></entry>
</row>
<row>
<entry><para>SecureRandom</para></entry>
+
<entry><para>none</para></entry>
+
<entry><para>java.security.SecureRandom</para></entry>
+
<entry><para><code>new SecureRandom()</code></para></entry>
- <entry>
- <para>Random number generator to use.</para></entry>
+
+ <entry><para>Random number generator to use.</para></entry>
</row>
<row>
<entry><para>SecureSocketProtocol</para></entry>
+
<entry><para>REMOTING_SSL_PROTOCOL</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para>TLS</para></entry>
- <entry>
- <para> The protocol for the <classname>SSLContext</classname>.
- Some acceptable values are TLS, SSL, and SSLv3</para></entry>
+
+ <entry><para> The protocol for the
+ <classname>SSLContext</classname>. Some acceptable values are
+ TLS, SSL, and SSLv3</para></entry>
</row>
<row>
<entry><para>ServerAuthMode</para></entry>
+
<entry><para>REMOTING_SERVER_AUTH_MODE</para></entry>
+
<entry><para>boolean/String</para></entry>
+
<entry><para>true</para></entry>
- <entry>
- <para>Determines if a client should attempt to
- authenticate a server certificate as one it trusts.</para></entry>
+
+ <entry><para>Determines if a client should attempt to
+ authenticate a server certificate as one it
+ trusts.</para></entry>
</row>
<row>
<entry><para>ServerSocketUseClientMode</para></entry>
+
<entry><para>REMOTING_SERVER_SOCKET_USE_CLIENT_MODE</para></entry>
+
<entry><para>boolean/String</para></entry>
+
<entry><para>false</para></entry>
- <entry>
- <para>Determines if the server sockets will be in
- client or server mode.</para></entry>
+
+ <entry><para>Determines if the server sockets will be in client
+ or server mode.</para></entry>
</row>
<row>
<entry><para>SocketUseClientMode</para></entry>
+
<entry><para>REMOTING_SOCKET_USE_CLIENT_MODE</para></entry>
+
<entry><para>boolean/String</para></entry>
+
<entry><para>true</para></entry>
- <entry>
- <para>Determines if the sockets will be in
- client or server mode.</para></entry>
+
+ <entry><para>Determines if the sockets will be in client or
+ server mode.</para></entry>
</row>
<row>
<entry><para>TrustStoreAlgorithm</para></entry>
+
<entry><para>REMOTING_TRUST_STORE_ALGORITHM</para></entry>
+
<entry><para>String</para></entry>
- <entry><para>value of <code>KeyStoreAlgorithm</code>, or
- SunX509 if <code>KeyStoreAlgorithm</code>
- is not set</para></entry>
- <entry>
- <para>trust store key management algorithm</para></entry>
+
+ <entry><para>value of <code>KeyStoreAlgorithm</code>, or SunX509
+ if <code>KeyStoreAlgorithm</code> is not set</para></entry>
+
+ <entry><para>trust store key management algorithm</para></entry>
</row>
<row>
<entry><para>TrustStorePassword</para></entry>
+
<entry><para>REMOTING_TRUST_STORE_PASSWORD</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>trust store password</para></entry>
+
+ <entry><para>trust store password</para></entry>
</row>
<row>
<entry><para>TrustStoreType</para></entry>
+
<entry><para>REMOTING_TRUST_STORE_TYPE</para></entry>
+
<entry><para>String</para></entry>
- <entry><para>value of <code>KeyStoreType</code>, or
- JKS if <code>KeyStoreType</code>
- is not set</para></entry>
- <entry>
- <para>type of trust store</para></entry>
+
+ <entry><para>value of <code>KeyStoreType</code>, or JKS if
+ <code>KeyStoreType</code> is not set</para></entry>
+
+ <entry><para>type of trust store</para></entry>
</row>
<row>
<entry><para>TrustStoreURL</para></entry>
+
<entry><para>REMOTING_TRUST_STORE_FILE_PATH</para></entry>
+
<entry><para>String</para></entry>
+
<entry><para></para></entry>
- <entry>
- <para>location of trust store</para></entry>
+
+ <entry><para>location of trust store</para></entry>
</row>
<row>
<entry><para>UseSSLServerSocketFactory</para></entry>
+
<entry><para>none</para></entry>
+
<entry><para>boolean</para></entry>
+
<entry><para>true</para></entry>
- <entry>
- <para>Determines if default
+
+ <entry><para>Determines if default
<classname>SSLServerSocketFactory</classname> should be
created.</para></entry>
</row>
<row>
<entry><para>UseSSLSocketFactory</para></entry>
+
<entry><para>none</para></entry>
+
<entry><para>boolean</para></entry>
+
<entry><para>true</para></entry>
- <entry>
- <para>Determines if default
+
+ <entry><para>Determines if default
<classname>SSLSocketFactory</classname> should be
created.</para></entry>
</row>
@@ -4141,20 +4047,18 @@
</tgroup>
</table>
- <para><emphasis role="bold">Note.</emphasis>
- If any of the attributes <code>KeyStoreURL</code>,
- <code>KeyStorePassword</code>, <code>KeyStoreType</code>,
- <code>TrustStoreURL</code>, <code>TrustStorePassword</code>, or
- <code>TrustStoreType</code> are left unconfigured,
- <classname>SSLSocketBuilder</classname> will also examine the
- corresponding standard SSL system properties "javax.net.ssl.keyStore",
- "javax.net.ssl.keyStorePassword", "javax.net.ssl.keyStoreType",
- "javax.net.ssl.trustStore", "javax.net.ssl.trustStorePassword",
- "javax.net.ssl.trustStoreType". In the cases of
- <code>KeyStoreType</code> and <code>TrustStoreType</code>,
- <classname>SSLSocketBuilder</classname> will then
- go on to use default values after checking the system
- properties.</para>
+ <para><emphasis role="bold">Note.</emphasis> If any of the attributes
+ <code>KeyStoreURL</code>, <code>KeyStorePassword</code>,
+ <code>KeyStoreType</code>, <code>TrustStoreURL</code>,
+ <code>TrustStorePassword</code>, or <code>TrustStoreType</code> are left
+ unconfigured, <classname>SSLSocketBuilder</classname> will also examine
+ the corresponding standard SSL system properties
+ "javax.net.ssl.keyStore", "javax.net.ssl.keyStorePassword",
+ "javax.net.ssl.keyStoreType", "javax.net.ssl.trustStore",
+ "javax.net.ssl.trustStorePassword", "javax.net.ssl.trustStoreType". In
+ the cases of <code>KeyStoreType</code> and <code>TrustStoreType</code>,
+ <classname>SSLSocketBuilder</classname> will then go on to use default
+ values after checking the system properties.</para>
<para>The following is an example of configuring a
<classname>SSLSocketBuilder</classname> and using it to create a custom
@@ -4175,9 +4079,10 @@
}
</programlisting>
- <para>More examples of configuring <classname>SSLSocketBuilder</classname> can
- be found in the class <classname>FactoryConfigSSLSample</classname> in the
- package <code>org.jboss.remoting.samples.config.factories</code>.</para>
+ <para>More examples of configuring
+ <classname>SSLSocketBuilder</classname> can be found in the class
+ <classname>FactoryConfigSSLSample</classname> in the package
+ <code>org.jboss.remoting.samples.config.factories</code>.</para>
<para>The following is an example of configuring
<classname>SSLSocketBuilder</classname> in a *-service.xml file:</para>
@@ -4219,6 +4124,14 @@
<attribute name="KeyStoreType">JKS</attribute>
</mbean>
</programlisting>
+
+ <para>It is also possible to set the default socket factory to be used
+ when not using customized settings (meaning UseSSLSocketFactory property
+ value is true, which is the default). This can be done by setting system
+ property of org.jboss.remoting.defaultSocketFactory to the fully
+ qualified class name of the javax.net.SocketFactory implementation to
+ use. Will then call the getDefault() method on that implementation to
+ get the SocketFactory instance to use.</para>
</section>
<section id="section-SSLServerSocketFactoryService"
@@ -4239,8 +4152,9 @@
<para>The following is an example of configuring
<classname>SSLServerSocketFactoryService</classname> in a *-service.xml
- file. Note that it depends on the <classname>SSLSocketBuilder</classname>
- MBean defined in the xml fragment above:</para>
+ file. Note that it depends on the
+ <classname>SSLSocketBuilder</classname> MBean defined in the xml
+ fragment above:</para>
<programlisting>
<!-- This service provides the exact same API as the ServerSocketFactory, so -->
@@ -4252,7 +4166,6 @@
proxy-type="attribute">jboss.remoting:service=SocketBuilder,type=SSL</depends>
</mbean>
</programlisting>
-
</section>
<section>
@@ -4355,10 +4268,10 @@
<section id="section-configuration" xreflabel="Configuration by properties">
<title>Configuration by properties</title>
- <para>This section covers configuration properties by constant values
- and bean properties for individual classes. This will duplicate some of
- the configuration properties already covered and is just another view to
- some of the same information.</para>
+ <para>This section covers configuration properties by constant values and
+ bean properties for individual classes. This will duplicate some of the
+ configuration properties already covered and is just another view to some
+ of the same information.</para>
<bridgehead>org.jboss.remoting.InvokerLocator</bridgehead>
@@ -4375,40 +4288,39 @@
when the initial bind address is 0.0.0.0 (or InvokerLocator.ANY).</para>
<para><emphasis role="bold">DATATYPE</emphasis> (actual value is
- 'datatype') - indicates the marshalling datatype that should be used for
- a particular invoker. Each invoker has its own default marshaller and
+ 'datatype') - indicates the marshalling datatype that should be used for a
+ particular invoker. Each invoker has its own default marshaller and
unmarshaller based on default datatype. For examle, the socket transport
has a default datatype of 'serializable', which is automatically
registered with the MarshalFactory and associated by default with
org.jboss.remoting.marshal.serializable.SerializableMarshaller and
org.jboss.remoting.marshal.serializable.SerializableUnMarshaller. The
- marshaller and unmarshaller used by an invoker can be overriden by
- setting the 'datatype' parameter within the LocatorInvoker. For example,
- could use a locator url of:</para>
+ marshaller and unmarshaller used by an invoker can be overriden by setting
+ the 'datatype' parameter within the LocatorInvoker. For example, could use
+ a locator url of:</para>
<programlisting>socket://myhost:6500/?datatype=test</programlisting>
<para>which would cause the socket invoker to use the marshaller and
- unmarshaller registered with the MarshalFactory under the datatype
- 'test'. Of course, this requires that the marshaller and unmarshaller
+ unmarshaller registered with the MarshalFactory under the datatype 'test'.
+ Of course, this requires that the marshaller and unmarshaller
implementations to be used have already been registered with the
MarshalFactory (otherwise will get an exception).</para>
- <para><emphasis role="bold">SERIALIZATIONTYPE</emphasis> (actual value
- is 'serializationtype') - indicates the serialization implementation to
- use. Currently, the only possible values are 'java' and 'jboss'. Java
+ <para><emphasis role="bold">SERIALIZATIONTYPE</emphasis> (actual value is
+ 'serializationtype') - indicates the serialization implementation to use.
+ Currently, the only possible values are 'java' and 'jboss'. Java
serialization is the default. Setting to 'jboss' will cause JBoss
- Serialization to be used. In implementation, this equates to the
- parameter that will be passed to the
- SerializationStreamFactory.getManagerInstance() method. This
- configuration can be set as an invoker locator url parameter (e.g.
- socket://myhost:5400/?serializationtype=jboss) or as an entry to the
+ Serialization to be used. In implementation, this equates to the parameter
+ that will be passed to the SerializationStreamFactory.getManagerInstance()
+ method. This configuration can be set as an invoker locator url parameter
+ (e.g. socket://myhost:5400/?serializationtype=jboss) or as an entry to the
configuration Map passed when constructing a remoting client or
server.</para>
<para><emphasis role="bold">MARSHALLER</emphasis> (actual value is
- 'marshaller') - used to indicate which marshaller implementation should
- be used by the invoker. This is an override for whatever the invoker's
+ 'marshaller') - used to indicate which marshaller implementation should be
+ used by the invoker. This is an override for whatever the invoker's
default implementation is. This can be set as a parameter of the invoker
locator url (e.g.
socket://myhost:6500/?marshaller=org.jboss.test.remoting.marshall.dynamic.remote.http.TestMarshaller).
@@ -4420,12 +4332,12 @@
<para><emphasis role="bold">UNMARSHALLER</emphasis> (actual value is
'unmarshaller') - used to indicate which unmarshaller implementation
should be used by the invoker. This is an override for whatever the
- invoker's default implementation is. This can be set as a parameter of
- the invoker locator url (e.g.
+ invoker's default implementation is. This can be set as a parameter of the
+ invoker locator url (e.g.
socket://myhost:6500/?unmarshaller=org.jboss.test.remoting.marshall.dynamic.remote.http.TestUnMarshaller).
Using this configuration requires that the value be the fully qualified
- classname of the unmarshaller implementation to use (which must be on
- the classpath, have a void constructor, and implement the
+ classname of the unmarshaller implementation to use (which must be on the
+ classpath, have a void constructor, and implement the
org.jboss.remotng.marshal.UnMarshaller interface).</para>
<para><emphasis role="bold">LOADER_PORT</emphasis> (actual value is
@@ -4434,10 +4346,9 @@
particular classes locally and would want to load them from the server
dynamically. This property can be set as a parameter to the invoker
locator url. A clasic example of when this might be used would be in
- conjunction with using custom marshalling. For example, if have
- configured a server to use custom marshaller and unmarshaller that the
- client will not have access to, could create a invoker locator such
- as:</para>
+ conjunction with using custom marshalling. For example, if have configured
+ a server to use custom marshaller and unmarshaller that the client will
+ not have access to, could create a invoker locator such as:</para>
<programlisting>socket://myhost:6500/?datatype=test&loaderport=6501&
marshaller=org.jboss.test.remoting.marshall.dynamic.remote.http.TestMarshaller&
@@ -4455,12 +4366,11 @@
<para>This can work for loading any remote server classes, but requires
the loaderport be included in the invoker locator url.</para>
- <para><emphasis role="bold">BYVALUE</emphasis> (actual value is
- 'byvalue') - indicates if when making local invocations (meaning client
- and server invoker exists within same jvm), the marshalling will be done
- by value, instead of the default, by reference. Using this
- configuration, the marshalling will actually perform a clone of the
- object instance (see
+ <para><emphasis role="bold">BYVALUE</emphasis> (actual value is 'byvalue')
+ - indicates if when making local invocations (meaning client and server
+ invoker exists within same jvm), the marshalling will be done by value,
+ instead of the default, by reference. Using this configuration, the
+ marshalling will actually perform a clone of the object instance (see
org.jboss.remoting.serialization.SerializationManager.createMarshalledValueForClone()).
Value for this property should be of type String and be either 'true' or
'false'. In releases prior to 2.0.0, using this configuration setting
@@ -4471,45 +4381,45 @@
'force_remote') - indicates if when making local invocations (meaning
client and server invoker exists within same jvm), the remote invokers
should be used instead of local invoker. Is equivalent to making
- invocations as though client and server were in different jvms). Value
- for this property should be of type String and be either 'true' or
+ invocations as though client and server were in different jvms). Value for
+ this property should be of type String and be either 'true' or
'false'.</para>
<para><emphasis role="bold">CLIENT_LEASE</emphasis> (actual value is
'leasing') - indicates if client should try to automatically establish a
- lease with the server. Is false by default. Value for this property
- should be of type String and be either 'true' or 'false'.</para>
+ lease with the server. Is false by default. Value for this property should
+ be of type String and be either 'true' or 'false'.</para>
<para><emphasis role="bold">CLIENT_LEASE_PERIOD</emphasis> (actual value
- is 'lease_period') - defines what the client lease period should be in
- the case that server side leasing is turned on. Value for this parameter
- key should be the number of milliseconds to wait before each client
- lease renewal and must be greater than zero in order to be recognized.
- If this property is not set (and CLIENT_LEASE is), will use the lease
- period as specified by the server.</para>
+ is 'lease_period') - defines what the client lease period should be in the
+ case that server side leasing is turned on. Value for this parameter key
+ should be the number of milliseconds to wait before each client lease
+ renewal and must be greater than zero in order to be recognized. If this
+ property is not set (and CLIENT_LEASE is), will use the lease period as
+ specified by the server.</para>
<para></para>
<bridgehead>org.jboss.remoting.Client</bridgehead>
- <para><emphasis role="bold">RAW</emphasis> (actual value is
- 'rawPayload') - key to use for the metadata Map passed when making an
- invoke() call and wish for the invocation payload to be sent as is and
- not wrapped within a remoting invocation request object. This should be
- used when want to make direct calls on systems outside of remoting (e.g.
- making an http POST request to a web service).</para>
+ <para><emphasis role="bold">RAW</emphasis> (actual value is 'rawPayload')
+ - key to use for the metadata Map passed when making an invoke() call and
+ wish for the invocation payload to be sent as is and not wrapped within a
+ remoting invocation request object. This should be used when want to make
+ direct calls on systems outside of remoting (e.g. making an http POST
+ request to a web service).</para>
<para><emphasis role="bold">ENABLE_LEASE</emphasis> (actual value is
'enableLease') - key for the configuration map passed to the Client
constructor to indicate that client should make initial request to
- establish lease with server. The value for this should be either a
- String that java.lang.Boolean can evaluate or a java.lang.Boolean. By
- default, leasing is turned off, so this property would be used to turn
- on leasing for the client.</para>
+ establish lease with server. The value for this should be either a String
+ that java.lang.Boolean can evaluate or a java.lang.Boolean. By default,
+ leasing is turned off, so this property would be used to turn on leasing
+ for the client.</para>
<para><emphasis role="bold">HANDSHAKE_COMPLETED_LISTENER</emphasis>
- (actual value is 'handshakeCompletedListener') - key for the
- configuration map passed to the Client constructor providing a ssl
+ (actual value is 'handshakeCompletedListener') - key for the configuration
+ map passed to the Client constructor providing a ssl
javax.net.ssl.HandshakeCompletedListener implementation, which will be
called on when ssl handshake completed with server.</para>
@@ -4522,33 +4432,33 @@
public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject, boolean serverToClient) throws Throwable</programlisting>
<para><emphasis role="bold">CALLBACK_SERVER_PROTOCOL</emphasis> (actual
- value is 'callbackServerProtocol') - key for the configuration when
- adding a callback handler and internal callback server connector is
- created. The value should be the transport protocol to be used. By
- default will use the same protocol as being used by this client (e.g.
- http, socket, rmi, multiplex, etc.).</para>
+ value is 'callbackServerProtocol') - key for the configuration when adding
+ a callback handler and internal callback server connector is created. The
+ value should be the transport protocol to be used. By default will use the
+ same protocol as being used by this client (e.g. http, socket, rmi,
+ multiplex, etc.).</para>
- <para><emphasis role="bold">CALLBACK_SERVER_HOST</emphasis> (actual
- value is 'callbackServerHost') - key for the configuration when adding a
+ <para><emphasis role="bold">CALLBACK_SERVER_HOST</emphasis> (actual value
+ is 'callbackServerHost') - key for the configuration when adding a
callback handler and internal callback server connector is created. The
value should be the host name to be used. By default will use the result
of calling InetAddress.getLocalHost().getHostAddress().</para>
- <para><emphasis role="bold">CALLBACK_SERVER_PORT</emphasis> (actual
- value is 'callbackServerPort') - key for the configuration when adding a
+ <para><emphasis role="bold">CALLBACK_SERVER_PORT</emphasis> (actual value
+ is 'callbackServerPort') - key for the configuration when adding a
callback handler and internal callback server connector is created. The
- value should be the port to be used. By default will find a random
- unused port.</para>
+ value should be the port to be used. By default will find a random unused
+ port.</para>
<para></para>
<para><emphasis role="bold">Bean properties (meaning have
getter/setter):</emphasis></para>
- <para><emphasis role="bold">SessionId</emphasis> -
- session id used when making invocations on server invokers. There is a
- default unique id automatically generated for each Client instance, so
- unless you have a good reason to set this, do not set this.</para>
+ <para><emphasis role="bold">SessionId</emphasis> - session id used when
+ making invocations on server invokers. There is a default unique id
+ automatically generated for each Client instance, so unless you have a
+ good reason to set this, do not set this.</para>
<para><emphasis role="bold">Subsystem</emphasis> - the subsystem being
used when routing invocation requests on the server side. Specifing a
@@ -4557,16 +4467,15 @@
using Client constructor.</para>
<para><emphasis role="bold">MaxNumberOfThreads</emphasis> - the maximum
- number of threads to use within client pool for one way invocations on
- the client side (meaning oneway invocation is handled by thread in this
- pool and user's call returns immediately) Default value is
+ number of threads to use within client pool for one way invocations on the
+ client side (meaning oneway invocation is handled by thread in this pool
+ and user's call returns immediately) Default value is
MAX_NUM_ONEWAY_THREADS (whose value is 10).</para>
- <para><emphasis role="bold">OnewayThreadPool</emphasis> - the thread
- pool being used for making one way invocations on the client side. If
- one has not been specifically set via configuration or call to set it,
- will always return instance of
- org.jboss.util.threadpool.BasicThreadPool.</para>
+ <para><emphasis role="bold">OnewayThreadPool</emphasis> - the thread pool
+ being used for making one way invocations on the client side. If one has
+ not been specifically set via configuration or call to set it, will always
+ return instance of org.jboss.util.threadpool.BasicThreadPool.</para>
<para><emphasis role="bold">SocketFactory</emphasis> - instance of
javax.net.SocketFactory, which can only be set on the Client before the
@@ -4574,13 +4483,13 @@
thrown.</para>
<para><emphasis role="bold">Marshaller</emphasis> - the marshaller
- implementation that should be used by the client invoker (transport).
- This overrides the client's default marshaller (or any set within
+ implementation that should be used by the client invoker (transport). This
+ overrides the client's default marshaller (or any set within
configuration).</para>
<para><emphasis role="bold">UnMarshaller</emphasis> - the unmarshaller
- implementation that should be used by the client invoker (transport).
- This overrides the client's default unmarshaller (or any set within
+ implementation that should be used by the client invoker (transport). This
+ overrides the client's default unmarshaller (or any set within
configuration).</para>
<para></para>
@@ -4588,64 +4497,61 @@
<bridgehead>org.jboss.remoting.Remoting</bridgehead>
<para><emphasis role="bold">CUSTOM_SERVER_SOCKET_FACTORY</emphasis>
- (actual value is 'customServerSocketFactory') - key for the
- configuration map passed to a Connector to indicate the server socket
- factory to be used. This will override the creation of any other socket
- factory. Value must be an instance of
- javax.net.ServerSocketFactory.</para>
-
- <para><emphasis role="bold">CUSTOM_SOCKET_FACTORY</emphasis> (actual
- value is 'customSocketFactory') - key for the configuration map passed
- to a Client to indicate the socket factory to be used. Value must be
- instance of javax.net.SocketFactory.</para>
+ (actual value is 'customServerSocketFactory') - key for the configuration
+ map passed to a Connector to indicate the server socket factory to be
+ used. This will override the creation of any other socket factory. Value
+ must be an instance of javax.net.ServerSocketFactory.</para>
+
+ <para><emphasis role="bold">CUSTOM_SOCKET_FACTORY</emphasis> (actual value
+ is 'customSocketFactory') - key for the configuration map passed to a
+ Client to indicate the socket factory to be used. Value must be instance
+ of javax.net.SocketFactory.</para>
<para><emphasis role="bold">SOCKET_FACTORY_NAME</emphasis> (actual value
- is 'socketFactory') - key for the configuration map passed to
- a Client to indicate the classname of the socket factory to be used.
- Value should be fully qualified classname of class that is an instance
- of javax.net.SocketFactory and has a void constructor. This property
- will not be used if CUSTOM_SOCKET_FACTORY is also set.</para>
+ is 'socketFactory') - key for the configuration map passed to a Client to
+ indicate the classname of the socket factory to be used. Value should be
+ fully qualified classname of class that is an instance of
+ javax.net.SocketFactory and has a void constructor. This property will not
+ be used if CUSTOM_SOCKET_FACTORY is also set.</para>
<para></para>
<bridgehead>org.jboss.remoting.ServerInvoker</bridgehead>
- <para><emphasis role="bold">MAX_NUM_ONEWAY_THREADS_KEY</emphasis>
- (actual value is 'maxNumThreadsOneway') - key for the maximum number of
- threads to be used in the thread pool for one way invocations (server
- side). This property is only used when the default oneway thread pool is
- used.</para>
+ <para><emphasis role="bold">MAX_NUM_ONEWAY_THREADS_KEY</emphasis> (actual
+ value is 'maxNumThreadsOneway') - key for the maximum number of threads to
+ be used in the thread pool for one way invocations (server side). This
+ property is only used when the default oneway thread pool is used.</para>
<para><emphasis role="bold">ONEWAY_THREAD_POOL_CLASS_KEY</emphasis>
(actual value is 'onewayThreadPool') - key for setting the setting the
oneway thread pool to use. The value used with this key will first be
- checked to see if is a JMX ObjectName and if so, try to look up
- associated mbean for the ObjectName given and cast to type
+ checked to see if is a JMX ObjectName and if so, try to look up associated
+ mbean for the ObjectName given and cast to type
org.jboss.util.threadpool.ThreadPoolMBean (via
MBeanServerInvocationHandler.newProxyInstance()). If the value is not a
JMX ObjectName, will assume is a fully qualified classname and load the
- coresponding class and create a new instance of it (which will require
- it to have a void constructor). The newly created instance will then be
- cast to type of org.jboss.util.threadpool.ThreadPool.</para>
+ coresponding class and create a new instance of it (which will require it
+ to have a void constructor). The newly created instance will then be cast
+ to type of org.jboss.util.threadpool.ThreadPool.</para>
<para><emphasis role="bold">SERVER_BIND_ADDRESS_KEY</emphasis> (actual
value is 'serverBindAddress') - key for setting the address the server
invoker should bind to. The value can be either host name or IP.</para>
- <para><emphasis role="bold">CLIENT_CONNECT_ADDRESS_KEY</emphasis>
- (actual value is 'clientConnectAddress') - key for setting the address
- the client invoker should connecto to. This should be used when client
- will be connecting to server from outside the server's network and the
- external address is different from that of the internal address the
- server invoker will bind to (e.g. using NAT to expose different external
- address). This will mostly be useful when client uses remoting detection
- to discover remoting servers. The value can be either host name or
- IP.</para>
-
- <para><emphasis role="bold">SERVER_BIND_PORT_KEY</emphasis> (actual
- value is 'serverBindPort') - key for setting the port the server invoker
- should bind to. If the value supplied is less than or equal to zero, the
- server invoker will randomly choose a free port to use.</para>
+ <para><emphasis role="bold">CLIENT_CONNECT_ADDRESS_KEY</emphasis> (actual
+ value is 'clientConnectAddress') - key for setting the address the client
+ invoker should connecto to. This should be used when client will be
+ connecting to server from outside the server's network and the external
+ address is different from that of the internal address the server invoker
+ will bind to (e.g. using NAT to expose different external address). This
+ will mostly be useful when client uses remoting detection to discover
+ remoting servers. The value can be either host name or IP.</para>
+
+ <para><emphasis role="bold">SERVER_BIND_PORT_KEY</emphasis> (actual value
+ is 'serverBindPort') - key for setting the port the server invoker should
+ bind to. If the value supplied is less than or equal to zero, the server
+ invoker will randomly choose a free port to use.</para>
<para><emphasis role="bold">CLIENT_CONNECT_PORT_KEY</emphasis> (actual
value is 'clientConnectPort') - key for setting the port the client
@@ -4663,21 +4569,20 @@
be used. This value will also be what is given to the client when it
initially queries server for leasing information.</para>
- <para><emphasis role="bold">TIMEOUT</emphasis> (actual value is
- 'timeout') - key for setting the timeout value (in milliseconds) for
- socket connections.</para>
-
- <para><emphasis role="bold">SERVER_SOCKET_FACTORY</emphasis> (actual
- value is 'serverSocketFactory') - key for setting the value for the
- server socket factory to be used by the server invoker. The value can be
- either a JMX Object name, in which case will lookup the mbean and create
- a proxy to it with type of
- org.jboss.remoting.security.ServerSocketFactoryMBean (via
+ <para><emphasis role="bold">TIMEOUT</emphasis> (actual value is 'timeout')
+ - key for setting the timeout value (in milliseconds) for socket
+ connections.</para>
+
+ <para><emphasis role="bold">SERVER_SOCKET_FACTORY</emphasis> (actual value
+ is 'serverSocketFactory') - key for setting the value for the server
+ socket factory to be used by the server invoker. The value can be either a
+ JMX Object name, in which case will lookup the mbean and create a proxy to
+ it with type of org.jboss.remoting.security.ServerSocketFactoryMBean (via
MBeanServerInvocationHandler.newProxyInstance()), or, if not a JMX
ObjectName, will assume is the fully qualified classname to the
- implementation to be used and will load the class and create a new instance
- of it (which requires it to have a void constructor). The instance will
- then be cast to type javax.net.ServerSocketFactory.</para>
+ implementation to be used and will load the class and create a new
+ instance of it (which requires it to have a void constructor). The
+ instance will then be cast to type javax.net.ServerSocketFactory.</para>
<para></para>
@@ -4686,20 +4591,20 @@
<para><emphasis role="bold">ServerSocketFactory</emphasis> -
implementation of javax.net.ServerSocketFactory to be used by the server
- invoker. This takes precedence over any other configuration for the
- server socket factory.</para>
+ invoker. This takes precedence over any other configuration for the server
+ socket factory.</para>
- <para><emphasis role="bold">Timeout</emphasis> - timeout (in
- milliseconds) for socket connection. If set after create() method
- called, this value will override value set by TIMEOUT key.</para>
+ <para><emphasis role="bold">Timeout</emphasis> - timeout (in milliseconds)
+ for socket connection. If set after create() method called, this value
+ will override value set by TIMEOUT key.</para>
<para><emphasis role="bold">LeasePeriod</emphasis> - the amount of time
(in milliseconds) that a client should renew its lease. If this value is
not set, the default of five seconds (see DEFAULT_CLIENT_LEASE_PERIOD),
- will be used. This value will also be what is given to the client when
- it initially queries server for leasing information. If set after
- create() method called, this value will override value set by
- CLIENT_LEASE_PERIOD key.</para>
+ will be used. This value will also be what is given to the client when it
+ initially queries server for leasing information. If set after create()
+ method called, this value will override value set by CLIENT_LEASE_PERIOD
+ key.</para>
<para><emphasis role="bold">MaxNumberOfOnewayThreads</emphasis> - the
maximum number of threads to be used in the thread pool for one way
@@ -4714,19 +4619,19 @@
<bridgehead>org.jboss.remoting.callback.CallbackPoller</bridgehead>
- <para><emphasis role="bold">CALLBACK_POLL_PERIOD</emphasis> (actual
- value is 'callbackPollPeriod') - key for setting the frequency (in
- milliseconds) in which Client's internal callback poller should poll
- server for waiting callbacks. This configuration is only necessary when
- using one of the following Client methods:</para>
+ <para><emphasis role="bold">CALLBACK_POLL_PERIOD</emphasis> (actual value
+ is 'callbackPollPeriod') - key for setting the frequency (in milliseconds)
+ in which Client's internal callback poller should poll server for waiting
+ callbacks. This configuration is only necessary when using one of the
+ following Client methods:</para>
<programlisting>public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject) throws Throwable
public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject, boolean serverToClient) throws Throwable</programlisting>
<para>and should be one of the entries in the metadata Map passed. This
will also only apply when the underlying transport is uni-directional
- (e.g. socket, http, rmi). Bi-directional transports will not need to
- poll. If this property is not set, the default (see
+ (e.g. socket, http, rmi). Bi-directional transports will not need to poll.
+ If this property is not set, the default (see
CallbackPoller.DEFAULT_POLL_PERIOD) value is five seconds.</para>
<para></para>
@@ -4736,10 +4641,9 @@
<para><emphasis role="bold">FILE_PATH_KEY</emphasis> (actual value is
'StoreFilePath') - key for setting the directory in which to write the
callback objects. The default value is the property value of
- 'jboss.server.data.dir' and if this is not set, then will be 'data'.
- Will then append 'remoting' and the callback client's session id. An
- example would be
- 'data\remoting\5c4o05l-9jijyx-e5b6xyph-1-e5b6xyph-2'.</para>
+ 'jboss.server.data.dir' and if this is not set, then will be 'data'. Will
+ then append 'remoting' and the callback client's session id. An example
+ would be 'data\remoting\5c4o05l-9jijyx-e5b6xyph-1-e5b6xyph-2'.</para>
<para><emphasis role="bold">FILE_SUFFIX_KEY</emphasis> (actual value is
'StoreFileSuffix') - key for setting the file suffix to use for the
@@ -4750,8 +4654,8 @@
<bridgehead>org.jboss.remoting.callback.DefaultCallbackErrorHandler</bridgehead>
<para><emphasis role="bold">CALLBACK_ERRORS_ALLOWED</emphasis> (actual
- value is 'callbackErrorsAllowed') - key for setting the number of
- callback exceptions that will be allowed when calling on
+ value is 'callbackErrorsAllowed') - key for setting the number of callback
+ exceptions that will be allowed when calling on
org.jboss.remoting.callback.InvokerCallbackHandler.handleCallback(Callback
callback) before cleaning up the callback listener. This only applies to
push callback. The default if this property is not set is five.</para>
@@ -4760,28 +4664,28 @@
<bridgehead>org.jboss.remoting.callback.ServerInvokerCallbackHandler</bridgehead>
- <para><emphasis role="bold">CALLBACK_STORE_KEY</emphasis> (actual value
- is 'callbackStore') - key for specifing the callback store to be used.
- The value can be either a JMX ObjectName or a fully qualified class
- name; either way, must implement org.jboss.remoting.SerializableStore.
- If using class name, the callback store implementation must have a void
+ <para><emphasis role="bold">CALLBACK_STORE_KEY</emphasis> (actual value is
+ 'callbackStore') - key for specifing the callback store to be used. The
+ value can be either a JMX ObjectName or a fully qualified class name;
+ either way, must implement org.jboss.remoting.SerializableStore. If using
+ class name, the callback store implementation must have a void
constructor. The default is to use the
org.jboss.remoting.callback.NullCallbackStore.</para>
- <para><emphasis role="bold">CALLBACK_ERROR_HANDLER_KEY</emphasis>
- (actual value is 'callbackErrorHandler') - key for specifing the
- callback exception handler to be used. The value can be either a JMX
- ObjectName or a fully qualified class name, either way, must implement
- org.jboss.remoting.callback.CallbackErrorHandler. If using class name,
- the callback exception handler implementation must have a void
- constructor. The default is to use
+ <para><emphasis role="bold">CALLBACK_ERROR_HANDLER_KEY</emphasis> (actual
+ value is 'callbackErrorHandler') - key for specifing the callback
+ exception handler to be used. The value can be either a JMX ObjectName or
+ a fully qualified class name, either way, must implement
+ org.jboss.remoting.callback.CallbackErrorHandler. If using class name, the
+ callback exception handler implementation must have a void constructor.
+ The default is to use
org.jboss.remoting.callback.DefaultCallbackErrorHandler.</para>
- <para><emphasis role="bold">CALLBACK_MEM_CEILING</emphasis> (actual
- value is 'callbackMemCeiling') - key for specifying the percentage of
- free memory available before callbacks will be persisted. If the memory
- heap allocated has reached its maximum value and the percent of free
- memory available is less than the callbackMemCeiling, this will trigger
+ <para><emphasis role="bold">CALLBACK_MEM_CEILING</emphasis> (actual value
+ is 'callbackMemCeiling') - key for specifying the percentage of free
+ memory available before callbacks will be persisted. If the memory heap
+ allocated has reached its maximum value and the percent of free memory
+ available is less than the callbackMemCeiling, this will trigger
persisting of the callback message. The default value is 20.</para>
<para></para>
@@ -4791,9 +4695,8 @@
<para><emphasis role="bold">Bean properties (meaning have
getter/setter):</emphasis></para>
- <para><emphasis
- role="bold">SubContextName</emphasis> - sub context name under which
- detection messages will be bound and looked up.</para>
+ <para><emphasis role="bold">SubContextName</emphasis> - sub context name
+ under which detection messages will be bound and looked up.</para>
<para></para>
@@ -4830,9 +4733,9 @@
...
</programlisting>
- <para> <emphasis role="bold">PATH</emphasis> (actual value is 'Path') -
- key for getting the path from the url request from the calling client.
- This will be populated within the Map returned from call to
+ <para><emphasis role="bold">PATH</emphasis> (actual value is 'Path') - key
+ for getting the path from the url request from the calling client. This
+ will be populated within the Map returned from call to
org.jboss.remoting.InvocationRequest.getRequestPayload() within a
org.jboss.remoting.ServerInvocationHandler implementation. For
example:</para>
@@ -4845,17 +4748,17 @@
</programlisting>
<para><emphasis role="bold">HTTPVERSION</emphasis> (actual value is
- 'HttpVersion') - key for getting the HTTP version from the calling
- client request (e.g. HTTP/1.1).</para>
+ 'HttpVersion') - key for getting the HTTP version from the calling client
+ request (e.g. HTTP/1.1).</para>
<para></para>
<para></para>
<para><emphasis role="bold">RESPONSE_CODE</emphasis> (actual value is
- 'ResponseCode') - key for getting and setting the HTTP response code.
- Will be used as key to get the response code from metadata Map passed to
- the Client's invoke() method after the invocation has been made. For
+ 'ResponseCode') - key for getting and setting the HTTP response code. Will
+ be used as key to get the response code from metadata Map passed to the
+ Client's invoke() method after the invocation has been made. For
example:</para>
<programlisting>Map metadata = new HashMap();
@@ -4872,11 +4775,11 @@
responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE, new Integer(202));
</programlisting>
- <para><emphasis role="bold">RESPONSE_CODE_MESSAGE</emphasis> (actual
- value is 'ResponseCodeMessage') - key for getting and setting the HTTP
- response code message. Will be used as the key to get the response code
- message from metadata Map passed to the Client's invoke() method after
- the invocation has been made. For example:</para>
+ <para><emphasis role="bold">RESPONSE_CODE_MESSAGE</emphasis> (actual value
+ is 'ResponseCodeMessage') - key for getting and setting the HTTP response
+ code message. Will be used as the key to get the response code message
+ from metadata Map passed to the Client's invoke() method after the
+ invocation has been made. For example:</para>
<programlisting>Map metadata = new HashMap();
Object response = remotingClient.invoke(myPayloadObject, metadata);
@@ -4892,49 +4795,48 @@
responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, "Custom response code and message from remoting server");
</programlisting>
- <para><emphasis role="bold">NO_THROW_ON_ERROR</emphasis> (actual value
- is 'NoThrowOnError') - key indicating if http client invoker (for
- transports http, https, servlet, and sslservlet) should throw an
- exception if the server response code is equal to or greater than 400.
- Unless set to true, the client invoker will by default throw either the
- exception that originated on the server (if using remoting server) or
- throw a org.jboss.remoting.transport.http.WebServerError, whose message
- will be the error html returned from the web server.</para>
+ <para><emphasis role="bold">NO_THROW_ON_ERROR</emphasis> (actual value is
+ 'NoThrowOnError') - key indicating if http client invoker (for transports
+ http, https, servlet, and sslservlet) should throw an exception if the
+ server response code is equal to or greater than 400. Unless set to true,
+ the client invoker will by default throw either the exception that
+ originated on the server (if using remoting server) or throw a
+ org.jboss.remoting.transport.http.WebServerError, whose message will be
+ the error html returned from the web server.</para>
<para></para>
- <para>For every http client request made from remoting client, a
- remoting version and remoting specific user agent will be set as a
- request property. The request property key for the remoting version will
- be 'JBoss-Remoting-Version' and the value will be set based on return
- from call to Version.getDefaultVersion(). The 'User-Agent' request
- property value will be set to the evaluation of '"JBossRemoting - " +
+ <para>For every http client request made from remoting client, a remoting
+ version and remoting specific user agent will be set as a request
+ property. The request property key for the remoting version will be
+ 'JBoss-Remoting-Version' and the value will be set based on return from
+ call to Version.getDefaultVersion(). The 'User-Agent' request property
+ value will be set to the evaluation of '"JBossRemoting - " +
Version.VERSION'.</para>
<para></para>
<bridgehead>org.jboss.remoting.transport.http.ssl.HTTPSClientInvoker</bridgehead>
- <para><emphasis role="bold">IGNORE_HTTPS_HOST</emphasis> (actual value
- is 'org.jboss.security.ignoreHttpsHost') - key indicating if the http
- client invoker (for transports https and sslservlet) should ignore host
- name verification (meaning will not check for URL's hostname and
- server's identification hostname mismatch during handshaking). By
- default, if this not set to true, standard hostname verification will be
- performed.</para>
-
- <para><emphasis role="bold">HOSTNAME_VERIFIER</emphasis> (actual value
- is 'hostnameVerifier') - key indicating the hostname verifier that
- should be used by the http client invoker. The value should be the fully
- qualified classname of class that implements
- javax.net.ssl.HostnameVerifier and has a void constructor.</para>
+ <para><emphasis role="bold">IGNORE_HTTPS_HOST</emphasis> (actual value is
+ 'org.jboss.security.ignoreHttpsHost') - key indicating if the http client
+ invoker (for transports https and sslservlet) should ignore host name
+ verification (meaning will not check for URL's hostname and server's
+ identification hostname mismatch during handshaking). By default, if this
+ not set to true, standard hostname verification will be performed.</para>
+
+ <para><emphasis role="bold">HOSTNAME_VERIFIER</emphasis> (actual value is
+ 'hostnameVerifier') - key indicating the hostname verifier that should be
+ used by the http client invoker. The value should be the fully qualified
+ classname of class that implements javax.net.ssl.HostnameVerifier and has
+ a void constructor.</para>
<para></para>
<bridgehead>org.jboss.remoting.transport.rmi.RMIServerInvoker</bridgehead>
- <para><emphasis role="bold">REGISTRY_PORT_KEY</emphasis> (actual value
- is 'registryPort') - the port on which to create the RMI registry. The
+ <para><emphasis role="bold">REGISTRY_PORT_KEY</emphasis> (actual value is
+ 'registryPort') - 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>
@@ -4944,15 +4846,15 @@
<para><emphasis role="bold">TCP_NODELAY_FLAG</emphasis> (actual value is
'enableTcpNoDelay') - can be either true or false and will indicate if
- client socket should have TCP_NODELAY turned on or off. TCP_NODELAY is
- for a specific purpose; to disable the Nagle buffering algorithm. It
- should only be set for applications that send frequent small bursts of
+ client socket should have TCP_NODELAY turned on or off. TCP_NODELAY is for
+ a specific purpose; to disable the Nagle buffering algorithm. It should
+ only be set for applications that send frequent small bursts of
information without getting an immediate response; where timely delivery
of data is required (the canonical example is mouse movements). The
default is false.</para>
- <para><emphasis role="bold">MAX_POOL_SIZE_FLAG</emphasis> (actual value
- is 'clientMaxPoolSize') - the client side maximum number of threads. The
+ <para><emphasis role="bold">MAX_POOL_SIZE_FLAG</emphasis> (actual value is
+ 'clientMaxPoolSize') - the client side maximum number of threads. The
default is 50.</para>
<para><emphasis role="bold">CLIENT_SOCKET_CLASS_FLAG</emphasis> (actual
@@ -4967,14 +4869,14 @@
<bridgehead>org.jboss.remoting.transport.socket.SocketServerInvoker</bridgehead>
- <para><emphasis role="bold">CHECK_CONNECTION_KEY</emphasis> (actual
- value is 'socket.check_connection') - key for indicating if socket
- invoker should continue to keep socket connection between client and
- server open after invocations by sending a ping on the connection before
- being re-used. The default for this is false.</para>
+ <para><emphasis role="bold">CHECK_CONNECTION_KEY</emphasis> (actual value
+ is 'socket.check_connection') - key for indicating if socket invoker
+ should continue to keep socket connection between client and server open
+ after invocations by sending a ping on the connection before being
+ re-used. The default for this is false.</para>
<para><emphasis role="bold">SERVER_SOCKET_CLASS_FLAG</emphasis> (actual
value is 'serverSocketClass') - specifies the fully qualified class name
for the custom SocketWrapper implementation to use on the server.</para>
</section>
- </chapter>
\ No newline at end of file
+</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list