[jboss-cvs] JBossRemoting/docs/guide/en ...
Tom Elrod
tom.elrod at jboss.com
Mon Jul 31 02:54:11 EDT 2006
User: telrod
Date: 06/07/31 02:54:11
Modified: docs/guide/en chap10.xml
Log:
JBREM-559 - updated remoting doc for some changes in 2.0.0.CR1 (transporters)
Revision Changes Path
1.2 +1012 -935 JBossRemoting/docs/guide/en/chap10.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap10.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap10.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- chap10.xml 30 Jul 2006 06:56:36 -0000 1.1
+++ chap10.xml 31 Jul 2006 06:54:11 -0000 1.2
@@ -1,47 +1,47 @@
-
- <chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
<title>How to use it - sample code</title>
- <para>Sample code demonstrating different remoting features can be found
- in the examples directory. They can be compiled and run manually via your
- IDE or via an ant build file found in the examples directory. There are
- many sets of sample code, each with their own package. Within most of
- these packages, there will be a server and a client class that will need
- to be executed</para>
+ <para>Sample code demonstrating different remoting features can be found in
+ the examples directory. They can be compiled and run manually via your IDE
+ or via an ant build file found in the examples directory. There are many
+ sets of sample code, each with their own package. Within most of these
+ packages, there will be a server and a client class that will need to be
+ executed</para>
<section>
<title>Simple invocation</title>
<para>The simple invocation sample (found in the
- org.jboss.remoting.samples.simple package), has two classes;
- SimpleClient and SimpleServer. It demonstrates making a simple
- invocation from a remoting client to a remoting server. The SimpleClient
- class will create an InvokerLocator object from a simple url-like string
- that identifies the remoting server to call upon (which will be
- socket://localhost:5400 by default). Then the SimpleClient will create a
- remoting Client class, passing the newly created InvokerLocator. Next
- the Client will be called to make an invocation on the remoting server,
- passing the request payload object (which is a String with the value of
- "Do something"). The server will return a response from this call which
- is printed to standard output.</para>
+ org.jboss.remoting.samples.simple package), has two classes; SimpleClient
+ and SimpleServer. It demonstrates making a simple invocation from a
+ remoting client to a remoting server. The SimpleClient class will create
+ an InvokerLocator object from a simple url-like string that identifies the
+ remoting server to call upon (which will be socket://localhost:5400 by
+ default). Then the SimpleClient will create a remoting Client class,
+ passing the newly created InvokerLocator. Next the Client will be called
+ to make an invocation on the remoting server, passing the request payload
+ object (which is a String with the value of "Do something"). The server
+ will return a response from this call which is printed to standard
+ output.</para>
<para>Within the SimpleServer, a remoting server is created and started.
This is done by first creating an InvokerLocator, just like was done in
the SimpleClient. Then constructing a Connector, passing the
- InvokerLocator. Next, need to call create() on the Connector to
- initialize all the resources, such as the remoting server invoker. Once
- created, need to create the invocation handler. The invocation handler
- is the class that the remoting server will pass client requests on to.
- The invocation handler in this sample simply returns the simple String
- "This is the return to SampleInvocationHandler invocation". Once
- created, the handler is added to the Connector. Finally, the Connector
- is started and will start listening for incoming client requests.</para>
+ InvokerLocator. Next, need to call create() on the Connector to initialize
+ all the resources, such as the remoting server invoker. Once created, need
+ to create the invocation handler. The invocation handler is the class that
+ the remoting server will pass client requests on to. The invocation
+ handler in this sample simply returns the simple String "This is the
+ return to SampleInvocationHandler invocation". Once created, the handler
+ is added to the Connector. Finally, the Connector is started and will
+ start listening for incoming client requests.</para>
<para>To run this example, can compile both the SimpleClient and
SimpleServer class, then first run the SimpleServer and then the
SimpleClient. Or can go to the examples directory and run the ant target
- 'run-simple-server' and then in another console window run the ant
- target 'run-simple-client'. For example:</para>
+ 'run-simple-server' and then in another console window run the ant target
+ 'run-simple-client'. For example:</para>
<para><programlisting>ant run-simple-server</programlisting>ant
then:</para>
@@ -72,8 +72,8 @@
will start with the server side. The SimpleServer class is much like the
one from the previous simple invocation example, except that instead of
using the 'socket' transport, will be using the 'http' transport. Also,
- instead of using the SampleInvocationHandler class as the handler, will
- be using the WebInvocationHandler (code shown below).</para>
+ instead of using the SampleInvocationHandler class as the handler, will be
+ using the WebInvocationHandler (code shown below).</para>
<programlisting>public class <emphasis role="bold">WebInvocationHandler</emphasis> implements <emphasis
role="bold">ServerInvocationHandler</emphasis>
@@ -129,24 +129,23 @@
invoke() method implementation. First it will check to see what the
request parameter was from the InvocationRequest and based on what the
value is, will return different responses. The first check is to see if
- the client passed a request to return a null value. The second will
- check to see if the request parameter from the client was of type
- ComplexObject. If so, return the pre-built ComplexObject that was
- created as a static variable.</para>
+ the client passed a request to return a null value. The second will check
+ to see if the request parameter from the client was of type ComplexObject.
+ If so, return the pre-built ComplexObject that was created as a static
+ variable.</para>
<para>After that, will check to see if the request parameter was for
returning a simple String. Notice in this block, will set the desired
- response code and message to be returned to the client. In this case,
- are setting the response code to be returned to 207 and the response
- message to "Custom response code and message from remoting server".
- These are non-standard code and message, but can be anything
- desired.</para>
+ response code and message to be returned to the client. In this case, are
+ setting the response code to be returned to 207 and the response message
+ to "Custom response code and message from remoting server". These are
+ non-standard code and message, but can be anything desired.</para>
<para>Last, if have not found a matching invocation request parameter,
will just return some simple html.</para>
- <para>Now onto the client side for making the calls to this handler,
- which can be found in SimpleClient (code shown below).</para>
+ <para>Now onto the client side for making the calls to this handler, which
+ can be found in SimpleClient (code shown below).</para>
<programlisting>public class <emphasis role="bold">SimpleClient</emphasis>
{
@@ -199,10 +198,10 @@
<para>This SimpleClient, like the one before in the simple invocation
example, starts off by creating an InvokerLocator and remoting Client
instance, except is using http transport instead of socket. The first
- invocation made is to send a newly constructed ComplexObject. If
- remember from the WebInvocationHandler above, will expect this
- invocation to return a different ComplexObject, which can be seen in the
- following system output line.</para>
+ invocation made is to send a newly constructed ComplexObject. If remember
+ from the WebInvocationHandler above, will expect this invocation to return
+ a different ComplexObject, which can be seen in the following system
+ output line.</para>
<para>The next invocation to be made is a simple http GET request. To do
this, must first let the remoting client know that the method type needs
@@ -211,11 +210,11 @@
get data in response) and the metadata map just populated with the GET
type. This invocation request will return a response of html.</para>
- <para>Then, will change back to being a POST type request and will pass
- a simple String as the payload to the invocation request. This will
- return a simple String as the response from the WebInvocationHandler.
- Afterward, will see the specific response code and message printed to
- standard output, as well as the exception itself.</para>
+ <para>Then, will change back to being a POST type request and will pass a
+ simple String as the payload to the invocation request. This will return a
+ simple String as the response from the WebInvocationHandler. Afterward,
+ will see the specific response code and message printed to standard
+ output, as well as the exception itself.</para>
<para>To run this example, can compile all the classes in the package,
then first run the SimpleServer and then the SimpleClient. Or can go to
@@ -242,11 +241,10 @@
Response code from server: 207
Response message from server: Custom response code and message from remoting server</programlisting>
- <para>Notice that the first response is the ComplexObject from the
- static variable returned within WebInvocationHandler. The next response
- is html and then simple text from the WebInvocationHandler. Can see the
- specific response code and message set in the
- WebInvocationHandler.</para>
+ <para>Notice that the first response is the ComplexObject from the static
+ variable returned within WebInvocationHandler. The next response is html
+ and then simple text from the WebInvocationHandler. Can see the specific
+ response code and message set in the WebInvocationHandler.</para>
<para>The output from the SimpleServer should look like:</para>
@@ -259,10 +257,10 @@
Invocation request from client is: null
Invocation request from client is: return_string</programlisting>
- <para>First the information for the http server invoker is written,
- which includes the locator uri used to start the server and the output
- from starting the Tomcat connector. Then will see the invocation
- parameter passed for each client request.</para>
+ <para>First the information for the http server invoker is written, which
+ includes the locator uri used to start the server and the output from
+ starting the Tomcat connector. Then will see the invocation parameter
+ passed for each client request.</para>
<para>Since the SimpleServer should still be running, can open a web
browser and enter the locator uri, http://localhost:5400. This should
@@ -278,31 +276,30 @@
invocation example, except in this sample, the client will make
asynchronous invocations on the server.</para>
- <para>The OnewayClient class sets up the remoting client as in the
- simple invocation sample, but instead of using the invoke() method, it
- uses the invokeOneway() method on the Client class. There are two basic
- modes when making a oneway invocation in remoting. The first is to have
- the calling thread to be the one that makes the actual call to the
- server. This allows the caller to ensure that the invocation request at
- least made it to the server. Once the server receives the invocation
- request, the call will return (and the request will be processed by a
- separate worker thread on the server). The other mode, which is
- demonstrated in the second call to invokeOneway, allows for the calling
- thread to return immediately and a worker thread on the client side will
- make the actual invocation on the server. This is faster of the two
- modes, but if there is a problem making the request on the server, the
- original caller will be unaware.</para>
+ <para>The OnewayClient class sets up the remoting client as in the simple
+ invocation sample, but instead of using the invoke() method, it uses the
+ invokeOneway() method on the Client class. There are two basic modes when
+ making a oneway invocation in remoting. The first is to have the calling
+ thread to be the one that makes the actual call to the server. This allows
+ the caller to ensure that the invocation request at least made it to the
+ server. Once the server receives the invocation request, the call will
+ return (and the request will be processed by a separate worker thread on
+ the server). The other mode, which is demonstrated in the second call to
+ invokeOneway, allows for the calling thread to return immediately and a
+ worker thread on the client side will make the actual invocation on the
+ server. This is faster of the two modes, but if there is a problem making
+ the request on the server, the original caller will be unaware.</para>
<para>The OnewayServer is exactly the same as the SimpleServer from the
- previous example, with the exception that invocation handler returns
- null (since even if did return a response, would not be delivered to the
+ previous example, with the exception that invocation handler returns null
+ (since even if did return a response, would not be delivered to the
original caller).</para>
<para>To run this example, can compile both the OnewayClient and
OnewayServer class, then run the OnewayServer and then the OnewayClient.
Or can go to the examples directory and run the ant target
- 'run-oneway-server' and then in another console window run the ant
- target 'run-oneway-client'. For example:</para>
+ 'run-oneway-server' and then in another console window run the ant target
+ 'run-oneway-client'. For example:</para>
<programlisting>ant run-oneway-server</programlisting>
@@ -325,10 +322,9 @@
<para>Note: will have to manually shut down the OnewayServer once
started.</para>
- <para>Although this example only demonstrates making one way
- invocations, could include this with callbacks (see further down) to
- have asynchronous invocations with callbacks to verify was
- processed.</para>
+ <para>Although this example only demonstrates making one way invocations,
+ could include this with callbacks (see further down) to have asynchronous
+ invocations with callbacks to verify was processed.</para>
</section>
<section>
@@ -336,20 +332,20 @@
<para>The discovery sample (found in the
org.jboss.remoting.samples.detection package) is similar to the simple
- invocation example in that it makes a simple invocation from the client
- to the server. However, in this example, instead of explicitly
- specifying the invoker locator to use for the target remoting server, it
- is discovered dynamically during runtime. This example is composed of
- two classes; SimpleDetectorClient and SimpleDetectorServer.</para>
+ invocation example in that it makes a simple invocation from the client to
+ the server. However, in this example, instead of explicitly specifying the
+ invoker locator to use for the target remoting server, it is discovered
+ dynamically during runtime. This example is composed of two classes;
+ SimpleDetectorClient and SimpleDetectorServer.</para>
<para>The SimpleDetectorClient starts off by setting up the remoting
detector. Detection on the client side requires a few components; a JMX
MBeanServer, one or more Detectors, and a NetworkRegistry. The Detectors
- will listen for detection messages from remoting servers and then add
- the information for the detected servers to the NetworkRegistry. They
- use JMX to lookup and call on the NetworkRegistry. The NetworkRegistry
- uses JMX Notifications to emit changes in network topology (remoting
- servers being added or removed).</para>
+ will listen for detection messages from remoting servers and then add the
+ information for the detected servers to the NetworkRegistry. They use JMX
+ to lookup and call on the NetworkRegistry. The NetworkRegistry uses JMX
+ Notifications to emit changes in network topology (remoting servers being
+ added or removed).</para>
<para>In this particular example, the SimpleDetectorClient is registered
with the NetworkRegistry as a notification listener. When it receives
@@ -364,18 +360,18 @@
<para>The biggest change between the SimpleDetectorServer and the
SimpleServer from the first sample is that have added a method,
setupDetector(), to create and start a remoting Detector. On the server
- side, only two components are needed for detection; the Detector and a
- JMX MBeanServer. As for the setup of the Connector, it is exactly the
- same as before. Notice that even though we have added a Detector on the
- server side, the Connector is not directly aware of either Detector or
- the MBeanServer, so no code changes for the Connector setup is
+ side, only two components are needed for detection; the Detector and a JMX
+ MBeanServer. As for the setup of the Connector, it is exactly the same as
+ before. Notice that even though we have added a Detector on the server
+ side, the Connector is not directly aware of either Detector or the
+ MBeanServer, so no code changes for the Connector setup is
required.</para>
<para>To run this example, can compile both the SimpleDetectorClient and
- SimpleDetectorServer class, then run the SimpleDetectorServer and then
- the SimpleDetectorClient. Or can go to the examples directory and run
- the ant target 'run-detector-server' and then in another window run the
- ant target 'run-detector-client'. For example:</para>
+ SimpleDetectorServer class, then run the SimpleDetectorServer and then the
+ SimpleDetectorClient. Or can go to the examples directory and run the ant
+ target 'run-detector-server' and then in another window run the ant target
+ 'run-detector-client'. For example:</para>
<programlisting>ant run-detector-server</programlisting>
@@ -383,8 +379,8 @@
<programlisting>ant run-detector-client</programlisting>
- <para>The initial output when running the SimpleDetectorClient should
- look like:</para>
+ <para>The initial output when running the SimpleDetectorClient should look
+ like:</para>
<programlisting>ri Jan 13 09:36:50 EST 2006: [CLIENT]: Starting JBoss/Remoting client... to stop this client, kill it manually via Control-C
Fri Jan 13 09:36:50 EST 2006: [CLIENT]: NetworkRegistry has been created
@@ -424,8 +420,8 @@
callbacks from a remoting server to a remoting client. This example is
composed of two classes; CallbackClient and CallbackServer.</para>
- <para>Within remoting, there are two approaches in which a callback can
- be received. The first is to actively ask for callback messages from the
+ <para>Within remoting, there are two approaches in which a callback can be
+ received. The first is to actively ask for callback messages from the
remoting server, which is called a pull callback (since are pulling the
callbacks from the server). The second is to have the server send the
callbacks to the client as they are generated, which is called a push
@@ -434,56 +430,56 @@
<para>Looking at the CallbackClient class, will see that the first thing
done is to create a remoting Client, which is done in the same manner as
- previous examples. Next, we'll perform a pull callback, which requires
- the creation of a CallbackHandler. The CallbackHandler, which implements
- the InvokerCallbackHandler interface, is what is called upon with a
- Callback object when a callback is received. The Callback object
- contains information such as the callback message (in Object form), the
- server locator from where the callback originally came from, and a
- handle object which can help to identify callback context (similar to
- the handle object within a JMX Notification). Once created, the
- CallbackHandler is then registered as a listener within the Client. This
- will cause the client to make a call to the server to notify the server
- it has a callback listener (more on this below in the server section).
- Although the CallbackHandler is not called upon directly when doing pull
- callbacks, it is needed as an identifier for the callbacks.</para>
-
- <para>Then the client will wait a few seconds, make a simple invocation
- on the server, and then call on the remoting Client instance to get any
- callbacks that may be available for our CallbackHandler. This will
- return a list of callbacks, if any exist. The list will be iterated and
- each callback will be printed to standard output. Finally, the callback
- handler will be removed as a listener from the remoting Client (which in
- turns removes it from the remoting server).</para>
-
- <para>After performing a pull callback, will perform a push callback.
- This is a little more involved as requires creating a callback server to
- which the remoting target server can callback on when it generates a
- callback message. To do this, will need to create a remoting Connector,
- just as have seen in previous examples. For this particular example, we
- use the same locator url as our target remoting server, but increment
- the port to listen on by one. Will also notice that use the
- SampleInvocationHandler hander from the CallbackServer (more in this in
- a minute). After creating our callback server, a CallbackHandler and
- callback handle object is created. Next, remoting Client is called to
- add our callback listener. Here we pass not only the CallbackHandler,
- but the InvokerLocator for the callback server (so the target server
- will know where to deliver callback messages to), and the callback
- handle object (which will be included in all the callback messages
- delivered for this particular callback listener).</para>
-
- <para>Then the client will wait a few seconds, to allow the target
- server time to generate and deliver callback messages. After that, we
- remove the callback listener and clean up our callback server.</para>
+ previous examples. Next, we'll perform a pull callback, which requires the
+ creation of a CallbackHandler. The CallbackHandler, which implements the
+ InvokerCallbackHandler interface, is what is called upon with a Callback
+ object when a callback is received. The Callback object contains
+ information such as the callback message (in Object form), the server
+ locator from where the callback originally came from, and a handle object
+ which can help to identify callback context (similar to the handle object
+ within a JMX Notification). Once created, the CallbackHandler is then
+ registered as a listener within the Client. This will cause the client to
+ make a call to the server to notify the server it has a callback listener
+ (more on this below in the server section). Although the CallbackHandler
+ is not called upon directly when doing pull callbacks, it is needed as an
+ identifier for the callbacks.</para>
+
+ <para>Then the client will wait a few seconds, make a simple invocation on
+ the server, and then call on the remoting Client instance to get any
+ callbacks that may be available for our CallbackHandler. This will return
+ a list of callbacks, if any exist. The list will be iterated and each
+ callback will be printed to standard output. Finally, the callback handler
+ will be removed as a listener from the remoting Client (which in turns
+ removes it from the remoting server).</para>
+
+ <para>After performing a pull callback, will perform a push callback. This
+ is a little more involved as requires creating a callback server to which
+ the remoting target server can callback on when it generates a callback
+ message. To do this, will need to create a remoting Connector, just as
+ have seen in previous examples. For this particular example, we use the
+ same locator url as our target remoting server, but increment the port to
+ listen on by one. Will also notice that use the SampleInvocationHandler
+ hander from the CallbackServer (more in this in a minute). After creating
+ our callback server, a CallbackHandler and callback handle object is
+ created. Next, remoting Client is called to add our callback listener.
+ Here we pass not only the CallbackHandler, but the InvokerLocator for the
+ callback server (so the target server will know where to deliver callback
+ messages to), and the callback handle object (which will be included in
+ all the callback messages delivered for this particular callback
+ listener).</para>
+
+ <para>Then the client will wait a few seconds, to allow the target server
+ time to generate and deliver callback messages. After that, we remove the
+ callback listener and clean up our callback server.</para>
<para>The CallbackServer is pretty much the same as the previous samples
in setting up the remoting server, via the Connector. The biggest change
resides in the ServerInvocationHandler implementation,
SampleInvocationHandler (which is an inner class to CallbackServer). The
- first thing to notice is now have a variable called listeners, which is
- a List to hold any callback listeners that get registered. Also, in the
- constructor of the SampleInvocationHandler, we set up a new thread to
- run in the background. This thread, executing the run() method in
+ first thing to notice is now have a variable called listeners, which is a
+ List to hold any callback listeners that get registered. Also, in the
+ constructor of the SampleInvocationHandler, we set up a new thread to run
+ in the background. This thread, executing the run() method in
SampleInvocationHandler, will continually loop looking to see if the
shouldGenerateCallbacks has been set. If it has been, will create a
Callback object and loop through its list of listeners and tell each
@@ -496,9 +492,9 @@
<para>To run this example, can compile both the CallbackClient and
CallbackServer class, then run the CallbackServer and then the
- CallbackClient. Or can go to the examples directory and run the ant
- target 'run-callback-server' and then in another window run the ant
- target 'run-callback-client. For example:</para>
+ CallbackClient. Or can go to the examples directory and run the ant target
+ 'run-callback-server' and then in another window run the ant target
+ 'run-callback-client. For example:</para>
<programlisting>ant run-callback-server</programlisting>
@@ -524,9 +520,9 @@
Received callback server invoker of: InvokerLocator [socket://127.0.0.1:5400/]</programlisting>
<para>This output shows that client first pulled two callbacks generated
- from the server. Then, after creating and registering our second
- callback handler and a callback server, two callbacks were received from
- the target server.</para>
+ from the server. Then, after creating and registering our second callback
+ handler and a callback server, two callbacks were received from the target
+ server.</para>
<para>The output in the CallbackServer console window should look
like:</para>
@@ -544,63 +540,61 @@
<para>There are a few important points to mention about this example.
First, notice that in the client, the same callback handle object in the
- push callbacks was received as was registered with the callback
- listener. However, there was no special code required to facilitate this
- within the SampleInvocationHandler. This is handled within remoting
- automatically. Also notice when the callback server was created within
- the client, no special coding was required to register the callback
- handler with it, both were simply passed to the remoting Client instance
- when registering the callback listener and was handled
- internally.</para>
+ push callbacks was received as was registered with the callback listener.
+ However, there was no special code required to facilitate this within the
+ SampleInvocationHandler. This is handled within remoting automatically.
+ Also notice when the callback server was created within the client, no
+ special coding was required to register the callback handler with it, both
+ were simply passed to the remoting Client instance when registering the
+ callback listener and was handled internally.</para>
</section>
<section>
<title>Streaming</title>
- <para>The streaning sample (found in the
- org.jboss.remoting.samples.stream package) illustrates how a
- java.io.InputStream can be sent from a client and read on demand from a
- server. This example is composed of two classes: StreamingClient and
- StreamingServer.</para>
-
- <para>Unlike the previous examples that sent plain old java objects as
- the payload, this example will be sending a java.io.FileInputStream as
- the payload to the server. This is a special case because streams can
- not be serialized. One approach to this might be to write out the
- contents of a stream to a byte buffer and send the whole data content to
- the server. However, this approach can be dangerous because if the data
- content of the stream is large, such as an 800MB file, would run the
- risk of causing an out of memory error (since are loading all 800MB into
- memory). Another approach, which is used by JBossRemoting, is to create
- a proxy to the original stream. This proxy can then be called upon for
- reading, same as the original stream. When this happens, the proxy will
- call back the original stream for the requested data.</para>
+ <para>The streaning sample (found in the org.jboss.remoting.samples.stream
+ package) illustrates how a java.io.InputStream can be sent from a client
+ and read on demand from a server. This example is composed of two classes:
+ StreamingClient and StreamingServer.</para>
+
+ <para>Unlike the previous examples that sent plain old java objects as the
+ payload, this example will be sending a java.io.FileInputStream as the
+ payload to the server. This is a special case because streams can not be
+ serialized. One approach to this might be to write out the contents of a
+ stream to a byte buffer and send the whole data content to the server.
+ However, this approach can be dangerous because if the data content of the
+ stream is large, such as an 800MB file, would run the risk of causing an
+ out of memory error (since are loading all 800MB into memory). Another
+ approach, which is used by JBossRemoting, is to create a proxy to the
+ original stream. This proxy can then be called upon for reading, same as
+ the original stream. When this happens, the proxy will call back the
+ original stream for the requested data.</para>
- <para>Looking at the StreamingClient, the remoting Client is created as
- in previous samples. Next, will create a java.io.FileInputStream to the
+ <para>Looking at the StreamingClient, the remoting Client is created as in
+ previous samples. Next, will create a java.io.FileInputStream to the
sample.txt file on disk (which is in the same directory as the test
classes). Finally, will call the remoting Client to do its invocation,
passing the new FileInputStream and the name of the file. The second
parameter could be of any Object type and is meant to supply some
meaningful context to the server in regards to the stream being passed,
- such as the file name to use when writing to disk on the server side.
- The response from the server, in this example, is the size of the file
- it wrote to disk.</para>
+ such as the file name to use when writing to disk on the server side. The
+ response from the server, in this example, is the size of the file it
+ wrote to disk.</para>
<para>The StreamingServer sets up the remoting server as was done in
previous examples. However, instead of using an implementation of the
- ServerInvocationHandler class as the server handler, an implementation
- of the StreamInvocationHandler (which extends the
- ServerInvocationHandler) is used. The StreamInvocationHandler includes
- an extra method called handleStream() especially for processing requests
- with a stream as the payload. In this example, the class implementing
- the StreamInvocationHandler is the TestStreamInvocationHandler class,
- which is an inner class to the StreamingServer. The handleStream()
- method within the TestStreamInvocationHandler will use the stream passed
- to it to write out its contents to a file on disk, as specified by the
- second parameter passed to the handleStream() method. Upon writing out
- the file to disk, the handleStream() method will return to the client
- caller the size of the file.</para>
+ ServerInvocationHandler class as the server handler, an implementation of
+ the StreamInvocationHandler (which extends the ServerInvocationHandler) is
+ used. The StreamInvocationHandler includes an extra method called
+ handleStream() especially for processing requests with a stream as the
+ payload. In this example, the class implementing the
+ StreamInvocationHandler is the TestStreamInvocationHandler class, which is
+ an inner class to the StreamingServer. The handleStream() method within
+ the TestStreamInvocationHandler will use the stream passed to it to write
+ out its contents to a file on disk, as specified by the second parameter
+ passed to the handleStream() method. Upon writing out the file to disk,
+ the handleStream() method will return to the client caller the size of the
+ file.</para>
<para>To run this example, can compile both the StreamingClient and
StreamingServer class, then run the StreamingServer and then the
@@ -631,10 +625,9 @@
New file server_sample.txt has been written out to C:\tmp\JBossRemoting_1_4_0_final\examples\server_sample.txt</programlisting>
<para>After running this example, there should be a newly created
- server_sample.txt file in the root examples directory. The contents of
- the file should look exactly like the contents of the sample.txt file
- located in the examples\org\jboss\remoting\samples\stream
- directory.</para>
+ server_sample.txt file in the root examples directory. The contents of the
+ file should look exactly like the contents of the sample.txt file located
+ in the examples\org\jboss\remoting\samples\stream directory.</para>
</section>
<section>
@@ -643,29 +636,28 @@
<para>The serialization sample (found in the
org.jboss.remoting.samples.serialization package) illustrates how JBoss
Serialization can be used in place of the standard java serialization to
- allow for sending of invocation payload objects that do not implement
- the java.io.Serializable interface. This example is composed of three
- classes: SerializationClient, SerializationServer, and
+ allow for sending of invocation payload objects that do not implement the
+ java.io.Serializable interface. This example is composed of three classes:
+ SerializationClient, SerializationServer, and
NonSerializablePayload.</para>
<para>This example is exactly like the one from the simple example with
- two differences. The first difference is the use of JBoss Serialization
- to convert object instances to binary data format for wire transfer.
- This is accomplished by adding an extra parameter (serializationtype) to
- the locator url with a value of 'jboss'. Is important to note that use
- of JBoss Serialization requires JDK 1.5, so this example will need to be
- run using JDK 1.5. The second difference is instead of sending and
- receiving a simple String type for the remote invocation payload, will
- be sending and receiving an instance of the NonSerializablePayload
- class.</para>
+ two differences. The first difference is the use of JBoss Serialization to
+ convert object instances to binary data format for wire transfer. This is
+ accomplished by adding an extra parameter (serializationtype) to the
+ locator url with a value of 'jboss'. Is important to note that use of
+ JBoss Serialization requires JDK 1.5, so this example will need to be run
+ using JDK 1.5. The second difference is instead of sending and receiving a
+ simple String type for the remote invocation payload, will be sending and
+ receiving an instance of the NonSerializablePayload class.</para>
<para>There are a few important points to notice with the
- NonSerializablePayload class. The first is that it does NOT implement
- the java.io.Serializable interface. The second is that it has a void
- parameter constructor. This is a requirement of JBoss Serialization for
- object instances that do not implement the Serializable interface.
- However, this void parameter constructor can be private, as in the case
- of NonSerializablePayload, as to not change the external API of the
+ NonSerializablePayload class. The first is that it does NOT implement the
+ java.io.Serializable interface. The second is that it has a void parameter
+ constructor. This is a requirement of JBoss Serialization for object
+ instances that do not implement the Serializable interface. However, this
+ void parameter constructor can be private, as in the case of
+ NonSerializablePayload, as to not change the external API of the
class.</para>
<para>To run this example, can compile both the SerializationClient and
@@ -701,21 +693,121 @@
<section>
<title>Transporters</title>
- <para>The transporter sample spans several examples showing different
- ways to use the transporter. Each specific example is within its own
- package under the org.jboss.remoting.samples.transporter package. Since
- each of the transporter examples includes common objects, as well as
- client and server classes, the common objects will be found under the
- main transporter sub-package and the client and server classes in their
+ <section>
+ <title>Transporters - beaming POJOs</title>
+
+ <para>There are many ways in which to expose a remote interface to a
+ java object. Some require a complex framework API based on a standard
+ specification and some require new technologies like annotations and
+ AOP. Each of these have their own benefits. JBoss Remoting transporters
+ provide the same behavior via a simple API without the need for any of
+ the newer technologies.</para>
+
+ <para>When boiled down, transporters take a plain old java object (POJO)
+ and expose a remote proxy to it via JBoss Remoting. Dynamic proxies and
+ reflection are used to make the typed method calls on that target POJO.
+ Since JBoss Remoting is used, can select from a number of different
+ network transports (i.e. rmi, http, socket, multiplex, etc.), including
+ support for SSL. Even clustering features can be included.</para>
+
+ <bridgehead>How it works</bridgehead>
+
+ <para>In this section will discuss how remoting transporters can be
+ used, some requirments for usage, and a little detail on the
+ implementation. For greater breath on usage, please review the
+ transporter samples as most use cases are covered there.</para>
+
+ <para>To start, will need to have a plain old java object that
+ implements one or more interfaces that want to expose for remote method
+ invocation. Then will need to create a
+ <code>org.jboss.remoting.transporter.TransporterServer</code> to wrap
+ around it, so that can be exposed remotely. This can be done in one of
+ two basic ways. The first is to use a static
+ <code>createTransporterServer()</code> method of the TransporterServer
+ class. There are many of these create methods, but all basically do that
+ same thing in that they take a remoting locator and target pojo and will
+ return a TransporterServer instance that has been started and ready to
+ receive remote invocations (see javadoc for TransporterServer for all
+ the different static createTransporterServer() methods). The other way
+ to create a TransporterServer for the target pojo is to construct an
+ instance of it. This provides a little more flexibility as are able to
+ control more aspects of the TransporterServer, such as when it will be
+ started.</para>
+
+ <para>When a TransporterServer is created, it will create a remoting
+ Connector using the locator provided. It will generate a server
+ invocation handler that wraps the target pojo provided and use
+ reflection to make the calls on it based on the invocations it receives
+ from clients. By default, the subsystem underwhich the server invocation
+ handler is registered is the interface class name for which the target
+ pojo is exposing. If the target implements multiple interfaces, and a
+ specific one to use is not specified, all the interfaces will be
+ registered as subsystems for the same server invocation handler.
+ Whenever no long want the target pojo to receive remote method
+ invocations, will need to call the <code>stop()</code> method on the
+ TransporterServer for the target pojo (this is very important, as
+ otherwise will never be released from memory and will continue to
+ consume network and memory resources).</para>
+
+ <para>On the client side, in order to be able to call on the target pojo
+ remotely, will need to use the
+ <code>org.jboss.remoting.transporter.TransporterClient</code>. Unlike
+ the TransporterServer, can only use the static create methods of the
+ TransporterClient (this is because the return to the static create
+ method is a typed dynamic proxy). The static method to call on the
+ TransportClient is <code>createTransporterClient()</code>, where will
+ pass the locator to find the target pojo (same as one used when creating
+ the TransporterServer) and the interface for the target pojo that want
+ to make remote method invocations on. The return from this create call
+ will be a dynamic proxy which you can cast to to same interface type
+ supplied. At that point, can make typed method invocations on the
+ returned object, which will then make the remote invocations under the
+ covers. Note that can have multiple transporter clients to the same
+ target pojo, each using different interface types for making calls.
+ </para>
+
+ <para>When no longer need to make invocations on the target pojo, the
+ resources associated with the remoting client will need to be cleaned
+ up. This is done by calling the <code>destroyTransporterClient()</code>
+ method of the TransporterClient. This is important to remember to do, as
+ will otherwise leave network resources active even though not in
+ use.</para>
+
+ <para>One of the features of using remoting transporters is location
+ transparency. By this mean that client proxies returned by the
+ TransporterClient can be passed over the network. For example, can have
+ a target pojo that returns from a method call a client proxy (that it
+ created using the TransporterClient) in which the client can call on
+ directly as well. See the transporter proxy sample code to see how this
+ can be done.</para>
+
+ <para>Another nice feature when using transporters is the ability to
+ cluster. To be more specific, can create multiple target pojos using the
+ TransporterServer in clustered mode and then use the TransporterClient
+ in clustered mode to create a client proxy that will discover the
+ location of the target pojos are wanting to call on. Will also provide
+ automatic, seemless failover of remote method invocations in the case
+ that a particular target pojo instance fails. However, note that only
+ provide invocation failover and does not take into account state
+ transfer between target pojos (would need addition of JBoss Cache or
+ some other state synchronization tool). </para>
+ </section>
+
+ <para>The transporter sample spans several examples showing different ways
+ to use the transporter. Each specific example is within its own package
+ under the org.jboss.remoting.samples.transporter package. Since each of
+ the transporter examples includes common objects, as well as client and
+ server classes, the common objects will be found under the main
+ transporter sub-package and the client and server classes in their
respective sub-packages (named client and server).</para>
<section>
<title>Transporter sample - basic</title>
<para>The basic transporter example (found in
- org.jboss.remoting.samples.transporter.basic package) illustrates how
- to build a simple transporter for making remote invocations on plain
- old java objects.</para>
+ org.jboss.remoting.samples.transporter.basic package) illustrates how to
+ build a simple transporter for making remote invocations on plain old
+ java objects.</para>
<para>In this first, basic transporter example, will be using a few
domain objects; <code>Customer</code> and Address, which are just data
@@ -874,8 +966,8 @@
public Customer processCustomer(Customer customer);
}</programlisting>
- <para>So far, nothing special, just plain old java objects. Next need
- to create the server component that will listen for remote request to
+ <para>So far, nothing special, just plain old java objects. Next need to
+ create the server component that will listen for remote request to
invoke on the target POJO. This is where the transporter comes
in.</para>
@@ -918,29 +1010,27 @@
}
}</programlisting>
- <para>The <code>Server</code> class is a pretty simple one. It calls
- the <code>TransporterServer</code> factory method to create the server
- component for the <code>CustomerProcessorImpl</code> instance using
- the specified remoting locator information.</para>
+ <para>The <code>Server</code> class is a pretty simple one. It calls the
+ <code>TransporterServer</code> factory method to create the server
+ component for the <code>CustomerProcessorImpl</code> instance using the
+ specified remoting locator information.</para>
<para>The <code>TransporterServer</code> returned from the
<code>createTransporterServer() </code>call will be a running instance
- of a remoting server using the <literal>socket</literal> transport
- that is bound to <literal>localhost</literal> and listening for remote
- requests on port <literal>5400</literal>. The requests that come in
- will be forwarded to the remoting handler which will convert them into
- direct method calls on the target POJO,
- <code>CustomerProcessorImpl</code> in this case, using
- reflection.</para>
-
- <para>The <code>TransporterServer</code> has a <code>start()</code>
- and <code>stop()</code> method exposed to control when to start and
- stop the running of the remoting server. The <code>start()</code>
- method is called automatically within the
- <code>createTransporterServer()</code> method, so is ready to receive
- requests upon the return of this method. The <code>stop()</code>
- method, however, needs to be called explicitly when no longer wish to
- receive remote calls on the target POJO.</para>
+ of a remoting server using the <literal>socket</literal> transport that
+ is bound to <literal>localhost</literal> and listening for remote
+ requests on port <literal>5400</literal>. The requests that come in will
+ be forwarded to the remoting handler which will convert them into direct
+ method calls on the target POJO, <code>CustomerProcessorImpl</code> in
+ this case, using reflection.</para>
+
+ <para>The <code>TransporterServer</code> has a <code>start()</code> and
+ <code>stop()</code> method exposed to control when to start and stop the
+ running of the remoting server. The <code>start()</code> method is
+ called automatically within the <code>createTransporterServer()</code>
+ method, so is ready to receive requests upon the return of this method.
+ The <code>stop()</code> method, however, needs to be called explicitly
+ when no longer wish to receive remote calls on the target POJO.</para>
<para>Next up is the client side. This is represented by the
<code>Client</code> class.</para>
@@ -991,30 +1081,29 @@
}
}</programlisting>
- <para>The <code>Client</code> class is also pretty simple. It creates
- a new <code>Customer</code> object instance, creates the remote proxy
- to the <code>CustomerProcessor</code>, and then calls on the
- <code>CustomerProcessor</code> to process its new
- <code>Customer</code> instance.</para>
+ <para>The <code>Client</code> class is also pretty simple. It creates a
+ new <code>Customer</code> object instance, creates the remote proxy to
+ the <code>CustomerProcessor</code>, and then calls on the
+ <code>CustomerProcessor</code> to process its new <code>Customer</code>
+ instance.</para>
<para>To get the remote proxy for the <code>CustomerProcessor</code>,
all that is required is to call the <code>TransporterClient</code>'s
method <code>createTransporterClient()</code> method and pass the
locator uri and the type of the remote proxy (and explicitly cast the
- return to that type). This will create a dynamic proxy for the
- specified type, <code>CustomerProcessor</code> in this case, which is
- backed by a remoting client which in turn makes the calls to the
- remote POJO's remoting server. Once the call to
- <code>createTransportClient()</code> has returned, the remoting client
- has already made its connection to the remoting server and is ready to
- make calls (will throw an exception if it could not connect to the
- specified remoting server).</para>
+ return to that type). This will create a dynamic proxy for the specified
+ type, <code>CustomerProcessor</code> in this case, which is backed by a
+ remoting client which in turn makes the calls to the remote POJO's
+ remoting server. Once the call to <code>createTransportClient()</code>
+ has returned, the remoting client has already made its connection to the
+ remoting server and is ready to make calls (will throw an exception if
+ it could not connect to the specified remoting server).</para>
- <para>When finished making calls on the remote POJO proxy, will need
- to explicitly destroy the client by calling
+ <para>When finished making calls on the remote POJO proxy, will need to
+ explicitly destroy the client by calling
<code>destroyTransporterClient()</code> and pass the remote proxy
- instance. This allows the remoting client to disconnect from the
- POJO's remoting server and clean up any network resources previously
+ instance. This allows the remoting client to disconnect from the POJO's
+ remoting server and clean up any network resources previously
used.</para>
<para>To run this example, can run the Server and then the Client. Or
@@ -1052,15 +1141,14 @@
</programlisting>
- <para>and the output from the Server class should be similar
- to:</para>
+ <para>and the output from the Server class should be similar to:</para>
<programlisting>processed customer with new id of 204</programlisting>
<para>The output shows that the <code>Customer</code> instance created
- on the client was sent to the server where it was processed (by
- setting the customer id to 204) and returned to the client (and
- printed out showing that the customer id was set to 204).</para>
+ on the client was sent to the server where it was processed (by setting
+ the customer id to 204) and returned to the client (and printed out
+ showing that the customer id was set to 204).</para>
</section>
<section>
@@ -1070,15 +1158,14 @@
org.jboss.remoting.samples.transporter.serialization package) is very
similar to the previous basic example, except in this one, the domain
objects being sent over the wire will NOT be Serializable. This is
- accomplished via the use of JBoss Serialization. This can be useful
- when don't know which domain objects you may be using in remote calls
- or if adding ability for remote calls on legacy code.</para>
-
- <para>To start, there are a few more domain objects:
- <code>Order</code>, <code>OrderProcessor</code>, and
- <code>OrderProcessorImpl</code>. These will use some of the domain
- objects from the previous example as well, such as
- <code>Customer</code>.</para>
+ accomplished via the use of JBoss Serialization. This can be useful when
+ don't know which domain objects you may be using in remote calls or if
+ adding ability for remote calls on legacy code.</para>
+
+ <para>To start, there are a few more domain objects: <code>Order</code>,
+ <code>OrderProcessor</code>, and <code>OrderProcessorImpl</code>. These
+ will use some of the domain objects from the previous example as well,
+ such as <code>Customer</code>.</para>
<programlisting>public class <emphasis role="bold">Order</emphasis>
{
@@ -1190,9 +1277,9 @@
<para>The <code>OrderProcessorImpl</code> will take orders, via the
<code>processOrder() </code>method, check that the customer for the
- order has been processed, and if not have the customer processor
- process the new customer. Then will place the order, which means will
- just set the order id and processed attribute to true.</para>
+ order has been processed, and if not have the customer processor process
+ the new customer. Then will place the order, which means will just set
+ the order id and processed attribute to true.</para>
<para>The most important point to this example is that the
<code>Order</code> class does NOT implement
@@ -1318,8 +1405,8 @@
<para>To run this example, can run the Server and then the Client. Or
can go to the examples directory and run the ant target 'ant
- run-transporter-serialization-server' and then in another window run
- the ant target 'ant run-transporter-serialization-client'. For
+ run-transporter-serialization-server' and then in another window run the
+ ant target 'ant run-transporter-serialization-client'. For
example:</para>
<programlisting>ant run-transporter-serialization-server</programlisting>
@@ -1371,9 +1458,8 @@
<para>The client output shows the printout of the newly created order
before calling the <code>OrderProcessor</code> and then the processed
- order afterwards. Noticed that the processed order has its customer's
- id set, its order id set and the processed attribute is set to
- true.</para>
+ order afterwards. Noticed that the processed order has its customer's id
+ set, its order id set and the processed attribute is set to true.</para>
<para>And the output from the <code>Server</code> is:</para>
@@ -1396,8 +1482,8 @@
Order processed. Order id now: 221
</programlisting>
- <para>The server output shows the printout of the customer before
- being processed and then the order while being processed.</para>
+ <para>The server output shows the printout of the customer before being
+ processed and then the order while being processed.</para>
</section>
<section>
@@ -1406,11 +1492,11 @@
<para>In the previous examples, there has been one and only one target
POJO to make calls upon. If that target POJO was not available, the
client call would fail. In the transporter clustered example (found in
- org.jboss.remoting.samples.transporter.clustered package), will show
- how to use the transporter in clustered mode so that if one target
- POJO becomes unavailable, the client call can be seamlessly failed
- over to another available target POJO on the network, regardless of
- network transport type.</para>
+ org.jboss.remoting.samples.transporter.clustered package), will show how
+ to use the transporter in clustered mode so that if one target POJO
+ becomes unavailable, the client call can be seamlessly failed over to
+ another available target POJO on the network, regardless of network
+ transport type.</para>
<para>This example uses the domain objects from the first, basic
example, so only need to cover the client and server code. For this
@@ -1465,18 +1551,18 @@
}
}</programlisting>
- <para>Notice that are now calling on the <code>TransportServer</code>
- to create a server with the locator uri and target POJO
- (<code>CustomerProcessorImpl</code>) as before, but have also added
- the interface type of the target POJO (<code>CustomerProcessor</code>)
- and that want clustering turned on (via the last
- <literal>true</literal> parameter).</para>
-
- <para>The interface type of the target POJO is needed because this
- will be used as the subsystem within the remoting server for the
- target POJO. The subsystem value will be what the client uses to
- determine if discovered remoting server is for the target POJO they
- are looking for.</para>
+ <para>Notice that are now calling on the <code>TransportServer</code> to
+ create a server with the locator uri and target POJO
+ (<code>CustomerProcessorImpl</code>) as before, but have also added the
+ interface type of the target POJO (<code>CustomerProcessor</code>) and
+ that want clustering turned on (via the last <literal>true</literal>
+ parameter).</para>
+
+ <para>The interface type of the target POJO is needed because this will
+ be used as the subsystem within the remoting server for the target POJO.
+ The subsystem value will be what the client uses to determine if
+ discovered remoting server is for the target POJO they are looking
+ for.</para>
<sidebar>
<para>The transporter uses the MulticastDetector from JBoss Remoting
@@ -1488,9 +1574,9 @@
</sidebar>
<para>The second server class is the <code>RMIServer</code> class. The
- <code>RMIServer</code> class extends the <code>SocketServer</code>
- class and uses a different locator uri specify <literal>rmi</literal>
- as the transport protocol and a different port
+ <code>RMIServer</code> class extends the <code>SocketServer</code> class
+ and uses a different locator uri specify <literal>rmi</literal> as the
+ transport protocol and a different port
(<literal>5500</literal>).</para>
<programlisting>public class <emphasis role="bold">RMIServer</emphasis> extends <emphasis
@@ -1525,10 +1611,10 @@
}</programlisting>
<para>The last server class is the <code>HTTPServer</code> class. The
- <code>HTTPServer</code> class also extends the
- <code>SocketServer</code> class and specifies <literal>http</literal>
- as the transport protocol and <literal>5600</literal> as the port to
- listen for requests on.</para>
+ <code>HTTPServer</code> class also extends the <code>SocketServer</code>
+ class and specifies <literal>http</literal> as the transport protocol
+ and <literal>5600</literal> as the port to listen for requests
+ on.</para>
<programlisting>public class <emphasis role="bold">HTTPServer</emphasis> extends <emphasis
role="bold">SocketServer</emphasis>
@@ -1563,13 +1649,12 @@
<para>On the client side, there is only the <code>Client</code> class.
This class is very similar to the one from the basic example. The main
- exceptions are (1) the addition of a <code>TransporterClient</code>
- call to create a transporter client and (2) the fact that it
- continually loops, making calls on its <code>customerProcessor</code>
- variable to process customers. This is done so that when we run the
- client, we can kill the different servers and see that the client
- continues to loop making its calls without any exceptions or
- errors.</para>
+ exceptions are (1) the addition of a <code>TransporterClient</code> call
+ to create a transporter client and (2) the fact that it continually
+ loops, making calls on its <code>customerProcessor</code> variable to
+ process customers. This is done so that when we run the client, we can
+ kill the different servers and see that the client continues to loop
+ making its calls without any exceptions or errors.</para>
<programlisting>public class <emphasis role="bold">Client</emphasis>
{
@@ -1635,19 +1720,19 @@
}</programlisting>
<para>The first item of note is that the locator uri from the
- <code>SocketServer</code> class is being used. Technically, this is
- not required as once the clustered <code>TransporterClient</code> is
+ <code>SocketServer</code> class is being used. Technically, this is not
+ required as once the clustered <code>TransporterClient</code> is
started, it will start to discover the remoting servers that exist on
- the network. However, this process can take several seconds to occur,
- so unless it is known that no calls will be made on the remote proxy
- right away, it is best to bootstrap with a known target server.</para>
+ the network. However, this process can take several seconds to occur, so
+ unless it is known that no calls will be made on the remote proxy right
+ away, it is best to bootstrap with a known target server.</para>
<para>Can also see that in the <code>main()</code> method, the first
call on the Client instance is to <code>getCustomerProcessor()</code>.
This method will call the <code>TransporterClient</code>'s
- <code>createTransporterClient()</code> method and passes the locator
- uri for the target POJO server, the type of POJO's remote proxy, and
- that clustering should be enabled.</para>
+ <code>createTransporterClient()</code> method and passes the locator uri
+ for the target POJO server, the type of POJO's remote proxy, and that
+ clustering should be enabled.</para>
<para>After getting the customer processor remote proxy, will
continually loop making calls using the remote proxy (via the
@@ -1656,9 +1741,9 @@
<para>To run this example, all the servers need to be started (by
running the <code>SocketServer</code>, <code>RMIServer</code>, and
- <code>HTTPServer</code> classes). Then run the Client class. This can
- be done via ant targets as well. So for example, could open four
- console windows and enter the ant targets as follows:</para>
+ <code>HTTPServer</code> classes). Then run the Client class. This can be
+ done via ant targets as well. So for example, could open four console
+ windows and enter the ant targets as follows:</para>
<programlisting>ant run-transporter-clustered-socket-server</programlisting>
@@ -1668,8 +1753,8 @@
<programlisting>ant run-transporter-clustered-client</programlisting>
- <para>Once the client starts running, should start to see output
- logged to the <code>SocketServer</code>, since this is the one used to
+ <para>Once the client starts running, should start to see output logged
+ to the <code>SocketServer</code>, since this is the one used to
bootstrap. This output would look like:</para>
<programlisting>processed customer with new id of 378
@@ -1677,14 +1762,13 @@
processed customer with new id of 980</programlisting>
<para>Once the <code>SocketServer</code> instance has received a few
- calls, kill this instance. The next time the client makes a call on
- its remote proxy, which happens every five seconds, it should fail
- over to another one of the servers (and will see similar output on
- that server instance). After that server has received a few calls,
- kill it and should see it fail over once again to the last server
- instance that is still running. Then, if kill that server instance,
- will see a CannotConnectException and stack trace similar to the
- following:</para>
+ calls, kill this instance. The next time the client makes a call on its
+ remote proxy, which happens every five seconds, it should fail over to
+ another one of the servers (and will see similar output on that server
+ instance). After that server has received a few calls, kill it and
+ should see it fail over once again to the last server instance that is
+ still running. Then, if kill that server instance, will see a
+ CannotConnectException and stack trace similar to the following:</para>
<programlisting><emphasis role="bold">...
org.jboss.remoting.CannotConnectException</emphasis>: Can not connect http client invoker.
@@ -1724,16 +1808,15 @@
... 14 more</programlisting>
<para>since there are no target servers left to make calls on. Notice
- that earlier in the client output there were no errors while was
- failing over to the different servers as they were being
- killed.</para>
+ that earlier in the client output there were no errors while was failing
+ over to the different servers as they were being killed.</para>
<para>Because the CannotConnectException is being caught within the
- while loop, the client will continue to try calling the remote proxy
- and getting this exception. Now re-run any of the previously killed
- servers and will see that the client will discover that server
- instance and begin to successfully call on that server. The output
- should look something like:</para>
+ while loop, the client will continue to try calling the remote proxy and
+ getting this exception. Now re-run any of the previously killed servers
+ and will see that the client will discover that server instance and
+ begin to successfully call on that server. The output should look
+ something like:</para>
<programlisting>...
at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.java:669)
@@ -1764,8 +1847,8 @@
...</programlisting>
<sidebar>
- <para>As demonstrated in this example, fail over can occur across
- any of the JBoss Remoting transports. Clustered transporters is also
+ <para>As demonstrated in this example, fail over can occur across any
+ of the JBoss Remoting transports. Clustered transporters is also
supported using JBoss Serialization, which was introduced in the
previous example.</para>
@@ -1773,9 +1856,9 @@
transporters, clustering means invocation fail over. The JBoss
Remoting transporters themselves do not handle any form of state
replication. If this feature were needed, could use JBoss Cache to
- store the target POJO instances so that when their state changed,
- that change would be replicated to the other target POJO instances
- running in other processes.</para>
+ store the target POJO instances so that when their state changed, that
+ change would be replicated to the other target POJO instances running
+ in other processes.</para>
</sidebar>
</section>
@@ -1784,16 +1867,15 @@
<para>The complex transporter example (found in
org.jboss.remoting.samples.transporter.complex package) is based off a
- test case a user, Milt Grinberg, provided (thanks Milt). The example
- is similar to the previous examples, except in this case involves
- matching Doctors and Patients using the ProviderInterface and provides
- a more complex sample in which to demonstrate how to use
- transporters.</para>
+ test case a user, Milt Grinberg, provided (thanks Milt). The example is
+ similar to the previous examples, except in this case involves matching
+ Doctors and Patients using the ProviderInterface and provides a more
+ complex sample in which to demonstrate how to use transporters.</para>
<para>This example requires JDK 1.5 to run, since is using JBoss
Serialization (and non-serialized data objects). To run this example,
- run the Server class and then the Client class. This can be done via
- ant targets 'run-transporter-complex-server' and then
+ run the Server class and then the Client class. This can be done via ant
+ targets 'run-transporter-complex-server' and then
'run-transporter-complex-server' as well. For example:</para>
<programlisting>ant run-transporter-complex-server</programlisting>
@@ -1857,14 +1939,14 @@
at com.intellij.rt.execution.application.AppMain.main(AppMain.java:86)
</programlisting>
- <para>From the output see the creation of a new patient, Bill Gates,
- and the attempt to find a doctor that specializes in his ailment. For
- Mr. Gates, we were able to find a doctor, Andy Jones, and can see that
- he has been added to the list of Dr. Jones' patients. Then we have Dr.
- Jones retire. Then we create a new patient and try to find an
- available doctor for the same ailment. Since Dr. Jones has retired,
- and there are no other doctors that specialize in that particular
- ailment, an exception is thrown. This is as expected.</para>
+ <para>From the output see the creation of a new patient, Bill Gates, and
+ the attempt to find a doctor that specializes in his ailment. For Mr.
+ Gates, we were able to find a doctor, Andy Jones, and can see that he
+ has been added to the list of Dr. Jones' patients. Then we have Dr.
+ Jones retire. Then we create a new patient and try to find an available
+ doctor for the same ailment. Since Dr. Jones has retired, and there are
+ no other doctors that specialize in that particular ailment, an
+ exception is thrown. This is as expected.</para>
</section>
</section>
@@ -1873,8 +1955,8 @@
xreflabel="Multiplex invokers">Multiplex invokers</title>
<para>This section illustrates the construction of multiplex invoker
- groups described in the section <xref linkend="section-multiplex" />.
- The directory</para>
+ groups described in the section <xref linkend="section-multiplex" />. The
+ directory</para>
<blockquote>
<para><code>examples/org/jboss/remoting/samples/multiplex/invoker</code></para>
@@ -1882,13 +1964,12 @@
<para>contains a server class,
<classname>MultiplexInvokerServer</classname>, which is suitable for use
- with any of the client classes described below. It may be run in an IDE
- or from the command line using ant target
- <code>run-multiplex-server</code> from the <code>build.xml</code> file
- found in the <code>examples</code> directory. The server will stay
- alive, processing invocation requests as they are presented, until it
- has sent two push callbacks to however many listeners are registered, at
- which time it will shut itself down.</para>
+ with any of the client classes described below. It may be run in an IDE or
+ from the command line using ant target <code>run-multiplex-server</code>
+ from the <code>build.xml</code> file found in the <code>examples</code>
+ directory. The server will stay alive, processing invocation requests as
+ they are presented, until it has sent two push callbacks to however many
+ listeners are registered, at which time it will shut itself down.</para>
<para>The sample clients are as follows. Each sample client
<emphasis><client></emphasis> may be run in an IDE or by using the
@@ -1900,8 +1981,8 @@
<para><classname>Client2Server1</classname>: A
<classname>MultiplexClientInvoker</classname> starts according to
client rule 2, after which a
- <classname>MultiplexServerInvoker</classname> is started according
- to server rule 1. Note that the <classname>Client</classname> and
+ <classname>MultiplexServerInvoker</classname> is started according to
+ server rule 1. Note that the <classname>Client</classname> and
<classname>Connector</classname> are passed matching
<emphasis>clientMultiplexId</emphasis> and
<emphasis>serverMultiplexId</emphasis> parameters,
@@ -1912,23 +1993,21 @@
<para><classname>Client2Server2</classname>: A
<classname>MultiplexClientInvoker</classname> starts according to
client rule 2, after which a
- <classname>MultiplexServerInvoker</classname> is started according
- to server rule 2. Note that no
- <emphasis>clientMultiplexId</emphasis> is passed to the
- <classname>Client</classname> and no
+ <classname>MultiplexServerInvoker</classname> is started according to
+ server rule 2. Note that no <emphasis>clientMultiplexId</emphasis> is
+ passed to the <classname>Client</classname> and no
<emphasis>serverMultiplexId</emphasis> parameter is passed to the
<classname>Connector</classname> in this example.</para>
</listitem>
<listitem>
<para><classname>Client3Server1</classname>: A
- <classname>MultiplexClientInvoker</classname> is created, and,
- lacking binding information, finds itself governed by client rule 3.
+ <classname>MultiplexClientInvoker</classname> is created, and, lacking
+ binding information, finds itself governed by client rule 3.
Subsequently, a <classname>MultiplexServerInvoker</classname> is
- started according to server rule 1, providing the binding
- information which allows the
- <classname>MultiplexClientInvoker</classname> to start. Note that
- the <classname>Client</classname> and
+ started according to server rule 1, providing the binding information
+ which allows the <classname>MultiplexClientInvoker</classname> to
+ start. Note that the <classname>Client</classname> and
<classname>Connector</classname> are passed matching
<emphasis>clientMultiplexId</emphasis> and
<emphasis>serverMultiplexId</emphasis> parameters,
@@ -1939,8 +2018,8 @@
<para><classname>Server2Client1</classname>: A
<classname>MultiplexServerInvoker</classname> starts according to
server rule 2, after which a
- <classname>MultiplexClientInvoker</classname> is started according
- to client rule 1. Note that the <classname>Connector</classname> and
+ <classname>MultiplexClientInvoker</classname> is started according to
+ client rule 1. Note that the <classname>Connector</classname> and
<classname>Client</classname> are passed matching
<emphasis>serverMultiplexId</emphasis> and
<emphasis>clientMultiplexId</emphasis> parameters,
@@ -1951,23 +2030,21 @@
<para><classname>Server2Client2</classname>: A
<classname>MultiplexServerInvoker</classname> starts according to
server rule 2, after which a
- <classname>MultiplexClientInvoker</classname> is started according
- to client rule 2. Note that no
- <emphasis>serverMultiplexId</emphasis> is passed to the
- <classname>Connector</classname> and no
+ <classname>MultiplexClientInvoker</classname> is started according to
+ client rule 2. Note that no <emphasis>serverMultiplexId</emphasis> is
+ passed to the <classname>Connector</classname> and no
<emphasis>clientMultiplexId</emphasis> parameter is passed to the
<classname>Client</classname> in this example.</para>
</listitem>
<listitem>
<para><classname>Server3Client1</classname>: A
- <classname>MultiplexServerInvoker</classname> is created, and,
- lacking connect information, finds itself governed by server rule 3.
+ <classname>MultiplexServerInvoker</classname> is created, and, lacking
+ connect information, finds itself governed by server rule 3.
Subsequently, a <classname>MultiplexClientInvoker</classname> is
- started according to client rule 1, providing the connect
- information which allows the
- <classname>MultiplexServerInvoker</classname> to start. Note that
- the <classname>Connector</classname> and
+ started according to client rule 1, providing the connect information
+ which allows the <classname>MultiplexServerInvoker</classname> to
+ start. Note that the <classname>Connector</classname> and
<classname>Client</classname> are passed matching
<emphasis>serverMultiplexId</emphasis> and
<emphasis>clientMultiplexId</emphasis> parameters,
@@ -1977,7 +2054,7 @@
<para>For variety, the examples in which the client invoker starts first
use the configuration <classname>Map</classname> to pass invoker group
- parameters, and the examples in which the server invoker starts first
- pass parameters in the <classname>InvokerLocator</classname>.</para>
+ parameters, and the examples in which the server invoker starts first pass
+ parameters in the <classname>InvokerLocator</classname>.</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