[jboss-cvs] JBossRemoting/docs/guide/en ...
Tom Elrod
tom.elrod at jboss.com
Mon Jul 31 01:03:42 EDT 2006
User: telrod
Date: 06/07/31 01:03:42
Modified: docs/guide/en chap16.xml chap3.xml chap5.xml
chap6.xml chap7.xml chap8.xml master.xml
Log:
JBREM-559 - updated remoting doc for some changes in 2.0.0.CR1
Revision Changes Path
1.2 +261 -31 JBossRemoting/docs/guide/en/chap16.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap16.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap16.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- chap16.xml 30 Jul 2006 06:56:36 -0000 1.1
+++ chap16.xml 31 Jul 2006 05:03:42 -0000 1.2
@@ -17,75 +17,304 @@
<para></para>
- <para>Release Notes - JBoss Remoting - Version 1.4.1 final</para>
+ <para>Release Notes - JBoss Remoting - Version 2.0.0.Beta2 (Boon) </para>
- <para>** Feature Request </para>
+ <para>** Bug </para>
- <para>* [JBREM-310] - Ability to turn connection checking off </para>
+ <para>* [JBREM-304] -
+ org.jboss.test.remoting.transport.multiplex.MultiplexInvokerTestCase(java_serialization)
+ fails </para>
- <para>* [JBREM-325] - move IMarshalledValue from jboss-commons to
- jboss-remoting.jar </para>
+ <para>* [JBREM-371] - HTTPClientInvoker does not pass an
+ ObjectOutputStream to the marshaller </para>
- <para>** Bug </para>
+ <para>* [JBREM-405] - NPE when calling stop() twice on MulticastDetector
+ </para>
- <para>* [JBREM-313] - client lease does not work if client and server in
- same VM (using local invoker) </para>
+ <para>* [JBREM-406] - StringIndexOutOfBoundsException in InvokerLocator
+ </para>
+
+ <para>* [JBREM-408] - client lease updates broken on server side </para>
+
+ <para>* [JBREM-409] - Invocations fail when the pool exhausts and under
+ heavy load </para>
+
+ <para>* [JBREM-414] - JNDI detection failing </para>
+
+ <para>* [JBREM-418] - ObjectInputStreamWithClassLoader can't handle
+ primitives </para>
+
+ <para>* [JBREM-426] - keyStorePath and keyStorePassword being printed to
+ standard out </para>
+
+ <para>* [JBREM-432] - TransporterClient missing serialVersionUID </para>
+
+ <para>* [JBREM-440] - CallbackStore.getNext() won't necessarily get the
+ oldest one </para>
+
+ <para>* [JBREM-441] - DefaultCallbackErrorHandler.setConfig needs to avoid
+ NPE </para>
- <para>* [JBREM-317] - HTTPClientInvoker conect sends gratuitous POST
+ <para>* [JBREM-449] - Failure Information lost in RemotingSSLSocketFactory
</para>
- <para>* [JBREM-341] - Client ping interval must be lease than lease period
+ <para>* [JBREM-450] - ClassNotFoundException for class array type during
+ deserialization </para>
+
+ <para>* [JBREM-464] - ssl socket invoker not using ssl server socket
+ factory </para>
+
+ <para>* [JBREM-467] - NPE when calling Client.removeConnectionListener()
</para>
- <para>* [JBREM-343] - Exceptions on connection closing </para>
+ <para>* [JBREM-470] - javax.net.ssl.SSLException: No available certificate
+ corresponds to the SSL cipher suites </para>
- <para>* [JBREM-345] - problem using client address and port </para>
+ <para>* [JBREM-472] - Misspelled serialization type generates obscure NPE
+ </para>
- <para>* [JBREM-346] - fix ConcurrentModificationException in cleanup of
- MultiplexServerInvoker </para>
+ <para>* [JBREM-479] - ClientConfigurationMapTestCase failure </para>
+
+ <para>* [JBREM-482] - client invoker configuration lost after first time
+ invoker is created </para>
+
+ <para>** Feature Request </para>
+
+ <para>* [JBREM-312] - make TransporterClient so can be sent over network
+ as dynamic proxy </para>
+
+ <para>* [JBREM-363] - make callbacks easier with richer API for
+ registering for callbacks </para>
+
+ <para>* [JBREM-411] - Add chunked streaming support to the HTTP invoker
+ </para>
+
+ <para>* [JBREM-413] - Transporter server should allow multiple pojo
+ targets </para>
+
+ <para>* [JBREM-422] - Add plugable load balancing policy to transporter
+ client </para>
+
+ <para>* [JBREM-425] - Add support for setting the HTTP invoker content
+ encoding that is accepted </para>
+
+ <para>* [JBREM-431] - transporter server should automatically expose all
+ interfaces implemented as subsystems </para>
- <para>* [JBREM-350] - ConcurrentModificationException in InvokerRegistry
+ <para>* [JBREM-439] - StreamInvocationHandler.handleStream should throw
+ Throwable for consistency </para>
+
+ <para>* [JBREM-469] - Enable HTTP polling </para>
+
+ <para>* [JBREM-471] - need better InvokerLocator.equals() implementation
</para>
- <para>* [JBREM-361] - Race condition in invoking on Client </para>
+ <para>* [JBREM-481] - Changing StringUtilBuffer creation on
+ JBossSerialization </para>
<para>** Task </para>
- <para>* [JBREM-2] - sample-bindings.xml does not have entry for remoting
+ <para>* [JBREM-299] - MultiplexInvokerTestCase failure </para>
+
+ <para>* [JBREM-314] - need
+ org.jboss.test.pooled.test.SSLSocketsUnitTestCase for remoting </para>
+
+ <para>* [JBREM-328] - change lease ping to be HEAD instead of POST for
+ http transport </para>
+
+ <para>* [JBREM-362] - convert Connector to be standard mbean instead of
+ xmbean </para>
+
+ <para>* [JBREM-365] - set default user agent header in http client invoker
+ </para>
+
+ <para>* [JBREM-366] - clean up client invoker tracking within
+ InvokerRegistry </para>
+
+ <para>* [JBREM-367] - set live server socket factory on Connector </para>
+
+ <para>* [JBREM-370] - add changes from 1.4.1 release to master.xml doc
+ </para>
+
+ <para>* [JBREM-377] - need to convert ConnectionValidator to use
+ TimerQueue </para>
+
+ <para>* [JBREM-379] - need to update jboss-serialization jar being used
</para>
- <para>* [JBREM-220] - clean up remoting wiki </para>
+ <para>* [JBREM-380] - change ConnectionValidator to only notify once of
+ failure </para>
+
+ <para>* [JBREM-382] - disable lease ping for local invoker </para>
+
+ <para>* [JBREM-415] - sync bug fixes with pooled invoker and socket
+ invoker </para>
+
+ <para>* [JBREM-420] - JNDI Detector should not need a connector when
+ running in client mode </para>
+
+ <para>* [JBREM-421] - remote stream handler api inconsistent with regular
+ handler </para>
+
+ <para>* [JBREM-436] - Extend MultiplexingInputStream with readInt() to
+ avoid creating a MultiplexingDataInputStream in VirtualSocket.connect()
+ and elsewhere. </para>
+
+ <para>* [JBREM-437] - Eliminate "verify connect" phase from virtual socket
+ connection protocol. </para>
+
+ <para>* [JBREM-443] - add HandshakeCompletedListener support to ssl
+ multiplex </para>
+
+ <para>* [JBREM-451] - Send the pre-release jar to the messaging team for
+ testing </para>
+
+ <para>* [JBREM-455] - checking of socket connection is not really needed
+ </para>
+
+ <para>* [JBREM-456] - block callback handling when callback store full
+ </para>
+
+ <para>* [JBREM-460] - createSocket() in SSLSocketClientInvoker and
+ SSLMultiplexClientInvoker should not assume SocketFactory has been
+ created. </para>
+
+ <para>* [JBREM-465] - property setting on the client from locator
+ parameters and config map </para>
+
+ <para>* [JBREM-476] - make externalization of Client match original
+ instance state </para>
+
+ <para>* [JBREM-478] - fix local client invoker handling of disconnected
+ server invokers </para>
+
+ <para>* [JBREM-483] - remove LocalLeaseTestCase </para>
+
+ <para>* [JBREM-485] - use the ClientInvokerHolder to contain the reference
+ counting instead of having to use clientInvokerCounter </para>
+
+ <para>* [JBREM-486] - Fix ConcurrentModificationException in
+ org.jboss.test.remoting.transport.mock.MockServerInvocationHandler</para>
+
+ <para></para>
+
+ <para>Release Notes - JBoss Remoting - Version 2.0.0.Beta1</para>
+
+ <para>** Bug</para>
+
+ <para>* [JBREM-372] - memory leak on server side leasing</para>
+
+ <para>* [JBREM-376] - problem versioning with not using connection
+ checking</para>
+
+ <para>* [JBREM-378] - client connection checking not working</para>
+
+ <para>** Feature Request</para>
+
+ <para>* [JBREM-340] - Strong version compatibility guarantee</para>
+
+ <para>** Task</para>
+
+ <para>* [JBREM-374] - single thread the leasing timer</para>
+
+ <para></para>
+
+ <para>Release Notes - JBoss Remoting - Version 1.4.4.GA </para>
+
+ <para>** Bug</para>
+
+ <para> * [JBREM-426] - keyStorePath and keyStorePassword being printed to
+ standard out</para>
+
+ <para></para>
+
+ <para>Release Notes - JBoss Remoting - Version 1.4.3.GA </para>
+
+ <para>** Bug </para>
+
+ <para>* [JBREM-418] - ObjectInputStreamWithClassLoader can't handle
+ primitives</para>
+
+ <para></para>
+
+ <para>Release Notes - JBoss Remoting - Version 1.4.2 final</para>
+
+ <para>** Feature Request </para>
+
+ <para>* [JBREM-429] - Create JBossSerialization MarshalledValue more
+ optimized for RemoteCalls</para>
+
+ <para></para>
+
+ <para>Release Notes - JBoss Remoting - Version 1.4.1 final</para>
+
+ <para>** Feature Request</para>
+
+ <para>* [JBREM-310] - Ability to turn connection checking off</para>
+
+ <para>* [JBREM-325] - move IMarshalledValue from jboss-commons to
+ jboss-remoting.jar</para>
+
+ <para>** Bug</para>
+
+ <para>* [JBREM-313] - client lease does not work if client and server in
+ same VM (using local invoker)</para>
+
+ <para>* [JBREM-317] - HTTPClientInvoker conect sends gratuitous
+ POST</para>
+
+ <para>* [JBREM-341] - Client ping interval must be lease than lease
+ period</para>
+
+ <para>* [JBREM-343] - Exceptions on connection closing</para>
+
+ <para>* [JBREM-345] - problem using client address and port</para>
+
+ <para>* [JBREM-346] - fix ConcurrentModificationException in cleanup of
+ MultiplexServerInvoker</para>
+
+ <para>* [JBREM-350] - ConcurrentModificationException in
+ InvokerRegistry</para>
+
+ <para>* [JBREM-361] - Race condition in invoking on Client</para>
+
+ <para>** Task</para>
+
+ <para>* [JBREM-2] - sample-bindings.xml does not have entry for
+ remoting</para>
+
+ <para>* [JBREM-220] - clean up remoting wiki</para>
<para>* [JBREM-316] - Maintain tomcat originated code under the ASF
- license. </para>
+ license.</para>
<para>* [JBREM-319] - ability to inject socket factory by classname or
- instance in all remoting transports </para>
+ instance in all remoting transports</para>
- <para>* [JBREM-323] - client lease config changes </para>
+ <para>* [JBREM-323] - client lease config changes</para>
- <para>* [JBREM-329] - create global transport config for timeout </para>
+ <para>* [JBREM-329] - create global transport config for timeout</para>
<para>* [JBREM-330] - create socket server factory based off of
- configuration properties </para>
+ configuration properties</para>
<para>* [JBREM-335] - Client.invoke() should pass configuration map to
- InvokerRegistry.createClientInvoker(). </para>
+ InvokerRegistry.createClientInvoker().</para>
<para>* [JBREM-336] - InvokerRegistry doesn't purge InvokerLocators from
- static Set registeredLocators. </para>
+ static Set registeredLocators.</para>
<para>* [JBREM-337] - PortUtil.findFreePort() should return ports only
- between 1024 and 65535. </para>
+ between 1024 and 65535.</para>
- <para>* [JBREM-342] - Thread usage for timers and lease functionality
- </para>
+ <para>* [JBREM-342] - Thread usage for timers and lease
+ functionality</para>
<para>* [JBREM-354] - ServerInvokerCallbackHandler should make its
- subsystem accessible. </para>
+ subsystem accessible.</para>
- <para>* [JBREM-356] - ServerInvoker should destroy its callback handlers.
- </para>
+ <para>* [JBREM-356] - ServerInvoker should destroy its callback
+ handlers.</para>
<para>* [JBREM-359] - MultiplexInvokerConfigTestCase should execute
MultiplexInvokerConfigTestServer instead of
@@ -620,4 +849,5 @@
required</para>
<para></para>
+
</chapter>
\ No newline at end of file
1.2 +267 -144 JBossRemoting/docs/guide/en/chap3.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap3.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap3.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- chap3.xml 30 Jul 2006 06:56:36 -0000 1.1
+++ chap3.xml 31 Jul 2006 05:03:42 -0000 1.2
@@ -1,4 +1,5 @@
- <chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
<title>JBoss Remoting Components</title>
<para>This section covers a few of the main components exposed within the
@@ -6,36 +7,59 @@
<para><emphasis role="bold">org.jboss.remoting.Client</emphasis> – is the
class the user will create and call on from the client side. This is the
- main entry point for making all invocations and adding a callback
- listener. The Client class requires only the InvokerLocator for the server
- you wish to call upon and that you call connect before use and disconnect
- after use (which is technically only required for stateful transports and
- when client leasing is turned on, but good to call in either case).</para>
+ main entry point for making all invocations and adding a callback listener.
+ The Client class requires only the InvokerLocator for the server you wish to
+ call upon and that you call connect before use and disconnect after use
+ (which is technically only required for stateful transports and when client
+ leasing is turned on, but good to call in either case).</para>
<para><emphasis role="bold">org.jboss.remoting.InvokerLocator</emphasis> –
is a class, which can be described as a string URI, for identifying a
- particular JBossRemoting server JVM and transport protocol. For example,
- the InvokerLocator string socket://192.168.10.1:8080 describes a TCP/IP
+ particular JBossRemoting server JVM and transport protocol. For example, the
+ InvokerLocator string socket://192.168.10.1:8080 describes a TCP/IP
Socket-based transport, which is listening on port 8080 of the IP address,
192.168.10.1. Using the string URI, or the InvokerLocator object,
JBossRemoting can make a client connection to the remote JBoss server. The
format of the locator string is the same as the URI type:
- <code>[transport]://[host]:<port>/path/?<parameter=value>&<parameter=value></code>
- A few important points to note about the InvokerLocator. The string
+ <code>[transport]://[host]:<port>/path/?<parameter=value>&<parameter=value></code></para>
+
+ <para>A few important points to note about the InvokerLocator. The string
representation used to construct the InvokerLocator may be modified after
- creation. This can occur if the host supplied is 0.0.0.0, in which case
- the InvokerLocator will attempt to replace it with the value of the local
- host name. This can also occur if the port specified is less than zero or
- not specified at all (in which case remoting will select a random port to
+ creation. This can occur if the host supplied is 0.0.0.0, in which case the
+ InvokerLocator will attempt to replace it with the value of the local host
+ name. This can also occur if the port specified is less than zero or not
+ specified at all (in which case remoting will select a random port to
use).</para>
+ <para>The InvokerLocator will accept host name as is and will not
+ automatically convert to ip address (since 2.0.0 release). This means
+ equality for locators is based on if is host name or ip, but does not
+ resolve one to the other. The following is a list of how the InvokerLocator
+ will evaluate equality between two instances based on the locator uri string
+ passed: </para>
+
+ <para>InvokerLocator.equals(): </para>
+
+ <para>http://localhost:1234/services/uri:Test & http://localhost:1234 =
+ false </para>
+
+ <para>http://localhost:1234/services/uri:Test & http://127.0.0.1:1234 =
+ false </para>
+
+ <para>InvokerLocator.isSameEndpoint(): </para>
+
+ <para>http://localhost:1234/services/uri:Test & http://localhost:1234 =
+ true </para>
+
+ <para>http://localhost:1234/services/uri:Test & http://127.0.0.1:1234 =
+ false</para>
+
<para><emphasis
- role="bold">org.jboss.remoting.transport.Connector</emphasis> - is an
- MBean that loads a particular ServerInvoker implementation for a given
- transport subsystem and one or more ServerInvocationHandler
- implementations that handle Subsystem invocations on the remote server
- JVM. The Connector is the main user touch point for configuring and
- managing a remoting server.</para>
+ role="bold">org.jboss.remoting.transport.Connector</emphasis> - is an MBean
+ that loads a particular ServerInvoker implementation for a given transport
+ subsystem and one or more ServerInvocationHandler implementations that
+ handle Subsystem invocations on the remote server JVM. The Connector is the
+ main user touch point for configuring and managing a remoting server.</para>
<para><emphasis
role="bold">org.jboss.remoting.ServerInvocationHandler</emphasis> – is the
@@ -44,12 +68,11 @@
implementation will also be required to keep track of callback listeners
that have been registered by the client as well.</para>
- <para><emphasis role="bold">org.jboss.remoting.InvocationRequest
- </emphasis> – is the actual remoting payload of an invocation. This class
- wraps the caller’s request and provides extra information about the
- invocation, such as the caller’s session id and its callback locator (if
- one exists). This will be object passed to the
- ServerInvocationHandler.</para>
+ <para><emphasis role="bold">org.jboss.remoting.InvocationRequest </emphasis>
+ – is the actual remoting payload of an invocation. This class wraps the
+ caller’s request and provides extra information about the invocation, such
+ as the caller’s session id and its callback locator (if one exists). This
+ will be object passed to the ServerInvocationHandler.</para>
<para><emphasis
role="bold">org.jboss.remoting.stream.StreamInvocationHandler</emphasis> –
@@ -57,23 +80,22 @@
expecting to receive invocations containing an input stream.</para>
<para><emphasis
- role="bold">org.jboss.remoting.callback.InvokerCallbackHandler</emphasis>
- – the interface for any callback listener to implement. Upon receiving
- callbacks, the remoting client will call on this interface if registered
- as a listener.</para>
-
- <para><emphasis
- role="bold">org.jboss.remoting.callback.Callback</emphasis> – the callback
- object passed to the InvokerCallbackHandler. It contains the callback
- payload supplied by the invocation handler, any handle object specified
- when callback listener was registered, and the locator from which the
- callback came.</para>
-
- <para><emphasis
- role="bold">org.jboss.remoting.network.NetworkRegistry</emphasis> – this
- is a singleton class that will keep track of remoting servers as new ones
- are detected and dead ones are detected. Upon a change in the registry,
- the NetworkRegistry fires a NetworkNotification.</para>
+ role="bold">org.jboss.remoting.callback.InvokerCallbackHandler</emphasis> –
+ the interface for any callback listener to implement. Upon receiving
+ callbacks, the remoting client will call on this interface if registered as
+ a listener.</para>
+
+ <para><emphasis role="bold">org.jboss.remoting.callback.Callback</emphasis>
+ – the callback object passed to the InvokerCallbackHandler. It contains the
+ callback payload supplied by the invocation handler, any handle object
+ specified when callback listener was registered, and the locator from which
+ the callback came.</para>
+
+ <para><emphasis
+ role="bold">org.jboss.remoting.network.NetworkRegistry</emphasis> – this is
+ a singleton class that will keep track of remoting servers as new ones are
+ detected and dead ones are detected. Upon a change in the registry, the
+ NetworkRegistry fires a NetworkNotification.</para>
<para><emphasis role="bold">org.jboss.remoting.network.NetworkNotification
</emphasis> – a JMX Notification containing information about a remoting
@@ -88,26 +110,26 @@
<para><emphasis role="bold">org.jboss.remoting.ident.Identity</emphasis> –
is one of the main components remoting uses during discovery to identify
- remoting server instances (is actually the way it guarantees uniqueness).
- If have two remoting servers running on the same server, they can be
- uniquely identified. The reason the identity is persisted (currently only
- able to do this to the file system) is so if a server crashes and then
- restarts, can identify it when it restarts as the one that crashed
- (instead of being a completely new instance that is being started). This
- may be important from a monitoring point as would want to know that the
- crashed server is back online.</para>
+ remoting server instances (is actually the way it guarantees uniqueness). If
+ have two remoting servers running on the same server, they can be uniquely
+ identified. The reason the identity is persisted (currently only able to do
+ this to the file system) is so if a server crashes and then restarts, can
+ identify it when it restarts as the one that crashed (instead of being a
+ completely new instance that is being started). This may be important from a
+ monitoring point as would want to know that the crashed server is back
+ online.</para>
<para>When creating the identity to be presisted, remoting will first look
- to see if a system property for 'jboss.identity' has been set already. If
- it has, will use that one. If not, will get the value for the
- 'ServerDataDir' attribute of the 'jboss.system:type=ServerConfig' mbean.
- If can retrieve this value, will just this as the directory to write out
- the 'jboss.identity' file. If not, will look to see if a system property
- has been set for 'jboss.identity.dir'. If it has, will use this as the
- directory to write the 'jboss.identity' file to, otherwise, will default
- to '.'. If for some reason the file can not be written to, will throw a
- RuntimeException, which will cause the detector to error during startup.
- For more details on how and where the identity is persisted, can refer to
+ to see if a system property for 'jboss.identity' has been set already. If it
+ has, will use that one. If not, will get the value for the 'ServerDataDir'
+ attribute of the 'jboss.system:type=ServerConfig' mbean. If can retrieve
+ this value, will just this as the directory to write out the
+ 'jboss.identity' file. If not, will look to see if a system property has
+ been set for 'jboss.identity.dir'. If it has, will use this as the directory
+ to write the 'jboss.identity' file to, otherwise, will default to '.'. If
+ for some reason the file can not be written to, will throw a
+ RuntimeException, which will cause the detector to error during startup. For
+ more details on how and where the identity is persisted, can refer to
org.jboss.remoting.ident.Identity.createId().</para>
<para><emphasis
@@ -119,26 +141,127 @@
</emphasis> – is the detector implementation that registers its Detection
message to other detectors in a specified JNDI server.</para>
- <para>There are a few other components that are not represented as a
- class, but important to understand.</para>
+ <para>There are a few other components that are not represented as a class,
+ but important to understand.</para>
<para><emphasis role="bold">Subsystem</emphasis> – a sub-system is an
- identifier for what higher level system an invocation handler is
- associated with. The sub-system is declared as any String value. The
- reason for identifying sub-systems is that a remoting Connector’s server
- invoker may handle invocations for multiple invocation handlers, which
- need to be routed based on sub-system. For example, a particular socket
- based server invoker may handle invocations for both customer processing
- and order processing. The client making the invocation would then need to
- identify the intended sub-system to handle the invocation based on this
- identifier. If only one handler is added to a Connector, the client does
- not need to specify a sub-system when making an invocation.</para>
+ identifier for what higher level system an invocation handler is associated
+ with. The sub-system is declared as any String value. The reason for
+ identifying sub-systems is that a remoting Connector’s server invoker may
+ handle invocations for multiple invocation handlers, which need to be routed
+ based on sub-system. For example, a particular socket based server invoker
+ may handle invocations for both customer processing and order processing.
+ The client making the invocation would then need to identify the intended
+ sub-system to handle the invocation based on this identifier. If only one
+ handler is added to a Connector, the client does not need to specify a
+ sub-system when making an invocation.</para>
<para><emphasis role="bold">Domain</emphasis> – a logical name for a group
- to which a remoting server can belong. The detectors can discriminate as
- to which detection messages they are interested based on their specified
+ to which a remoting server can belong. The detectors can discriminate as to
+ which detection messages they are interested based on their specified
domain. The domain to which a remoting server belongs is stored within the
Identity of that remoting server, which is included within the detection
- messages. Detectors can be configured to accept detection messages from
- one, many or all domains.</para>
- </chapter>
\ No newline at end of file
+ messages. Detectors can be configured to accept detection messages from one,
+ many or all domains.</para>
+
+ <section>
+ <title>Discovery</title>
+
+ <para>One of the features of JBoss Remoting is to be able to dynamically
+ discover remoting servers. This is done through the use of what remoting
+ calls detectors. These detectors run in same instance as the servers and
+ the clients. The detectors that run within the server instance
+ automatically gets list of remoting servers running locally and emits a
+ detection message contain information about those servers, such as their
+ locator url and subsystems supported. The detector running within the
+ client instance will receive these detection messages and update a local
+ registry, called the network registry, with this information. The client
+ detector will also monitor the remoting servers it has discovered in case
+ one where to fail, in which case, will notify the network registry of the
+ failure The network registry will then fire events to registered listenes
+ (via JMX notifications), to include events such as new server added or
+ server failure.</para>
+
+ <para>There are currently two types of detector implementations; multicast
+ and JNDI. The multicast detectors use multicast channel to send and
+ receive detection messages. The JNDI detectors use a well known JNDI
+ server to bind and lookup detection messages.</para>
+
+ <para>The standard approach for detecting remoting servers happens in a
+ passive manner, in that as detection messages are received by the client
+ detector, they will cause an event to fire. In some cases, will need
+ ability to synchronously discover the remoting servers that exist upon
+ startup. This can be done by calling the forceDetection() method on the
+ detector. This will return an array of NetworkInstances which contains the
+ server information. Note, this method can take a few seconds to return (at
+ least in multicast implementation).</para>
+ </section>
+
+ <section>
+ <title>Transports</title>
+
+ <bridgehead>Service provider interface</bridgehead>
+
+ <para>The transport implementations within remoting, called invokers, are
+ responsible for handling the wire protocol to be used by remoting clients
+ and servers. Remoting will load client and server invoker (transport)
+ implementations (within the InvokerRegistry) using factories. The factory
+ class to be loaded will always be either TransportClientFactory (for
+ loading client invoker) or TransportServerFactory (for loading server
+ invoker). These classes must implement
+ <code>org.jboss.remoting.transport.ClientFactory</code> and
+ <code>org.jboss.remoting.transport.ServerFactory </code>interfaces
+ respectively. The package under which the TransportClientFactory and
+ TransportServerFactory will always start with
+ <code>org.jboss.test.remoting.transport</code>, then the transport
+ protocol type. For example, the 'socket' transport factories can be found
+ under
+ <code>org.jboss.remoting.transport.socket.TransportClientFactory</code>
+ and
+ <code>org.jboss.remoting.transport.socket.TransportServerFactory</code>.
+ The API for org.jboss.remoting.transport.ClientFactory is:</para>
+
+ <programlisting> public ClientInvoker createClientInvoker(InvokerLocator locator, Map config) throws IOException;
+ public boolean supportsSSL();
+</programlisting>
+
+ <para>The API for org.jboss.remoting.transport.ServerFactory is:</para>
+
+ <programlisting> public ServerInvoker createServerInvoker(InvokerLocator locator, Map config) throws IOException;
+ public boolean supportsSSL();
+</programlisting>
+
+ <para>An example of a transport client factory for the socket transport
+ (<code>org.jboss.remoting.transport.socket.TransportClientFactory</code>)
+ is:</para>
+
+ <programlisting>public class TransportClientFactory implements ClientFactory
+{
+ public ClientInvoker createClientInvoker(InvokerLocator locator, Map config)
+ throws IOException
+ {
+ return new SocketClientInvoker(locator, config);
+ }
+
+ public boolean supportsSSL()
+ {
+ return false;
+ }
+}
+</programlisting>
+
+ <para>The packages used within the factory does not matter as long as they
+ are on the classpath. Note that the transport factories are only loaded
+ upon request for that protocol. Also, the client and server factories have
+ been separated so that only the one requested is loaded (and thus the
+ corresponding classes needed for that invoker implementation). So if only
+ ask for a particular client transport invoker, only those classes are
+ loaded and the ones needed for the server are not required to be on the
+ classpath.</para>
+
+ <para>The biggest reason for taking this approach is allows users ability
+ to plugin custom transport implementation with zero config. Remoting comes
+ with the following transports: socket, sslsocket, http, https, multiplex,
+ sslmultiplex, servlet, sslservlet, rmi, sslrmi.</para>
+ </section>
+</chapter>
\ No newline at end of file
1.2 +533 -345 JBossRemoting/docs/guide/en/chap5.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap5.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap5.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- chap5.xml 30 Jul 2006 06:56:36 -0000 1.1
+++ chap5.xml 31 Jul 2006 05:03:42 -0000 1.2
@@ -526,6 +526,9 @@
<para><emphasis role="bold">Address</emphasis> - The IP of the multicast
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>
</section>
<section>
@@ -670,6 +673,12 @@
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 is needed for both
+ client and server to work. This if false by default.</para>
+
<bridgehead>Configurations affecting the Socket invoker
client</bridgehead>
@@ -694,7 +703,31 @@
client side is 1800000 (or 30 minutes).</para>
<para><emphasis role="bold">clientMaxPoolSize</emphasis> - the client
- side maximum number of threads. The default is 10.</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>
+
+ <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
+ SocketException.</para>
<para><emphasis role="bold">clientSocketClass</emphasis> - specifies
the fully qualified class name for the custom SocketWrapper
@@ -714,6 +747,111 @@
<para>To reiterate, these client configurations can only be set within
the server side configuration and will not change during
runtime.</para>
+
+ <section>
+ <title>How the Socket Invoker works</title>
+
+ <para>The Socket Invoker is one of the more complicated invokers
+ mainly because allows the highest degree of configuration. To better
+ understand how changes to configuration properties for the Socket
+ invoker (both client and server) will impact performance and
+ scalability, will discuss the implementation and how it works in
+ detail.</para>
+
+ <bridgehead>server</bridgehead>
+
+ <para>When the socket server invoker is started, it will create one,
+ 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>
+
+ <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>
+
+ <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 determiniation).</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 allowd (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 posibility that the socket connection returned, while still
+ appearing to be valid, has timedout 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 timedout 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>
<section>
@@ -843,21 +981,6 @@
<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>
-
- <bridgehead>Exception Handling</bridgehead>
-
- <para>When using remoting on the client side to connect to a remoting
- server (or any web server for that matter) via the http transport, if
- the server returns a response code greater than 400, the remoting
- client will read the error stream and return that as the response.
- Thus, the response returned will be of type java.lang.Exception. NOTE:
- this does NOT mean that the call to the Client's invoke() method will
- throw the exception, but instead will return the actual Exception
- object instance as a normally returned response. Therefore, is
- important that if want to check if response is an error instead of
- normal response, will need to look at the response code put in the
- metadata Map passed to the invoke() method on the Client instance. See
- the HTTP Handler section above for more details.</para>
</section>
<section>
@@ -1019,42 +1142,42 @@
for the InvokerLocator attribute is the exact url used to access the
servlet for the servlet invoker (more on how to define this below),
with the exception of the protocol being servlet instead of http. This
- is important because if using automatic discovery, this is the locator
- url that will be discovered and used by clients to connect to this
- server invoker.</para>
+ is important because 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 the release
- distribution or under the output/lib/ directory if doing a source
- build). By default, it is actually an exploded war, so the
+ 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
the WEB-INF directory is located the web.xml file. This is a standard
web configuration file and should look like:</para>
- <programlisting>
- <?xml version="1.0" encoding="UTF-8"?>
+ <programlisting> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
- <!--The the JBossRemoting server invoker servlet web.xml descriptor-->
<web-app>
<servlet>
<servlet-name>ServerInvokerServlet</servlet-name>
- <description>The ServerInvokerServlet receives requests via HTTP protocol
- from within a web container and passes it onto the ServletServerInvoker for processing.
+ <description>The ServerInvokerServlet receives requests via HTTP
+ protocol from within a web container and passes it onto the
+ ServletServerInvoker for processing.
</description>
- <servlet-class>
- org.jboss.remoting.transport.servlet.web.ServerInvokerServlet
- </servlet-class>
+ <servlet-class>org.jboss.remoting.transport.servlet.web.ServerInvokerServlet</servlet-class>
<init-param>
<param-name>invokerName</param-name>
- <param-value>
- jboss.remoting:service=invoker,transport=servlet
- </param-value>
+ <param-value>jboss.remoting:service=invoker,transport=servlet</param-value>
<description>The servlet server invoker</description>
+ <!--
+ <param-name>locatorUrl</param-name>
+ <param-value>servlet://localhost:8080/servlet-invoker/ServerInvokerServlet</param-value>
+ <description>The servlet server invoker locator url</description>
+ -->
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
@@ -1062,57 +1185,26 @@
<servlet-name>ServerInvokerServlet</servlet-name>
<url-pattern>/ServerInvokerServlet/*</url-pattern>
</servlet-mapping>
- </web-app>
- </programlisting>
+ </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 an 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 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. Also note that there is a parameter,
- invokerName, that has the value of the object name of the servlet
- server invoker. This is what the ServerInvokerServlet uses to look up
- the server invoker which it will pass the requests on to.</para>
-
- <para>Due to the way the servlet invoker is currently configured and
- deployed, it must run within the JBoss application server and is not
- portable to other web servers.</para>
-
- <bridgehead>Exception handling</bridgehead>
-
- <para>If the ServletServerInvoker catches any exception thrown from
- the invocation handler invoke() call, it will send an error to the
- client with a status of 500 and include the original exception message
- as its error message. From the client side, the client invoker will
- actually throw a CannotConnectException, which will have root
- exception as its cause. The cause should be an IOException with the
- server's message. For example, the stack trace from the exception
- thrown within the test case
- org.jboss.remoting.transport.servlet.test.ServletInvokerTestClient
- is:</para>
-
- <programlisting>
- org.jboss.remoting.CannotConnectException: Can not connect http client invoker.
- at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:154)
- at org.jboss.remoting.transport.http.HTTPClientInvoker.transport(HTTPClientInvoker.java:68)
- at org.jboss.remoting.RemoteClientInvoker.invoke(RemoteClientInvoker.java:113)
- at org.jboss.remoting.Client.invoke(Client.java:221)
- at org.jboss.remoting.Client.invoke(Client.java:184)
- at
- org.jboss.remoting.transport.servlet.test.ServletInvokerTestClient.testInvocation(ServletInvokerTestClient.java:65)
- at
- org.jboss.remoting.transport.servlet.test.ServletInvokerTestClient.main(ServletInvokerTestClient.java:98)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:324)
- at com.intellij.rt.execution.application.AppMain.main(AppMain.java:78)
- Caused by: java.io.IOException: Server returned HTTP response code: 500 for URL:
- http://localhost:8080/servlet-invoker/ServerInvokerServlet
- at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:791)
- at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:139)
- ... 11 more
- </programlisting>
+ 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>
<bridgehead>Issues</bridgehead>
@@ -1124,6 +1216,104 @@
</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 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>
+
+ <programlisting> <?xml version="1.0" encoding="UTF-8"?>
+
+ <server>
+ <mbean code="org.jboss.remoting.transport.Connector"
+ name="jboss.remoting:service=Connector,transport=SSLServlet"
+ display-name="SSL Servlet transport Connector">
+
+ <attribute name="InvokerLocator">
+ sslservlet://localhost:8443/servlet-invoker/ServerInvokerServlet
+ </attribute>
+ <attribute name="Configuration">
+ <config>
+ <handlers>
+ <handler subsystem="test">org.jboss.test.remoting.transport.web.WebInvocationHandler</handler>
+ </handlers>
+ </config>
+ </attribute>
+ </mbean>
+ </server> </programlisting>
+
+ <para>An example of servlet-invoker.war/WEB-INF/web.xml for the ssl
+ server invoker servlet would be: </para>
+
+ <programlisting> <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE web-app PUBLIC
+ "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+
+ <web-app>
+ <servlet>
+ <servlet-name>ServerInvokerServlet</servlet-name>
+ <description>The ServerInvokerServlet receives requests via HTTP
+ protocol from within a web container and passes it onto the
+ ServletServerInvoker for processing.
+ </description>
+ <servlet-class>org.jboss.remoting.transport.servlet.web.ServerInvokerServlet</servlet-class>
+ <init-param>
+ <param-name>locatorUrl</param-name>
+ <param-value>sslservlet://localhost:8443/servlet-invoker/ServerInvokerServlet</param-value>
+ <description>The servlet server invoker locator url</description>
+ </init-param>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>ServerInvokerServlet</servlet-name>
+ <url-pattern>/ServerInvokerServlet/*</url-pattern>
+ </servlet-mapping>
+ </web-app> </programlisting>
+ </section>
+
+ <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>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
+ WebServerError and returned as this type. The raw data from the web
+ server can the be retreived by getting the WebServerError's message.
+ </para>
+ </section>
+
+ <section>
<title id="section-multiplex" xreflabel="Multiplex Invoker">Multiplex
Invoker</title>
@@ -3981,7 +4171,9 @@
object instance (see
org.jboss.remoting.serialization.SerializationManager.createMarshalledValueForClone()).
Value for this property should be of type String and be either 'true' or
- 'false'.</para>
+ 'false'. In releases prior to 2.0.0, using this configuration setting
+ would have forced invokers to be remote, which can now be done via
+ FORCE_REMOTE config (see below).</para>
<para><emphasis role="bold">FORCE_REMOTE</emphasis> (actual value is
'force_remote') - indicates if when making local invocations (meaning
@@ -4037,7 +4229,7 @@
<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> <emphasis role="bold">CALLBACK_SERVER_PROTOCOL</emphasis> (actual
+ <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
@@ -4054,7 +4246,7 @@
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>
+ unused port.</para>
<para></para>
@@ -4095,7 +4287,7 @@
<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
- configuration). </para>
+ configuration).</para>
<para></para>
@@ -4119,7 +4311,7 @@
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>
+ will not be used if CUSTOM_SOCKET_FACTORY is also set.</para>
<para></para>
@@ -4242,11 +4434,11 @@
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
- CallbackPoller.DEFAULT_POLL_PERIOD) value is five seconds. </para>
+ CallbackPoller.DEFAULT_POLL_PERIOD) value is five seconds.</para>
<para></para>
- <bridgehead>org.jboss.remoting.callback.CallbackStore </bridgehead>
+ <bridgehead>org.jboss.remoting.callback.CallbackStore</bridgehead>
<para><emphasis role="bold">FILE_PATH_KEY</emphasis> (actual value is
'StoreFilePath') - key for setting which directory to write the callback
@@ -4258,19 +4450,18 @@
<para><emphasis role="bold">FILE_SUFFIX_KEY</emphasis> (actual value is
'StoreFileSuffix') - key for setting the file suffix to use for the
- callback objects written to disk. The default value is 'ser'. </para>
+ callback objects written to disk. The default value is 'ser'.</para>
<para></para>
- <bridgehead>org.jboss.remoting.callback.DefaultCallbackErrorHandler
- </bridgehead>
+ <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 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>
+ push callback. The default if this property is not set is five.</para>
<para></para>
@@ -4298,7 +4489,7 @@
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>
+ persisting of the callback message. The default value is 20.</para>
<para></para>
@@ -4307,7 +4498,7 @@
<para><emphasis role="bold">Bean properties (meaning have
getter/setter):</emphasis> <emphasis
role="bold">SubContextName</emphasis> - sub context name under which
- detection messages will be bound and looked up. </para>
+ detection messages will be bound and looked up.</para>
<para></para>
@@ -4331,8 +4522,8 @@
'MethodType') - key for getting the method type used by client in http
request. 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>
+ org.jboss.remoting.ServerInvocationHandler implementation. For
+ example:</para>
<programlisting> public Object invoke(InvocationRequest invocation) throws Throwable
{
@@ -4348,8 +4539,8 @@
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>
+ org.jboss.remoting.ServerInvocationHandler implementation. For
+ example:</para>
<programlisting> public Object invoke(InvocationRequest invocation) throws Throwable
{
@@ -4358,9 +4549,9 @@
...
</programlisting>
- <para> <emphasis role="bold">HTTPVERSION</emphasis> (actual value is
+ <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>
+ client request (e.g. HTTP/1.1).</para>
<para></para>
@@ -4386,7 +4577,7 @@
responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE, new Integer(202));
</programlisting>
- <para> <emphasis role="bold">RESPONSE_CODE_MESSAGE</emphasis> (actual
+ <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
@@ -4406,7 +4597,7 @@
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
+ <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.
@@ -4450,12 +4641,11 @@
<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>
+ true.</para>
<para></para>
- <bridgehead>org.jboss.remoting.transport.socket.MicroSocketClientInvoker
- </bridgehead>
+ <bridgehead>org.jboss.remoting.transport.socket.MicroSocketClientInvoker</bridgehead>
<para><emphasis role="bold">TCP_NODELAY_FLAG</emphasis> (actual value is
'enableTcpNoDelay') - can be either true or false and will indicate if
@@ -4475,13 +4665,12 @@
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>
+ marshaller/unmarshaller that is used, which may also be a
+ requirement.</para>
<para></para>
- <bridgehead>org.jboss.remoting.transport.socket.SocketServerInvoker
- </bridgehead>
+ <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
@@ -4491,7 +4680,6 @@
<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>
+ for the custom SocketWrapper implementation to use on the server.</para>
</section>
</chapter>
\ No newline at end of file
1.2 +23 -0 JBossRemoting/docs/guide/en/chap6.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap6.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap6.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- chap6.xml 30 Jul 2006 06:56:36 -0000 1.1
+++ chap6.xml 31 Jul 2006 05:03:42 -0000 1.2
@@ -44,6 +44,29 @@
does not implement StreamInvocationhandler, an exception will be thrown to
the client caller.</para>
+ <para>If want to have more control over the stream server being created to
+ send the stream data back to the caller, instead of letting remoting
+ create it internally, can do this by creating a Connector to act as stream
+ server and pass it when making Client invocation.</para>
+
+ <programlisting>public Object invoke(InputStream inputStream, Object param, Connector streamConnector) throws Throwable</programlisting>
+
+ <para>Note, the Connector passed must already have been started (else an
+ exception will be thrown). The stream handler will then be added to the
+ connector with the subystem 'stream'. The Connector passed will NOT be
+ stopped when the stream is closed by the server's stream proxy (which
+ happens automatically when remoting creates the stream server
+ internally).</para>
+
+ <para>Can also call invoke method on client an pass the invoker locator
+ would like to use and allow remoting to create the stream server using the
+ specified locator.</para>
+
+ <programlisting>public Object invoke(InputStream inputStream, Object param, InvokerLocator streamServerLocator) throws Throwable </programlisting>
+
+ <para>In this case, the Connector created internally by remoting will be
+ stopped when the stream is closed by the server's stream proxy.</para>
+
<para>It is VERY IMPORTANT that the StreamInvocationHandler implementation
close the InputStream when it finished reading, as will close the real
stream that lives within the client VM.</para>
1.2 +27 -11 JBossRemoting/docs/guide/en/chap7.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap7.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap7.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- chap7.xml 30 Jul 2006 06:56:36 -0000 1.1
+++ chap7.xml 31 Jul 2006 05:03:42 -0000 1.2
@@ -1,17 +1,26 @@
<chapter>
<title>Serialization</title>
- <para>JBoss Remoting allows for the plugging in of custom serialization
- implementations. This is available via the
+ <para>Serialization – how it works within remoting In general, remoting
+ will rely on a factory to provide the serialization implementation, or
+ <code>org.jboss.remoting.serialization.SerializationManager</code>, to be
+ used when doing object serialization. This factory is
<code>org.jboss.remoting.serialization.SerializationStreamFactory</code>
- class, which will provide the implementation as a
- <code>org.jboss.remoting.serialization.SerializationManager</code> . The
- SerializationManager can then be called on to get implementations for
- <code>java.io.ObjectInputStream</code> and
- <code>java.io.ObjectOutputStream</code> . This SerializationManager is
- used by most of the standard remoting marshallers and unmarshallers. There
- are currently two implementations of the SerializationManager; one for the
- standard java serialization, which is the default, and one for JBoss
+ and is a (as defined by its javadoc):</para>
+
+ <literallayout>“factory is for defining the Object stream implemenations to be used along with creating those implemenations for use.
+The main function will be to return instance of ObjectOutput and ObjectInput. By default, the implementations will be
+java.io.ObjectOutputStream and java.io.ObjectInputStream.�
+</literallayout>
+
+ <para>Currently there are only two different types of serialization
+ implementations; ‘java’ and ‘jboss’. The ‘java’ type uses
+ <code>org.jboss.remoting.serialization.impl.java.JavaSerializationManager</code>
+ as the SerializationManager implementation and is backed by standard Java
+ serialization provide by the JVM, which is the default. The ‘jboss’ type
+ uses
+ <code>org.jboss.remoting.serialization.impl.jboss.JBossSerializationManager</code>
+ as the SerializationManger implementation and is backed by JBoss
Serialization.</para>
<para>JBoss Serialization is a new project under development to provide a
@@ -24,5 +33,12 @@
<para>- different protocol</para>
- <para>JBoss Serialization requires JDK 1.5.</para>
+ <para>JBoss Serialization requires JDK 1.5</para>
+
+ <para></para>
+
+ <para>It is possible to override the default SerializationManger
+ implementation to be used by setting the system property ‘SERIALIZATION’
+ to the fully qualified name of the class to use (which will need to
+ provide a void contructor).</para>
</chapter>
\ No newline at end of file
1.2 +43 -10 JBossRemoting/docs/guide/en/chap8.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap8.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap8.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- chap8.xml 30 Jul 2006 06:56:36 -0000 1.1
+++ chap8.xml 31 Jul 2006 05:03:42 -0000 1.2
@@ -1,5 +1,5 @@
<chapter>
- <title>Connection Exception Listeners</title>
+ <title>Connection Exception Listeners and Leasing</title>
<bridgehead>Client side</bridgehead>
@@ -56,15 +56,48 @@
invocation made on the server from the client, whether it be a normal
invocation or a ping from the client internally.</para>
- <para>One the client side, there is no API or configuration changes
- needed. When the client initially connects to the server, it will check to
- see if client leasing is turned on by the server. If it is, it will
- internally start pinging periodically to the server to maintain the lease.
- When the client disconnects, it will internally send message to the server
- to stop monitoring lease for this client. Therefore, it is <emphasis
- role="bold">IMPORTANT</emphasis> that disconnect is called on the client
- when done using it. Otherwise, the client will continue to make its ping
- call on the server to keep its lease current.</para>
+ <para>The actual lease window established on the server side is dynamic
+ based the rate at which the client updates their lease. In particular, the
+ lease window will always be set to lease period * 2 for any lease that
+ does not have a lease update duration that is longer than 75% of the lease
+ window (meaning if set lease period to 10 seconds and always update that
+ lease in less then 7.5 seconds, the lease period will always remain 10
+ seconds). If the update duration is greater than 75% of the lease window,
+ the lease window will be reset to the lease duration X 2 (meaning if set
+ lease period to 10 seconds and update that lease in 8 seconds, the new
+ lease window will be set to 16 seconds). Also, the lease will not
+ immediately expire on the first lease timeout (meaning did not get an
+ update within the lease window). It takes two consecutive timeouts before
+ a lease will expire and a notification for client connection failure is
+ fired. This essentially means that the time it will take before a
+ connection listener is notified of a client connection failure will be at
+ least 4 X lease period (no exceptions).</para>
+
+ <para>By default, the client is not configured to do client leasing. This
+ means if want to allow client to do leasing, will need to either need to
+ set invoker locator parameter of 'leasing' to true or include
+ configuration entry with key of 'enableLease' and value of true to the map
+ passed when creating a Client instance. This does not mean that client
+ will lease for sure, but will indicate the client should call on the
+ server to see if the server has activated leasing and get the leasing
+ period desired by the server. If leasing turned on within the client can
+ also override the lease period it will use, ignoring the one sent by the
+ server, by setting 'lease_period' parameter in the invoker locator
+ parameters to millisecond value. Also worth noting is that if the client
+ and server are local, meaning running within the jvm, leasing (and thus
+ connection notification) will not be activated, even if is configured to
+ do so.</para>
+
+ <para>If leasing is turned on within the client side, there is no API or
+ configuration changes needed, unless want to override as mentioned
+ previously. When the client initially connects to the server, it will
+ check to see if client leasing is turned on by the server. If it is, it
+ will internally start pinging periodically to the server to maintain the
+ lease. When the client disconnects, it will internally send message to the
+ server to stop monitoring lease for this client. Therefore, it is
+ <emphasis role="bold">IMPORTANT</emphasis> that disconnect is called on
+ the client when done using it. Otherwise, the client will continue to make
+ its ping call on the server to keep its lease current. </para>
<para>The client can also provide extra metadata the will be communicated
to the connection listener in case of failure by supplying a metadata Map
1.32 +2 -2 JBossRemoting/docs/guide/en/master.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: master.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/master.xml,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -b -r1.31 -r1.32
--- master.xml 30 Jul 2006 06:59:17 -0000 1.31
+++ master.xml 31 Jul 2006 05:03:42 -0000 1.32
@@ -24,9 +24,9 @@
<bookinfo>
<title>JBoss Remoting Guide</title>
- <subtitle>JBoss Remoting version 1.4.1 final</subtitle>
+ <subtitle>JBoss Remoting version 2.0.0.CR1</subtitle>
- <releaseinfo>March 27, 2006</releaseinfo>
+ <releaseinfo>July 31, 2006</releaseinfo>
<mediaobject>
<imageobject>
More information about the jboss-cvs-commits
mailing list