[jboss-remoting-commits] JBoss Remoting SVN: r4237 - remoting2/branches/2.x/docs/guide/en.

Author: ron.sigal(a)jboss.com Date: 2008-05-27 19:57:45 -0400 (Tue, 27 May 2008) New Revision: 4237 Modified: remoting2/branches/2.x/docs/guide/en/chap1.xml remoting2/branches/2.x/docs/guide/en/chap11.xml remoting2/branches/2.x/docs/guide/en/chap13.xml remoting2/branches/2.x/docs/guide/en/chap14.xml remoting2/branches/2.x/docs/guide/en/chap16.xml remoting2/branches/2.x/docs/guide/en/chap3.xml remoting2/branches/2.x/docs/guide/en/chap4.xml remoting2/branches/2.x/docs/guide/en/chap5.xml remoting2/branches/2.x/docs/guide/en/chap6.xml remoting2/branches/2.x/docs/guide/en/chap8.xml remoting2/branches/2.x/docs/guide/en/chap9.xml remoting2/branches/2.x/docs/guide/en/master.xml Log: JBREM-840: Changes for version 2.4. Modified: remoting2/branches/2.x/docs/guide/en/chap1.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap1.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap1.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -3,7 +3,7 @@ <title>Overview</title> <section> - <title>What is JBoss Remoting</title> + <title>What is JBoss Remoting?</title> <para>The purpose of JBoss Remoting is to provide a single API for most network based invocations and related service that uses pluggable @@ -52,17 +52,13 @@ <listitem> <para>HTTP(S)</para> </listitem> - + <listitem> - <para>Multiplex (SSL Multiplex)</para> - </listitem> - - <listitem> <para>Servlet (SSL Servlet)</para> </listitem> <listitem> - <para>BiSocket (SSL BiSocket)</para> + <para>Bisocket (SSL Bisocket)</para> </listitem> </itemizedlist> </listitem> @@ -171,10 +167,40 @@ <title>How to get JBoss Remoting</title> <para>The JBossRemoting distribution can be downloaded from <ulink - url="http://labs.jboss.com/portal/jbossremoting"> - http://labs.jboss.com/portal/jbossremoting</ulink> . This distribution + url="http://www.jboss.org/jbossremoting/"> + http://www.jboss.org/jbossremoting/</ulink> . This distribution contains everything needed to run JBossRemoting stand alone. The distribution includes binaries, source, documentation, javadoc, and sample code.</para> </section> + + <section> + <title>What's new in version 2.4?</title> + + <para>JBossRemoting 2.4.0.GA is an incremental release, with dozens of bug fixes and several new features: + </para> + + <itemizedlist> + <listitem> + <para>servers can be bound to multiple IP addresses</para> + </listitem> + <listitem> + <para>can run in the presence of a security manager</para> + </listitem> + <listitem> + <para>greater configurability</para> + </listitem> + <listitem> + <para>supports IPv6 addresses</para> + </listitem> + <listitem> + <para>improved connection monitoring</para> + </listitem> + <listitem> + <para>server gets client address in invocations</para> + </listitem> + + </itemizedlist> + + </section> </chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap11.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap11.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap11.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -1,23 +1,2634 @@ - <chapter> - <title>Client programming model</title> +<?xml version="1.0" encoding="UTF-8"?> +<chapter> + <title>How to use it - sample code</title> - <para>The approach taken for the programming model on the client side is - one based on a session based model. This means that it is expected that - once a Client is created for a particular target server, it will be used - exclusively to make calls on that server. This expectation dictates some - of the behavior of the remoting client.</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> - <para>For example, if create a Client on the client side to make server - invocations, including adding callback listeners, will have to use that - same instance of Client to remove the callback listeners. This is because - the Client creates a unique session id that it passes within the calls to - the server. This id is used as part of the key for registering callback - listeners on the server. If create a new Client instance and attempt to - remove the callback listeners, a new session id will be passed to the - server invoker, who will not recognize the callback listener to be - removed.</para> + <section> + <title>Simple invocation</title> - <para>See test case - <code>org.jboss.test.remoting.callback.push.MultipleCallbackServersTestCase</code> - .</para> - </chapter> \ No newline at end of file + <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> + + <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> + + <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> + + <para><programlisting>ant run-simple-server</programlisting>ant + then:</para> + + <para><programlisting>ant run-simple-client</programlisting>The output + when running the SimpleClient should look like:</para> + + <programlisting>Calling remoting server with locator uri of: socket://localhost:5400 +Invoking server with request of 'Do something' +Invocation response: This is the return to SampleInvocationHandler invocation</programlisting> + + <para>The output when running the SimpleServer should look like:</para> + + <programlisting>Starting remoting server with locator uri of: socket://localhost:5400 +Invocation request is: Do something +Returning response of: This is the return to SampleInvocationHandler invocation</programlisting> + + <para>Note: will have to manually shut down the SimpleServer once + started.</para> + </section> + + <section> + <title>HTTP invocation</title> + + <para>This http invocation sample (found in the + org.jboss.remoting.samples.http package), demonstrates how the http + invoker can be used for a variety of http based invocations. This time, + 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> + + <programlisting>public class <emphasis role="bold">WebInvocationHandler</emphasis> implements <emphasis + role="bold">ServerInvocationHandler</emphasis> +{ + // Pre-defined returns to be sent back to client based on type of request. + public static final String RESPONSE_VALUE = "This is the return to simple text based http invocation."; + public static final ComplexObject OBJECT_RESPONSE_VALUE = new ComplexObject(5, "dub", false); + public static final String HTML_PAGE_RESPONSE = "&lt;html&gt;&lt;head&gt;&lt;title&gt;Test HTML page&lt;/title&gt;&lt;/head&gt;&lt;body&gt;" + + "&lt;h1&gt;HTTP/Servlet Test HTML page&lt;/h1&gt;&lt;p&gt;This is a simple page served for test." + + "&lt;p&gt;Should show up in browser or via invoker client&lt;/body&gt;&lt;/html&gt;"; + + // Different request types that client may make + public static final String NULL_RETURN_PARAM = "return_null"; + public static final String OBJECT_RETURN_PARAM = "return_object"; + public static final String STRING_RETURN_PARAM = "return_string"; + + + /** + * called to handle a specific invocation + * + * @param invocation + * @return + * @throws Throwable + */ + <emphasis role="bold">public Object invoke(InvocationRequest invocation) throws Throwable + { + // Print out the invocation request + System.out.println("Invocation request from client is: " + invocation.getParameter()); + if(NULL_RETURN_PARAM.equals(invocation.getParameter())) + { + return null; + } + else if(invocation.getParameter() instanceof ComplexObject) + { + return OBJECT_RESPONSE_VALUE; + } + else if(STRING_RETURN_PARAM.equals(invocation.getParameter())) + { + Map responseMetadata = invocation.getReturnPayload(); + responseMetadata.put(HTTPMetadataConstants.RESPONSE_CODE, new Integer(207)); + responseMetadata.put(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, "Custom response code and message from remoting server"); + // Just going to return static string as this is just simple example code. + return RESPONSE_VALUE; + } + else + { + return HTML_PAGE_RESPONSE; + }</emphasis> + } +</programlisting> + + <para>The most interesting part of the WebInvocationHandler is its + 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> + + <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> + + <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> + + <programlisting>public class <emphasis role="bold">SimpleClient</emphasis> +{ + // Default locator values + private static String transport = "<emphasis role="bold">http</emphasis>"; + private static String host = "localhost"; + private static int port = 5400; + + public void makeInvocation(String locatorURI) throws Throwable + { + // create InvokerLocator with the url type string + // indicating the target remoting server to call upon. + InvokerLocator locator = new InvokerLocator(locatorURI); + System.out.println("Calling remoting server with locator uri of: " + locatorURI); + + Client remotingClient = new Client(locator); + + // make invocation on remoting server and send complex data object + // by default, the remoting http client invoker will use method type of POST, + // which is needed when ever sending objects to the server. So no metadata map needs + // to be passed to the invoke() method. + <emphasis role="bold">Object response = remotingClient.invoke(new ComplexObject(2, "foo", true), null);</emphasis> + + System.out.println("\nResponse from remoting http server when making http POST request and sending a complex data object:\n" + response); + + + <emphasis role="bold">Map metadata = new HashMap();</emphasis> + // set the metadata so remoting client knows to use http GET method type + <emphasis role="bold">metadata.put("TYPE", "GET");</emphasis> + // not actually sending any data to the remoting server, just want to get its response + <emphasis role="bold">response = remotingClient.invoke((Object) null, metadata);</emphasis> + + System.out.println("\nResponse from remoting http server when making GET request:\n" + response); + + // now set type back to POST and send a plain text based request + <emphasis role="bold">metadata.put("TYPE", "POST");</emphasis> + <emphasis role="bold">response = remotingClient.invoke(WebInvocationHandler.STRING_RETURN_PARAM, metadata);</emphasis> + + System.out.println("\nResponse from remoting http server when making http POST request and sending a text based request:\n" + response); + + // notice are getting custom response code and message set by web invocation handler + <emphasis role="bold">Integer responseCode = (Integer) metadata.get(HTTPMetadataConstants.RESPONSE_CODE); + String responseMessage = (String) metadata.get(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE);</emphasis> + System.out.println("Response code from server: " + responseCode); + System.out.println("Response message from server: " + responseMessage); + + } +</programlisting> + + <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> + + <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 + to be changed from the default, which is POST, to be GET. Then make the + invocation with a null payload (since not wanting to send any data, just + 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>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 + the examples directory and run the ant target 'run-http-server' and then + in another console window run the ant target 'run-http-client'. For + example:</para> + + <programlisting>ant run-http-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-http-client</programlisting> + + <para>The output when running the SimpleClient should look like:</para> + + <programlisting>Response from remoting http server when making http POST request and sending a complex data object: +ComplexObject (i = 5, s = dub, b = false, bytes.length = 0) + +Response from remoting http server when making GET request: +&lt;html&gt;&lt;head&gt;&lt;title&gt;Test HTML page&lt;/title&gt;&lt;/head&gt;&lt;body&gt;&lt;h1&gt;HTTP/Servlet Test HTML page&lt;/h1&gt;&lt;p&gt;This is a simple page served for test.&lt;p&gt;Should show up in browser or via invoker client&lt;/body&gt;&lt;/html&gt; + +Response from remoting http server when making http POST request and sending a text based request: +This is the return to simple text based http invocation. +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>The output from the SimpleServer should look like:</para> + + <programlisting>Starting remoting server with locator uri of: http://localhost:5400 +Jan 26, 2006 11:39:53 PM org.apache.coyote.http11.Http11BaseProtocol init +INFO: Initializing Coyote HTTP/1.1 on http-127.0.0.1-5400 +Jan 26, 2006 11:39:53 PM org.apache.coyote.http11.Http11BaseProtocol start +INFO: Starting Coyote HTTP/1.1 on http-127.0.0.1-5400 +Invocation request from client is: ComplexObject (i = 2, s = foo, b = true, bytes.length = 0) +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>Since the SimpleServer should still be running, can open a web + browser and enter the locator uri, http://localhost:5400. This should + cause the browser to render the html returned from the + WebInvocationHandler.</para> + </section> + + <section> + <title>Oneway invocation</title> + + <para>The oneway invocation sample (found in the + org.jboss.remoting.samples.oneway package) is very similar to the simple + 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 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 + 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> + + <programlisting>ant run-oneway-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-oneway-client</programlisting> + + <para>The output when running the OnewayClient should look like:</para> + + <programlisting>Calling remoting server with locator uri of: socket://localhost:5400 +Making oneway invocation with payload of 'Oneway call 1.' +Making oneway invocation with payload of 'Oneway call 2.'</programlisting> + + <para>The output when running the OnewayServer should look like:</para> + + <programlisting>Starting remoting server with locator uri of: socket://localhost:5400 +Invocation request is: Oneway call 1. +Invocation request is: Oneway call 2.</programlisting> + + <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> + </section> + + <section> + <title>Discovery and invocation</title> + + <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> + + <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> + + <para>In this particular example, the SimpleDetectorClient is registered + with the NetworkRegistry as a notification listener. When it receives + notifications from the NetworkRegistry (via the handleNotification() + method), it will check to see if the notification is for adding or + removing a remoting server. If it is for adding a remoting server, the + SimpleDetectorClient will get the array of InvokerLocators from the + NetworkNotification and make a remote call for each. If the notification + is for removing a remoting server, the SimpleDetectorClient will simply + print out a message saying which server has been removed.</para> + + <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 + 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> + + <programlisting>ant run-detector-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-detector-client</programlisting> + + <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 +Fri Jan 13 09:36:50 EST 2006: [CLIENT]: NetworkRegistry has added the client as a listener +Fri Jan 13 09:36:50 EST 2006: [CLIENT]: MulticastDetector has been created and is listening for new NetworkRegistries to come online +Fri Jan 13 09:36:50 EST 2006: [CLIENT]: GOT A NETWORK-REGISTRY NOTIFICATION: jboss.network.server.added +Fri Jan 13 09:36:50 EST 2006: [CLIENT]: New server(s) have been detected - getting locators and sending welcome messages +Fri Jan 13 09:36:50 EST 2006: [CLIENT]: Sending welcome message to remoting server with locator uri of: socket://127.0.0.1:5400/ +Fri Jan 13 09:36:50 EST 2006: [CLIENT]: The newly discovered server sent this response to our welcome message: Received your welcome message. Thank you!</programlisting> + + <para>The output when running the SimpleDetectorServer should look + like:</para> + + <programlisting>Fri Jan 13 09:36:46 EST 2006: [SERVER]: Starting JBoss/Remoting server... to stop this server, kill it manually via Control-C +Fri Jan 13 09:36:46 EST 2006: [SERVER]: This server's endpoint will be: socket://localhost:5400 +Fri Jan 13 09:36:46 EST 2006: [SERVER]: MulticastDetector has been created and is listening for new NetworkRegistries to come online +Fri Jan 13 09:36:46 EST 2006: [SERVER]: Starting remoting server with locator uri of: socket://localhost:5400 +Fri Jan 13 09:36:46 EST 2006: [SERVER]: Added our invocation handler; we are now ready to begin accepting messages from clients +Fri Jan 13 09:36:50 EST 2006: [SERVER]: RECEIVED A CLIENT MESSAGE: Welcome Aboard! +Fri Jan 13 09:36:50 EST 2006: [SERVER]: Returning the following message back to the client: Received your welcome message. Thank you!</programlisting> + + <para>At this point, try stopping the SimpleDetectorServer (notice that + the SimpleDetectorClient should still be running). After a few seconds, + the client detector should detect that the server is no longer available + and will see something like the following appended in the + SimpleDetectorClient console window:</para> + + <programlisting>Fri Jan 13 09:37:04 EST 2006: [CLIENT]: GOT A NETWORK-REGISTRY NOTIFICATION: jboss.network.server.removed +Fri Jan 13 09:37:04 EST 2006: [CLIENT]: It has been detected that a server has gone down with a locator of: InvokerLocator [socket://127.0.0.1:5400/]</programlisting> + </section> + + <section> + <title>Callbacks</title> + + <para>The callback sample (found in the + org.jboss.remoting.samples.callback package) illustrates how to perform + 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 + 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 + callback. This sample demonstrates how to do both pull and push + callbacks.</para> + + <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> + + <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 + 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 + listener to handle the newly created callback. Have also added + implementation to the addListener() and removeListener() methods where + will either add or remove specified callback listener from the internal + callback listener list and set the shouldGenerateCallbacks flag + accordingly. The invoke() method remains the same as in previous + samples.</para> + + <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> + + <programlisting>ant run-callback-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-callback-client</programlisting> + + <para>The output in the CallbackClient console window should look + like:</para> + + <programlisting>Calling remoting server with locator uri of: socket://localhost:5400 +Invocation response: This is the return to SampleInvocationHandler invocation +Pull Callback value = Callback 1: This is the payload of callback invocation. +Pull Callback value = Callback 2: This is the payload of callback invocation. +Starting remoting server with locator uri of: InvokerLocator [socket://127.0.0.1:5401/] +Received push callback. +Received callback value of: Callback 3: This is the payload of callback invocation. +Received callback handle object of: myCallbackHandleObject +Received callback server invoker of: InvokerLocator [socket://127.0.0.1:5400/] +Received push callback. +Received callback value of: Callback 4: This is the payload of callback invocation. +Received callback handle object of: myCallbackHandleObject +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> + + <para>The output in the CallbackServer console window should look + like:</para> + + <programlisting>Starting remoting server with locator uri of: socket://localhost:5400 +Adding callback listener. +Invocation request is: Do something +Removing callback listener. +Adding callback listener. +Removing callback listener. </programlisting> + + <para>This output shows two distinct callback handlers being added and + removed (with an invocation request being received after the first was + added).</para> + + <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> + </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>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> + + <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> + + <para>To run this example, can compile both the StreamingClient and + StreamingServer class, then run the StreamingServer and then the + StreamingClient. Or can go to the examples directory and run the ant + target 'run-stream-server' and then in another window run the ant target + 'run-stream-client'. For example:</para> + + <programlisting>ant run-stream-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-stream-client</programlisting> + + <para>The output in the StreamingClient console window should look + like:</para> + + <programlisting>Calling on remoting server with locator uri of: socket://localhost:5400 +Sending input stream for file sample.txt to server. +Size of file sample.txt is 987 +Server returned 987 as the size of the file read.</programlisting> + + <para>The output in the StreamingServer console window should look + like:</para> + + <programlisting>Starting remoting server with locator uri of: socket://localhost:5400 +Received input stream from client to write out to file server_sample.txt +Read stream of size 987. Now writing to server_sample.txt +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> + </section> + + <section> + <title>JBoss Serialization</title> + + <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 + 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> + + <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 + class.</para> + + <para>To run this example, can compile both the SerializationClient and + SerializationServer class, then run the SerializationServer and then the + SerializationClient. Or can go to the examples directory and run the ant + target 'run-serialization-server' and then in another window run the ant + target 'run-serialization-client'. For example:</para> + + <programlisting>ant run-serialization-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-serialization-client</programlisting> + + <para>The output in the SerializationClient console window should look + like:</para> + + <programlisting>Calling remoting server with locator uri of: socket://localhost:5400/?serializationtype=jboss +Invoking server with request of 'NonSerializablePayload - name: foo, id: 1' +Invocation response: NonSerializablePayload - name: bar, id: 2</programlisting> + + <para>The output in the SerializationServer console window should look + like:</para> + + <programlisting>Starting remoting server with locator uri of: socket://localhost:5400/?serializationtype=jboss +Invocation request is: NonSerializablePayload - name: foo, id: 1 +Returning response of: NonSerializablePayload - name: bar, id: 2</programlisting> + + <para>Note: will have to manually shut down the SerializationServer once + started.</para> + </section> + + <section> + <title>Transporters</title> + + <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>Transporters sample - simple</title> + + <para>The simple transporter example (found in + org.jboss.remoting.samples.transporter.simple package) demonstrates a + very simple example of how to use the transporters to expose a plain old + java object for remote method invocations.</para> + + <para>In this simple transporter example, will be taking a class that + formats a java.util.Date into a simple String representation and + exposing it so can call on the remotely. The target object in this case, + org.jboss.remoting.samples.transporter.simple.DateProcessorImpl, + implements the + org.jboss.remoting.samples.transporter.simple.DateProcessor interfaces + (as shown below):</para> + + <programlisting>public interface DateProcessor +{ + public String formatDate(Date dateToConvert); +} + + +public class DateProcessorImpl implements DateProcessor +{ + public String formatDate(Date dateToConvert) + { + DateFormat dateFormat = DateFormat.getDateInstance(DateFormat.MEDIUM); + return dateFormat.format(dateToConvert); + } +}</programlisting> + + <para>This is then exposed using the TransporterServer by the + org.jboss.remoting.samples.transporter.simple.Server class.</para> + + <programlisting>public class Server +{ + public static void main(String[] args) throws Exception + { + TransporterServer server = TransporterServer.createTransporterServer("socket://localhost:5400", new DateProcessorImpl(), DateProcessor.class.getName()); + Thread.sleep(10000); + server.stop(); + } +}</programlisting> + + <para>The Server class simply creates a TransporterServer by indicating + the locator url would like to use for the remoting server, a newly + created instance of DataProcessorImpl, and the interface type would like + to expose remotely. The TransporterServer returned from the + createTransporterServer call is live and ready to receive incoming + method invocation requests. Will then wait 10 seconds for a request, + then stop the server.</para> + + <para>Next need to have client to make the remote invocation. This can + be found within + org.jboss.remoting.samples.transporter.simple.Client.</para> + + <programlisting>public class Client +{ + public static void main(String[] args) throws Exception + { + DateProcessor dateProcessor = (DateProcessor) TransporterClient.createTransporterClient("socket://localhost:5400", DateProcessor.class); + String formattedDate = dateProcessor.formatDate(new Date()); + System.out.println("Current date: " + formattedDate); + } +}</programlisting> + + <para>In the Client class, create a TransporterClient which can be cast + to the desired type, which is DataProcessor in this case. In calling the + createTransporterClient, need to specify the locator ulr (same as was + used for the TransporterServer), and the interface type will be calling + on for the target pojo. Once have the DateProcessor variable, will make + the call to formatDate() and pass a newly created Date object. The + return will be a formated String of the date passed.</para> + + <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 + 'run-transporter-simple-server' and then in another window run the ant + target 'run-transporter-simple-client'. For example:</para> + + <programlisting>ant run-transporter-simple-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-transporter-simple-client</programlisting> + + <para>The output from the client window should look similar to:</para> + + <programlisting>Current date: Jul 31, 2006</programlisting> + </section> + + <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> + + <para>In this basic transporter example, will be using a few domain + objects; <code>Customer</code> and Address, which are just data + objects.</para> + + <programlisting>public class <emphasis role="bold">Customer</emphasis> implements Serializable +{ + private String firstName = null; + private String lastName = null; + private Address addr = null; + private int customerId = -1; + + public String getFirstName() + { + return firstName; + } + + public void setFirstName(String firstName) + { + this.firstName = firstName; + } + + public String getLastName() + { + return lastName; + } + + public void setLastName(String lastName) + { + this.lastName = lastName; + } + + public Address getAddr() + { + return addr; + } + + public void setAddr(Address addr) + { + this.addr = addr; + } + + public int getCustomerId() + { + return customerId; + } + + public void setCustomerId(int customerId) + { + this.customerId = customerId; + } + + public String toString() + { + StringBuffer buffer = new StringBuffer(); + buffer.append("\nCustomer:\n"); + buffer.append("customer id: " + customerId + "\n"); + buffer.append("first name: " + firstName + "\n"); + buffer.append("last name: " + lastName + "\n"); + buffer.append("street: " + addr.getStreet() + "\n"); + buffer.append("city: " + addr.getCity() + "\n"); + buffer.append("state: " + addr.getState() + "\n"); + buffer.append("zip: " + addr.getZip() + "\n"); + + return buffer.toString(); + } +}</programlisting> + + <programlisting>public class <emphasis role="bold">Address</emphasis> implements Serializable +{ + private String street = null; + private String city = null; + private String state = null; + private int zip = -1; + + public String getStreet() + { + return street; + } + + public void setStreet(String street) + { + this.street = street; + } + + public String getCity() + { + return city; + } + + public void setCity(String city) + { + this.city = city; + } + + public String getState() + { + return state; + } + + public void setState(String state) + { + this.state = state; + } + + public int getZip() + { + return zip; + } + + public void setZip(int zip) + { + this.zip = zip; + } +}</programlisting> + + <para>Next comes the POJO that we want to expose a remote proxy for, + which is <code>CustomerProcessorImpl</code> class. This implementation + has one method to process a <code>Customer</code> object. It also + implements the <code>CustomerProcessor</code> interface.</para> + + <programlisting>public class <emphasis role="bold">CustomerProcessorImpl</emphasis> implements <emphasis + role="bold">CustomerProcessor</emphasis> +{ + /** + * Takes the customer passed, and if not null and customer id + * is less than 0, will create a new random id and set it. + * The customer object returned will be the modified customer + * object passed. + * + * @param customer + * @return + */ + public Customer processCustomer(Customer customer) + { + if(customer != null &amp;&amp; customer.getCustomerId() &lt; 0) + { + customer.setCustomerId(new Random().nextInt(1000)); + } + System.out.println("processed customer with new id of " + customer.getCustomerId()); + return customer; + } +}</programlisting> + + <programlisting>public interface <emphasis role="bold">CustomerProcessor</emphasis> +{ + /** + * Process a customer object. Implementors + * should ensure that the customer object + * passed as parameter should have its internal + * state changed somehow and returned. + * + * @param customer + * @return + */ + 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 + invoke on the target POJO. This is where the transporter comes + in.</para> + + <programlisting>public class <emphasis role="bold">Server</emphasis> +{ + private String locatorURI = "socket://localhost:5400"; + private TransporterServer server = null; + + public void start() throws Exception + { + server = <emphasis role="bold">TransporterServer.createTransporterServer(locatorURI, new CustomerProcessorImpl())</emphasis>; + } + + public void stop() + { + if(server != null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server = new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +}</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>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> + + <para>Next up is the client side. This is represented by the + <code>Client</code> class.</para> + + <programlisting>public class <emphasis role="bold">Client</emphasis> +{ + private String locatorURI = "socket://localhost:5400"; + + public void makeClientCall() throws Exception + { + Customer customer = createCustomer(); + + <emphasis role="bold">CustomerProcessor customerProcessor = (CustomerProcessor) TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class);</emphasis> + + System.out.println("Customer to be processed: " + customer); + <emphasis role="bold">Customer processedCustomer = customerProcessor.processCustomer(customer);</emphasis> + System.out.println("Customer is now: " + processedCustomer); + + <emphasis role="bold">TransporterClient.destroyTransporterClient(customerProcessor);</emphasis> + } + + private Customer createCustomer() + { + Customer cust = new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr = new Address(); + addr.setStreet("101 Oak Street"); + addr.setCity("Atlanata"); + addr.setState("GA"); + addr.setZip(30249); + cust.setAddr(addr); + + return cust; + } + + public static void main(String[] args) + { + Client client = new Client(); + try + { + client.makeClientCall(); + } + catch(Exception e) + { + e.printStackTrace(); + } + } +}</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>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> + + <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 + used.</para> + + <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 + 'run-transporter-basic-server' and then in another window run the ant + target 'run-transporter-basic-client'. For example:</para> + + <programlisting>ant run-transporter-basic-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-transporter-basic-client</programlisting> + + <para>The output from the Client console should be similar to:</para> + + <programlisting>Customer to be processed: +Customer: +customer id: -1 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanata +state: GA +zip: 30249 + +Customer is now: +Customer: +customer id: 204 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanata +state: GA +zip: 30249 + +</programlisting> + + <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> + </section> + + <section> + <title>Transporter sample - JBoss serialization</title> + + <para>The transporter serialization example (found in + 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> + + <programlisting>public class <emphasis role="bold">Order</emphasis> +{ + private int orderId = -1; + private boolean isProcessed = false; + private Customer customer = null; + private List items = null; + + + public int getOrderId() + { + return orderId; + } + + public void setOrderId(int orderId) + { + this.orderId = orderId; + } + + public boolean isProcessed() + { + return isProcessed; + } + + public void setProcessed(boolean processed) + { + isProcessed = processed; + } + + public Customer getCustomer() + { + return customer; + } + + public void setCustomer(Customer customer) + { + this.customer = customer; + } + + public List getItems() + { + return items; + } + + public void setItems(List items) + { + this.items = items; + } + + public String toString() + { + StringBuffer buffer = new StringBuffer(); + buffer.append("\nOrder:\n"); + buffer.append("\nIs processed: " + isProcessed); + buffer.append("\nOrder id: " + orderId); + buffer.append(customer.toString()); + + buffer.append("\nItems ordered:"); + Iterator itr = items.iterator(); + while(itr.hasNext()) + { + buffer.append("\n" + itr.next().toString()); + } + + return buffer.toString(); + } +}</programlisting> + + <programlisting>public class <emphasis role="bold">OrderProcessorImpl</emphasis> implements <emphasis + role="bold">OrderProcessor</emphasis> +{ + private CustomerProcessor customerProcessor = null; + + public OrderProcessorImpl() + { + customerProcessor = new CustomerProcessorImpl(); + } + + public Order processOrder(Order order) + { + System.out.println("Incoming order to process from customer.\n" + order.getCustomer()); + + // has this customer been processed? + if(order.getCustomer().getCustomerId() &lt; 0) + { + order.setCustomer(customerProcessor.processCustomer(order.getCustomer())); + } + + List items = order.getItems(); + System.out.println("Items ordered:"); + Iterator itr = items.iterator(); + while(itr.hasNext()) + { + System.out.println(itr.next()); + } + + order.setOrderId(new Random().nextInt(1000)); + order.setProcessed(true); + + System.out.println("Order processed. Order id now: " + order.getOrderId()); + return order; + } +}</programlisting> + + <programlisting>public interface OrderProcessor +{ + public Order processOrder(Order order); +}</programlisting> + + <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> + + <para>The most important point to this example is that the + <code>Order</code> class does NOT implement + <code>java.io.Serializable</code>.</para> + + <para>Now onto the <code>Server</code> class. This is just like the + previous <code>Server</code> class in the basic example with one main + difference: the <code>locatorURI</code> value.</para> + + <programlisting>public class <emphasis role="bold">Server</emphasis> +{ + private String locatorURI = "socket://localhost:5400/?<emphasis role="bold">serializationtype=jboss</emphasis>"; + private TransporterServer server = null; + + public void start() throws Exception + { + server = TransporterServer.createTransporterServer(locatorURI, new OrderProcessorImpl()); + } + + public void stop() + { + if(server != null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server = new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +}</programlisting> + + <para>The addition of <literal>serializationtype=jboss</literal> tells + the remoting framework to use JBoss Serialization in place of the + standard java serialization.</para> + + <para>On the client side, there is the <code>Client</code> class, just + as in the previous basic example.</para> + + <programlisting>public class <emphasis role="bold">Client</emphasis> +{ + private String locatorURI = "socket://localhost:5400/?<emphasis role="bold">serializationtype=jboss</emphasis>"; + + public void makeClientCall() throws Exception + { + Order order = createOrder(); + + OrderProcessor orderProcessor = (OrderProcessor) TransporterClient.createTransporterClient(locatorURI, OrderProcessor.class); + + System.out.println("Order to be processed: " + order); + Order changedOrder = orderProcessor.processOrder(order); + System.out.println("Order now processed " + changedOrder); + + TransporterClient.destroyTransporterClient(orderProcessor); + + } + + private Order createOrder() + { + Order order = new Order(); + Customer customer = createCustomer(); + order.setCustomer(customer); + + List items = new ArrayList(); + items.add("Xbox 360"); + items.add("Wireless controller"); + items.add("Ghost Recon 3"); + + order.setItems(items); + + return order; + } + + private Customer createCustomer() + { + Customer cust = new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr = new Address(); + addr.setStreet("101 Oak Street"); + addr.setCity("Atlanata"); + addr.setState("GA"); + addr.setZip(30249); + cust.setAddr(addr); + + return cust; + } + + public static void main(String[] args) + { + Client client = new Client(); + try + { + client.makeClientCall(); + } + catch(Exception e) + { + e.printStackTrace(); + } + } +}</programlisting> + + <para>Again, the biggest difference to note is that have added + <literal>serializationtype=jboss</literal> to the locator uri.</para> + + <para>Note: Running this example requires JDK 1.5.</para> + + <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 + example:</para> + + <programlisting>ant run-transporter-serialization-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-transporter-serialization-client</programlisting> + + <para>When the server and client are run the output for the + <code>Client</code> class is:</para> + + <programlisting>Order to be processed: +Order: + +Is processed: false +Order id: -1 +Customer: +customer id: -1 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanata +state: GA +zip: 30249 + +Items ordered: +Xbox 360 +Wireless controller +Ghost Recon 3 +Order now processed +Order: + +Is processed: true +Order id: 221 +Customer: +customer id: 861 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanata +state: GA +zip: 30249 + +Items ordered: +Xbox 360 +Wireless controller +Ghost Recon 3 +</programlisting> + + <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> + + <para>And the output from the <code>Server</code> is:</para> + + <programlisting>Incoming order to process from customer. + +Customer: +customer id: -1 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanata +state: GA +zip: 30249 + +processed customer with new id of 861 +Items ordered: +Xbox 360 +Wireless controller +Ghost Recon 3 +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> + </section> + + <section> + <title>Transporter sample - clustered</title> + + <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> + + <para>This example uses the domain objects from the first, basic + example, so only need to cover the client and server code. For this + example, there are three different server classes. The first class is + the <code>SocketServer</code> class, which is the exact same as the + <code>Server</code> class in the basic example, except for the call to + the <code>TransportServer</code>'s <code>createTransportServer() + </code>method.</para> + + <programlisting>public class <emphasis role="bold">SocketServer</emphasis> +{ + public static String locatorURI = "socket://localhost:5400"; + private TransporterServer server = null; + + public void start() throws Exception + { + server = <emphasis role="bold">TransporterServer.createTransporterServer(getLocatorURI(), new CustomerProcessorImpl(), + CustomerProcessor.class.getName(), true)</emphasis>; + } + + protected String getLocatorURI() + { + return locatorURI; + } + + public void stop() + { + if(server != null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + SocketServer server = new SocketServer(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +}</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> + + <sidebar> + <para>The transporter uses the MulticastDetector from JBoss Remoting + for automatic discovery when in clustered mode. The actual detection + of remote servers that come online can take up to a few seconds once + started. There is a JNDI based detector provided within JBoss + Remoting, but has not been integrated within the transporters + yet.</para> + </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 to 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 + role="bold">SocketServer</emphasis> +{ + private String localLocatorURI = "<emphasis role="bold">rmi://localhost:5500</emphasis>"; + + protected String getLocatorURI() + { + return localLocatorURI; + } + + public static void main(String[] args) + { + SocketServer server = new RMIServer(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +}</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> + + <programlisting>public class <emphasis role="bold">HTTPServer</emphasis> extends <emphasis + role="bold">SocketServer</emphasis> +{ + private String localLocatorURI = "<emphasis role="bold">http://localhost:5600</emphasis>"; + + protected String getLocatorURI() + { + return localLocatorURI; + } + + public static void main(String[] args) + { + SocketServer server = new HTTPServer(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +}</programlisting> + + <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> + + <programlisting>public class <emphasis role="bold">Client</emphasis> +{ + <emphasis role="bold">private String locatorURI = SocketServer.locatorURI;</emphasis> + + private CustomerProcessor customerProcessor = null; + + public void makeClientCall() throws Exception + { + Customer customer = createCustomer(); + + System.out.println("Customer to be processed: " + customer); + <emphasis role="bold">Customer processedCustomer = customerProcessor.processCustomer(customer);</emphasis> + System.out.println("Customer is now: " + processedCustomer); + + //TransporterClient.destroyTransporterClient(customerProcessor); + } + + public void getCustomerProcessor() throws Exception + { + customerProcessor = (CustomerProcessor) <emphasis role="bold">TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class, true)</emphasis>; + } + + private Customer createCustomer() + { + Customer cust = new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr = new Address(); + addr.setStreet("101 Oak Street"); + addr.setCity("Atlanata"); + addr.setState("GA"); + addr.setZip(30249); + cust.setAddr(addr); + + return cust; + } + + public static void main(String[] args) + { + Client client = new Client(); + try + { +<emphasis role="bold"> client.getCustomerProcessor(); + while(true) + { + try + { + client.makeClientCall(); + Thread.currentThread().sleep(5000); + } + catch(Exception e) + { + e.printStackTrace(); + } + } +</emphasis> } + catch(Exception e) + { + e.printStackTrace(); + } + } +}</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 + 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> + + <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> + + <para>After getting the customer processor remote proxy, will + continually loop making calls using the remote proxy (via the + <code>processCustomer()</code> method on the + <code>customerProcessor</code> variable).</para> + + <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> + + <programlisting>ant run-transporter-clustered-socket-server</programlisting> + + <programlisting>ant run-transporter-clustered-http-server</programlisting> + + <programlisting>ant run-transporter-clustered-rmi-server</programlisting> + + <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 + bootstrap. This output would look like:</para> + + <programlisting>processed customer with new id of 378 +processed customer with new id of 487 +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> + + <programlisting><emphasis role="bold">... +org.jboss.remoting.CannotConnectException</emphasis>: Can not connect http client invoker. + at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:147) + at org.jboss.remoting.transport.http.HTTPClientInvoker.transport(HTTPClientInvoker.java:56) + at org.jboss.remoting.RemoteClientInvoker.invoke(RemoteClientInvoker.java:112) + at org.jboss.remoting.Client.invoke(Client.java:226) + at org.jboss.remoting.Client.invoke(Client.java:189) + at org.jboss.remoting.Client.invoke(Client.java:174) + at org.jboss.remoting.transporter.TransporterClient.invoke(TransporterClient.java:219) + at $Proxy0.processCustomer(Unknown Source) + at org.jboss.remoting.samples.transporter3.client.Client.makeClientCall(Client.java:29) + at org.jboss.remoting.samples.transporter3.client.Client.main(Client.java:64) + 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:585) + at com.intellij.rt.execution.application.AppMain.main(AppMain.java:86) +Caused by: java.net.ConnectException: Connection refused: connect + at java.net.PlainSocketImpl.socketConnect(Native Method) + at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:333) + at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:195) + at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:182) + at java.net.Socket.connect(Socket.java:507) + at java.net.Socket.connect(Socket.java:457) + at sun.net.NetworkClient.doConnect(NetworkClient.java:157) + at sun.net.www.http.HttpClient.openServer(HttpClient.java:365) + at sun.net.www.http.HttpClient.openServer(HttpClient.java:477) + at sun.net.www.http.HttpClient.&lt;init&gt;(HttpClient.java:214) + at sun.net.www.http.HttpClient.New(HttpClient.java:287) + at sun.net.www.http.HttpClient.New(HttpClient.java:299) + at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient(HttpURLConnection.java:792) + at sun.net.www.protocol.http.HttpURLConnection.plainConnect(HttpURLConnection.java:744) + at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.java:669) + at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLConnection.java:836) + at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:117) + ... 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> + + <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> + + <programlisting>... + at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.java:669) + at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLConnection.java:836) + at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:117) + ... 14 more + +Customer to be processed: +Customer: +customer id: -1 +first name: Bob +last name: Smith +street: 101 Oak Stree +city: Atlanata +state: null +zip: 30249 + +Customer is now: +Customer: +customer id: 633 +first name: Bob +last name: Smith +street: 101 Oak Stree +city: Atlanata +state: null +zip: 30249 + +...</programlisting> + + <sidebar> + <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> + + <para>It is important to understand that in the context of + 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> + </sidebar> + </section> + + <section> + <title>Transporters sample - multiple</title> + + <para>The multiple transporter example (found in + org.jboss.remoting.samples.transporter.multiple package) shows how can + have a multiple target pojos exposed via the same TransporterServer. In + this example, will be two pojos being exposed, CustomerProcessorImpl and + AccountProcessorImpl. Since the domain objects for this example is + similar to the others discussed in previous examples, will just focus on + the server and client code. On the server side, need to create the + TransporterServer so that will included both of the target pojos.</para> + + <programlisting>public class Server +{ + private String locatorURI = "socket://localhost:5400"; + private TransporterServer server = null; + + public void start() throws Exception + { + server = TransporterServer.createTransporterServer(locatorURI, new CustomerProcessorImpl(), CustomerProcessor.class.getName()); + server.addHandler(new AccountProcessorImpl(), AccountProcessor.class.getName()); + } + + public void stop() + { + if(server != null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server = new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +}</programlisting> + + <para>The TransporterServer is created with the CustomerProcessorImpl as + the inital target pojo. Now that have a live TransporterServer, can add + other pojos as targets. This is done using the addHandler() method where + the target pojo instance is passed and then the interface type to be + exposed as.</para> + + <para>Next have the Client that makes the call to both pojos.</para> + + <programlisting>public class Client +{ + private String locatorURI = "socket://localhost:5400"; + + public void makeClientCall() throws Exception + { + Customer customer = createCustomer(); + + CustomerProcessor customerProcessor = (CustomerProcessor) TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class); + + System.out.println("Customer to be processed: " + customer); + Customer processedCustomer = customerProcessor.processCustomer(customer); + System.out.println("Customer is now: " + processedCustomer); + + AccountProcessor accountProcessor = (AccountProcessor) TransporterClient.createTransporterClient(locatorURI, AccountProcessor.class); + + System.out.println("Asking for a new account to be created for customer."); + Account account = accountProcessor.createAccount(processedCustomer); + System.out.println("New account: " + account); + + TransporterClient.destroyTransporterClient(customerProcessor); + TransporterClient.destroyTransporterClient(accountProcessor); + + } + + private Customer createCustomer() + { + Customer cust = new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr = new Address(); + addr.setStreet("101 Oak Street"); + addr.setCity("Atlanta"); + addr.setState("GA"); + addr.setZip(30249); + cust.setAddr(addr); + + return cust; + } + + public static void main(String[] args) + { + org.jboss.remoting.samples.transporter.multiple.client.Client client = new org.jboss.remoting.samples.transporter.multiple.client.Client(); + try + { + client.makeClientCall(); + } + catch (Exception e) + { + e.printStackTrace(); + } + } + + +}</programlisting> + + <para>Notice that TransporterClients are created for each target pojo + want to call upon, they just happen to share the same locator uri. These + are independant instances so need to both be destroyed on their own when + finished with them.</para> + + <para>To run this example, run the Server class and then the Client + class. This can be done via ant targets + 'run-transporter-multiple-server' and then + 'run-transporter-multiple-client'. For example:</para> + + <programlisting>ant run-transporter-multiple-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-transporter-multiple-client</programlisting> + + <para>The output for the server should look similar to:</para> + + <programlisting>processed customer with new id of 980 +Created new account with account number: 1 and for customer: + +Customer: +customer id: 980 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanta +state: GA +zip: 30249</programlisting> + + <para>and the output from the client should look similar to:</para> + + <programlisting>Customer to be processed: +Customer: +customer id: -1 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanta +state: GA +zip: 30249 + +Customer is now: +Customer: +customer id: 980 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanta +state: GA +zip: 30249 + +Asking for a new account to be created for customer. +New account: Account - account number: 1 +Customer: +Customer: +customer id: 980 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanta +state: GA +zip: 30249 +</programlisting> + </section> + + <section> + <title>Transporters sample - proxy</title> + + <para>The proxy transporter example (found in + org.jboss.remoting.samples.transporter.proxy package) shows how can have + a TransporterClient sent over the network and called upon. In this + example, will have a target pojo, CustomerProcessorImpl which itself + creates a TransporterClient to another target pojo, Customer, and return + it as response to a method invocation.</para> + + <para>To start, will look at the initial target pojo, + CustomerProcessorImpl.</para> + + <programlisting>public class CustomerProcessorImpl implements CustomerProcessor +{ + private String locatorURI = "socket://localhost:5401"; + + /** + * Takes the customer passed, and if not null and customer id + * is less than 0, will create a new random id and set it. + * The customer object returned will be the modified customer + * object passed. + * + * @param customer + * @return + */ + public ICustomer processCustomer(Customer customer) + { + if (customer != null &amp;&amp; customer.getCustomerId() &lt; 0) + { + customer.setCustomerId(new Random().nextInt(1000)); + } + + ICustomer customerProxy = null; + try + { + TransporterServer server = TransporterServer.createTransporterServer(locatorURI, customer, ICustomer.class.getName()); + customerProxy = (ICustomer) TransporterClient.createTransporterClient(locatorURI, ICustomer.class); + } + catch (Exception e) + { + e.printStackTrace(); + } + + System.out.println("processed customer with new id of " + customerProxy.getCustomerId()); + return customerProxy; + } + +}</programlisting> + + <para>Notice that the processCustomer() method will take a Customer + object and set customer id on it. Then it will create a + TransporterServer for that customer instance and also create a + TransporterClient for the same instance and return that + TransporterClient proxy as the return to the processCustomer() + method.</para> + + <para>Next will look at the Customer class. It is a basic data object in + that is really just stores the customer data.</para> + + <programlisting>public class Customer implements Serializable, ICustomer +{ + private String firstName = null; + private String lastName = null; + private Address addr = null; + private int customerId = -1; + + public String getFirstName() + { + return firstName; + } + + public void setFirstName(String firstName) + { + this.firstName = firstName; + } + + public String getLastName() + { + return lastName; + } + + public void setLastName(String lastName) + { + this.lastName = lastName; + } + + public Address getAddr() + { + return addr; + } + + public void setAddr(Address addr) + { + this.addr = addr; + } + + public int getCustomerId() + { + return customerId; + } + + public void setCustomerId(int customerId) + { + this.customerId = customerId; + } + + public String toString() + { + System.out.println("Customer.toString() being called."); + StringBuffer buffer = new StringBuffer(); + buffer.append("\nCustomer:\n"); + buffer.append("customer id: " + customerId + "\n"); + buffer.append("first name: " + firstName + "\n"); + buffer.append("last name: " + lastName + "\n"); + buffer.append("street: " + addr.getStreet() + "\n"); + buffer.append("city: " + addr.getCity() + "\n"); + buffer.append("state: " + addr.getState() + "\n"); + buffer.append("zip: " + addr.getZip() + "\n"); + + return buffer.toString(); + } + + +} +</programlisting> + + <para>Notice the toString() method and how it prints out to the standard + out when being called. This will be important when the sample is run + later.</para> + + <para>Now if look at the Server class, will see is a standard setup like + have seen in previous samples.</para> + + <programlisting>public class Server +{ + private String locatorURI = "socket://localhost:5400"; + private TransporterServer server = null; + + public void start() throws Exception + { + server = TransporterServer.createTransporterServer(locatorURI, new CustomerProcessorImpl(), CustomerProcessor.class.getName()); + } + + public void stop() + { + if (server != null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server = new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch (Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +}</programlisting> + + <para>It is creating a TransporterServer for the CustomerProcessImpl + upon being started and will wait 60 seconds for invocations.</para> + + <para>Next is the Client class. </para> + + <programlisting>public class Client +{ + private String locatorURI = "socket://localhost:5400"; + + public void makeClientCall() throws Exception + { + Customer customer = createCustomer(); + + CustomerProcessor customerProcessor = (CustomerProcessor) TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class); + + System.out.println("Customer to be processed: " + customer); + ICustomer processedCustomer = customerProcessor.processCustomer(customer); + // processedCustomer returned is actually a proxy to the Customer instnace + // that lives on the server. So when print it out below, will actually + // be calling back to the server to get the string (vi toString() call). + // Notice the output of 'Customer.toString() being called.' on the server side. + System.out.println("Customer is now: " + processedCustomer); + + TransporterClient.destroyTransporterClient(customerProcessor); + + + } + + private Customer createCustomer() + { + Customer cust = new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr = new Address(); + addr.setStreet("101 Oak Street"); + addr.setCity("Atlanta"); + addr.setState("GA"); + addr.setZip(30249); + cust.setAddr(addr); + + return cust; + } + + public static void main(String[] args) + { + Client client = new Client(); + try + { + client.makeClientCall(); + } + catch (Exception e) + { + e.printStackTrace(); + } + } + + +}</programlisting> + + <para>The client class looks similar to the other example seen in that + it creates a TransporterClient for the CustomerProcessor and calls on it + to process the customer. Will then call on the ICustomer instance + returned from the processCustomer() method call and call toString() on + it (in the system out call). </para> + + <para>To run this example, run the Server class and then the Client + class. This can be done via ant targets 'run-transporter-proxy-server' + and then 'run-transporter-proxy-client'. For example:</para> + + <programlisting>ant run-transporter-proxy-server</programlisting> + + <para>ant then:</para> + + <programlisting>ant run-transporter-proxy-client</programlisting> + + <para>The output for the client should look similar to:</para> + + <programlisting>Customer.toString() being called. +Customer to be processed: +Customer: +customer id: -1 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanta +state: GA +zip: 30249 + +Customer is now: +Customer: +customer id: 418 +first name: Bob +last name: Smith +street: 101 Oak Street +city: Atlanta +state: GA +zip: 30249 +</programlisting> + + <para>The first line + is the print out from calling the Customer's toString() method that was + created to be passed to the CustomerProcessor's processCustomer() + method. Then the contents of the Customer object before being processed. + Then have the print out of the customer after has been processed. Notice + that when the ICustomer object instance is printed out the second time, + do not see the 'Customer.toString() being called'. This is because that + code is no longer being executed in the client vm, but instead is a + remote call to the customer instance living on the server (remember, the + processCustomer() method returned a TransporterClient proxy to the + customer living on the server side).</para> + + <para>Now, if look at output from the server will look similar + to:</para> + + <programlisting>processed customer with new id of 418 +Customer.toString() being called.</programlisting> + + <para>Notice that the 'Customer.toString() being called.' printed out at + the end. This is the result of the client's call to print out the + contents of the customer object returned from the processCustomer() + method, which actually lives within the server vm.</para> + + <para>This example has shown how can pass around TransporterClient + proxies to target pojos. However, when doing this, is important to + understand where the code is actually being executed as there are + consequences to being remote verse local, which need to be + understood.</para> + </section> + + <section> + <title>Transporter sample -complex</title> + + <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> + + <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-transporter-complex-client' as well. For example:</para> + + <programlisting>ant run-transporter-complex-server</programlisting> + + <para>and then:</para> + + <programlisting>ant run-transporter-complex-client</programlisting> + + <para>The output for the client should look similar to:</para> + + <programlisting>*** Have a new patient that needs a doctor. The patient is: + +Patient: + Name: Bill Gates + Ailment - Type: financial, Description: Money coming out the wazoo. + +*** Looking for doctor that can help our patient... + +*** Found doctor for our patient. Doctor found is: +Doctor: + Name: Andy Jones + Specialty: financial + Patients: + +Patient: + Name: Larry Ellison + Ailment - Type: null, Description: null + Doctor - Name: Andy Jones + +Patient: + Name: Steve Jobs + Ailment - Type: null, Description: null + Doctor - Name: Andy Jones + +Patient: + Name: Bill Gates + Ailment - Type: financial, Description: Money coming out the wazoo. + +*** Set doctor as patient's doctor. Patient info is now: + +Patient: + Name: Bill Gates + Ailment - Type: financial, Description: Money coming out the wazoo. + Doctor - Name: Andy Jones + +*** Have a new patient that we need to find a doctor for (remember, the previous one retired and there are no others) +*** Could not find doctor for patient. This is an expected exception when there are not doctors available. +org.jboss.remoting.samples.transporter.complex.NoDoctorAvailableException: No doctor available for ailment 'financial' + at org.jboss.remoting.RemoteClientInvoker.invoke(RemoteClientInvoker.java:183) + at org.jboss.remoting.Client.invoke(Client.java:325) + at org.jboss.remoting.Client.invoke(Client.java:288) + at org.jboss.remoting.Client.invoke(Client.java:273) + at org.jboss.remoting.transporter.TransporterClient.invoke(TransporterClient.java:237) + at $Proxy0.findDoctor(Unknown Source) + at org.jboss.remoting.samples.transporter.complex.client.Client.makeClientCall(Client.java:72) + at org.jboss.remoting.samples.transporter.complex.client.Client.main(Client.java:90) + 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:585) + 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> + </section> + </section> + + <section> + <title id="section-multiplex-invokers" + xreflabel="Multiplex invokers">Multiplex invokers</title> + + <para>This section illustrates the construction of multiplex invoker + groups described in the section <xref linkend="section-multiplex-invoker" />. The + directory</para> + + <blockquote> + <para><code>examples/org/jboss/remoting/samples/multiplex/invoker</code></para> + </blockquote> + + <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> + + <para>The sample clients are as follows. Each sample client + <emphasis>&lt;client&gt;</emphasis> may be run in an IDE or by using the + ant target <code>run-</code><emphasis>&lt;client&gt;</emphasis> (e.g., + <code>run-Client2Server1</code>).</para> + + <itemizedlist> + <listitem> + <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>Connector</classname> are passed matching + <emphasis>clientMultiplexId</emphasis> and + <emphasis>serverMultiplexId</emphasis> parameters, + respectively.</para> + </listitem> + + <listitem> + <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 + <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. + 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 + <classname>Connector</classname> are passed matching + <emphasis>clientMultiplexId</emphasis> and + <emphasis>serverMultiplexId</emphasis> parameters, + respectively.</para> + </listitem> + + <listitem> + <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>Client</classname> are passed matching + <emphasis>serverMultiplexId</emphasis> and + <emphasis>clientMultiplexId</emphasis> parameters, + respectively.</para> + </listitem> + + <listitem> + <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 + <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. + 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 + <classname>Client</classname> are passed matching + <emphasis>serverMultiplexId</emphasis> and + <emphasis>clientMultiplexId</emphasis> parameters, + respectively.</para> + </listitem> + </itemizedlist> + + <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> + </section> +</chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap13.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap13.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap13.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -1,87 +1,17 @@ <chapter> - <title>Getting the JBossRemoting source and building</title> + <title>Compatibility and versioning</title> - <para>The JBossRemoting source code resides in the JBoss CVS repository - under the CVS module JBossRemoting. To check out the source using the - anonymous account, use the following command:</para> - - <programlisting>cvs -d:pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss checkout JBossRemoting</programlisting> - - <para>To check out the source using a committer user id, use the - following:</para> - - <programlisting>cvs -d:ext:username@cvs.forge.jboss.com:/cvsroot/jboss checkout JBossRemoting</programlisting> - - <para>This should checkout the entire remoting project, including doc, - tests, libs, etc.</para> - - <para>See <!--<link linkend="???">http://www.jboss.org/wiki/Wiki.jsp?page=CVSRep... - <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=CVSRepository"> - http://www.jboss.org/wiki/Wiki.jsp?page=CVSRepository </ulink> for more - information on how to access the JBoss CVS repository.</para> - - <para>The build process for JBossRemoting is based on a standard ant build - file (build.xml). The version of ant that is supported is ant 1.6.2, but - should work with earlier versions as there are no special ant features - being used.</para> - - <para>The main ant build targets are as follows:</para> - - <para><emphasis role="bold">compile</emphasis> - compiles all the core - JBossRemoting classes.</para> - - <para><emphasis role="bold">jars</emphasis> - creates the - jboss-remoting.jar file from the compiled classes</para> - - <para><emphasis role="bold">dist.jars</emphasis> - creates the - subsystem jar files (jboss-remoting-core.jar, jboss-remoting-socket.jar, etc.) - from the compiled classes</para> - - <para><emphasis role="bold">javadoc</emphasis> - creates the javadoc html - files for JBossRemoting</para> - - <para><emphasis role="bold">tests.compile</emphasis> - compiles the - JBossRemoting test files</para> - - <para><emphasis role="bold">tests.jars</emphasis> - creates the - jboss-remoting-tests.jar and jboss-remoting-loading-tests.jar - files.</para> - - <para><emphasis role="bold">tests.quick</emphasis> - runs the functional - unit tests for JBossRemoting.</para> - - <para><emphasis role="bold">tests</emphasis> - runs all the tests for - JBossRemoting, including functional and performance tests for all the - different transports.</para> - - <para><emphasis role="bold">clean</emphasis> - removes all the build - artifacts and directories.</para> - - <para><emphasis role="bold">most</emphasis> - calls clean then jars - targets.</para> - - <para><emphasis role="bold">dist</emphasis> - builds the full - JBossRemoting distribution including running the full test suite.</para> - - <para><emphasis role="bold">dist.quick</emphasis> - builds the full - JBossRemoting distribution, but does not run the test suite.</para> - - <para>The root directory for all build output is the output directory. - Under this directory will be:</para> - - <para><literal>classes</literal> - compiled core classes - <literal></literal></para> - - <para><literal>etc</literal> - deployment and JMX XMBean xml files - <literal></literal></para> - - <para><literal>lib</literal> - all the jars and war file produced by the - build <literal></literal></para> - - <para><literal>tests</literal> - contains the compiled test classes and - test results</para> - - <para>For most development, the most target can be used. Please run the - tests.quick target before checking anything in to ensure that code changes - did not break any previously functioning test.</para> + <para>As of JBossRemoting 2.0.0 versioning has been added to guarantee + compatibility between different versions. This is accomplished by changing + serialization formats for certain classes and by using wire versioning. By + wire versioning, mean that the version used by a client and server will be + sent on the wire so that the other side will be able to adjust + accordingly. This will be automatic for JBossRemoting 2.0.0 and later + versions. However, since versioning was not introduced until the 2.0.0 + release, if need to have a 1.4.x version of remoting communicate to a + later version, will need to set a system property on the 2.0.0 version so + that knows to use the older wire protocol version. The system property to + set is 'jboss.remoting.pre_2_0_compatible' and should be set to true. + There are a few minor features that will not be fully compatible between + 1.4.x release and 2.0.0, which are listed in the release notes.</para> </chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap14.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap14.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap14.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -1,16 +1,87 @@ <chapter> - <title>Known issues</title> + <title>Getting the JBossRemoting source and building</title> - <para>All of the known issues and road map can be found on our bug - tracking system, Jira, at <!--<link linkend="???">http://jira.jboss.com/jira/secure/BrowseProjec... - <ulink - url="http://jira.jboss.com/jira/secure/BrowseProject.jspa?id=10031&q... - http://jira.jboss.com/jira/secure/BrowseProject.jspa?id=10031 </ulink> - (require member plus registration, which is free). If you find more, - please post them to Jira. If you have questions post them to the JBoss - Remoting users forum <!--<link linkend="???">http://www.jboss.com/index.html?module=bb&... - (<ulink - url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... - http://www.jboss.com/index.html?module=bb&amp;op=viewforum&amp;f=222 - </ulink>).</para> + <para>The JBossRemoting source code resides in the JBoss CVS repository + under the CVS module JBossRemoting. To check out the source using the + anonymous account, use the following command:</para> + + <programlisting>cvs -d:pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss checkout JBossRemoting</programlisting> + + <para>To check out the source using a committer user id, use the + following:</para> + + <programlisting>cvs -d:ext:username@cvs.forge.jboss.com:/cvsroot/jboss checkout JBossRemoting</programlisting> + + <para>This should checkout the entire remoting project, including doc, + tests, libs, etc.</para> + + <para>See <!--<link linkend="???">http://www.jboss.org/wiki/Wiki.jsp?page=CVSRep... + <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=CVSRepository"> + http://www.jboss.org/wiki/Wiki.jsp?page=CVSRepository </ulink> for more + information on how to access the JBoss CVS repository.</para> + + <para>The build process for JBossRemoting is based on a standard ant build + file (build.xml). The version of ant that is supported is ant 1.6.2, but + should work with earlier versions as there are no special ant features + being used.</para> + + <para>The main ant build targets are as follows:</para> + + <para><emphasis role="bold">compile</emphasis> - compiles all the core + JBossRemoting classes.</para> + + <para><emphasis role="bold">jars</emphasis> - creates the + jboss-remoting.jar file from the compiled classes</para> + + <para><emphasis role="bold">dist.jars</emphasis> - creates the + subsystem jar files (jboss-remoting-core.jar, jboss-remoting-socket.jar, etc.) + from the compiled classes</para> + + <para><emphasis role="bold">javadoc</emphasis> - creates the javadoc html + files for JBossRemoting</para> + + <para><emphasis role="bold">tests.compile</emphasis> - compiles the + JBossRemoting test files</para> + + <para><emphasis role="bold">tests.jars</emphasis> - creates the + jboss-remoting-tests.jar and jboss-remoting-loading-tests.jar + files.</para> + + <para><emphasis role="bold">tests.quick</emphasis> - runs the functional + unit tests for JBossRemoting.</para> + + <para><emphasis role="bold">tests</emphasis> - runs all the tests for + JBossRemoting, including functional and performance tests for all the + different transports.</para> + + <para><emphasis role="bold">clean</emphasis> - removes all the build + artifacts and directories.</para> + + <para><emphasis role="bold">most</emphasis> - calls clean then jars + targets.</para> + + <para><emphasis role="bold">dist</emphasis> - builds the full + JBossRemoting distribution including running the full test suite.</para> + + <para><emphasis role="bold">dist.quick</emphasis> - builds the full + JBossRemoting distribution, but does not run the test suite.</para> + + <para>The root directory for all build output is the output directory. + Under this directory will be:</para> + + <para><literal>classes</literal> - compiled core classes + <literal></literal></para> + + <para><literal>etc</literal> - deployment and JMX XMBean xml files + <literal></literal></para> + + <para><literal>lib</literal> - all the jars and war file produced by the + build <literal></literal></para> + + <para><literal>tests</literal> - contains the compiled test classes and + test results</para> + + <para>For most development, the most target can be used. Please run the + tests.quick target before checking anything in to ensure that code changes + did not break any previously functioning test.</para> </chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap16.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap16.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap16.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -1,1458 +1,22 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter> - <title>Release Notes</title> + <chapter> + <title>Future plans</title> - <bridgehead>Important changes and differences in 2.2.0 release (from 2.0.0 - release)</bridgehead> + <para>Full road map for JBossRemoting can be found at <!--<link linkend="???"> + http://jira.jboss.com/jira/browse/JBREM?report=com.atlassian.jira.plugin.... + </link>--> <ulink + url="http://jira.jboss.com/jira/browse/JBREM?report=com.atlassian.ji... + http://jira.jboss.com/jira/browse/JBREM?report=com.atlassian.jira.plugin.... + </ulink>.</para> - <para>- Asynchronous method for handling callbacks (JBREM-640)</para> - - <para>- Bidirectional transport (JBREM-650) </para> - - <para>- Local transport (JBREM-660) </para> - - <para>- Marshallers/Unmarshallers construct their preferred streams - (JBREM-692)</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 2.2.0.GA (Bluto) </para> - - <para>** Bug * [JBREM-721] - Fix memory leaks in bisocket transport and - LeasePinger </para> - - <para>* [JBREM-722] - BisocketClientInvoker should start pinging on control - connection without waiting for call to createsocket() </para> - - <para>* [JBREM-725] - NPE in BisocketServeInvoker::createControlConnection - </para> - - <para>* [JBREM-726] - BisocketServerInvoker control connection creation - needs to be in loop </para> - - <para>** Feature Request</para> - - <para> * [JBREM-705] - Separate the http invoker and web container - dependency </para> - - <para>* [JBREM-727] - Make Client's implicitly created Connectors accessible - </para> - - <para>** Task * [JBREM-634] - update doc on callbacks </para> - - <para>* [JBREM-724] - Update build.xml to create bisocket transport jars - </para> - - <para>Release Notes - JBoss Remoting - Version 2.2.0.Beta1 (Bluto) </para> - - <para>** Bug * [JBREM-581] - can not do connection validation with ssl - transport (only impacts detection) </para> - - <para>* [JBREM-600] - - org.jboss.test.remoting.lease.multiplex.MultiplexLeaseTestCase fails </para> - - <para>* [JBREM-623] - need reset() call added back to - JavaSerializationManager.sendObject() method </para> - - <para>* [JBREM-642] - Socket.setReuseAddress() in MicroSocketClientInvoker - invocation is ignored </para> - - <para>* [JBREM-648] - Client.disconnect without clearing ConnectionListeners - will cause NPEs </para> - - <para>* [JBREM-651] - Array class loading problem under jdk6 </para> - - <para>* [JBREM-654] - a NullPointerException occures and is not handled in - SocketServerInvoker and MultiplexServerInvoker </para> - - <para>* [JBREM-655] - rename server thread when new socket connection comes - in </para> - - <para>* [JBREM-656] - Creating a client inside a ConnectionListener might - lead into Lease reference counting problems </para> - - <para>* [JBREM-658] - bug in oneway thread pool under heavy load </para> - - <para>* [JBREM-659] - Java 6 and ClassLoader.loadClass() </para> - - <para>* [JBREM-670] - Remove equals() and hashCode() from - org.jboss.remoting.transport.rmi.RemotingRMIClientSocketFactory. </para> - - <para>* [JBREM-671] - serlvet invoker no longer supports leasing </para> - - <para>* [JBREM-683] - ByValueInvocationTestCase is broken </para> - - <para>* [JBREM-685] - A server needs redundant information to detect a one - way invocation </para> - - <para>* [JBREM-690] - Once the socket of a callback server timeouts, it - starts to silently discard traffic </para> - - <para>* [JBREM-697] - - Horg.jboss.remoting.transport.rmi.RemotingRMIClientSocketFactory.ComparableHolder - should use InetAddress for host. </para> - - <para>* [JBREM-700] - NPE in AbstractDetector </para> - - <para>* [JBREM-704] - BisocketServerInvoker inadvertently logs "got - listener: null" as INFO </para> - - <para>* [JBREM-708] - Correct org.jboss.remoting.Client.readExternal() - </para> - - <para>* [JBREM-711] - ChunkedTestCase and Chuncked2TestCase failing </para> - - <para>* [JBREM-712] - HTTPInvokerProxyTestCase failing </para> - - <para>* [JBREM-723] - BisocketClientInvoker.transport() needs to distinguish - between push and pull callback connections </para> - - <para>** Feature Request </para> - - <para>* [JBREM-525] - Automatically set HostnameVerifier in - HTTPSClientInvoker to allow all hosts if authorization is turned off. - </para> - - <para>* [JBREM-598] - add timeout config per client invocation </para> - - <para>* [JBREM-618] - Support CallbackPoller configuration. </para> - - <para>* [JBREM-640] - Implement an asynchronous method for handling - callbacks. </para> - - <para>* [JBREM-650] - Create bidirectional transport </para> - - <para>* [JBREM-657] - Implement versions of Client.removeListener() and - Client.disconnect() which do not write to a broken server. </para> - - <para>* [JBREM-660] - create local transport </para> - - <para>* [JBREM-664] - Fix misleading InvalidConfigurationException </para> - - <para>* [JBREM-692] - Let marshallers/unmarshallers construct their - preferred streams. </para> - - <para>* [JBREM-720] - Need to expose create method for TransporterClient - that passes load balancing policy </para> - - <para>** Task </para> - - <para>* [JBREM-274] - add callback methods to the Client API </para> - - <para>* [JBREM-369] - For Connectors that support callbacks on SSL - connections, there should be a unified means of configuring SSLServerSocket - and callback Client SSLSocket.s. </para> - - <para>* [JBREM-453] - Send the pre-release jar to the messaging team for - testing </para> - - <para>* [JBREM-614] - Client.invoke() should check isConnected(). </para> - - <para>* [JBREM-631] - Fix - org.jboss.test.remoting.transport.socket.connection.SocketConnectionCheckTestCase - and SocketConnectionTestCase failures. </para> - - <para>* [JBREM-635] - Remove misleading error message from HTTPUnMarshaller. - </para> - - <para>* [JBREM-636] - Remove ServerInvokerCallbackHandler's dependence on - initial InvocationRequest for listerner id. </para> - - <para>* [JBREM-637] - add tomcat jar to component-info.xml for remoting - release </para> - - <para>* [JBREM-644] - Reduce unit test logging output. </para> - - <para>* [JBREM-647] - Initialize Client configuration map to empty HashMap. - </para> - - <para>* [JBREM-663] - Put org.jboss.remoting.LeasePinger on separate thread. - </para> - - <para>* [JBREM-669] - Client.removeListener() should catch exception and - continue if invocation to server fails. </para> - - <para>* [JBREM-674] - add test case for client exiting correctly </para> - - <para>* [JBREM-693] - Make sure "bisocket" can fully replace "socket" as - Messaging's default transport </para> - - <para>* [JBREM-695] - RemotingRMIClientSocketFactory.createSocket() should - return a socket even if a RMIClientInvoker has not been registered. </para> - - <para>* [JBREM-702] - http.basic.password should allow for empty passwords - </para> - - <para>* [JBREM-707] - Fix handling of OPTIONS invocations in CoyoteInvoker - </para> - - <para>* [JBREM-709] - Fix occasional failures of - org.jboss.test.remoting.lease.socket.multiple.SocketLeaseTestCase </para> - - <para>* [JBREM-719] - Fix spelling of - ServerInvokerCallbackHandler.REMOTING_ACKNOWLEDGES_PUSH_CALLBACKS </para> - - <para>Release Notes - JBoss Remoting - Version 2.2.0.Alpha6 </para> - - <para>** Bug * [JBREM-662] - Failed ClientInvoker not cleaned up properly - </para> - - <para>* [JBREM-673] - Use of java.util.Timer recently added and not set to - daemon, so applications not exiting </para> - - <para>* [JBREM-683] - ByValueInvocationTestCase is broken </para> - - <para>** Feature Request </para> - - <para>* [JBREM-678] - Sending an one-way invocation into a server invoker - that is not started should generate a warning in logs </para> - - <para>* [JBREM-679] - Add the possibility to obtain ConnectionValidator's - ping period from a Client </para> - - <para>* [JBREM-680] - An invocation into a "broken" client should throw a - subclass of IOException </para> - - <para>** Task </para> - - <para>* [JBREM-676] - TimerTasks run by TimerUtil should have a chance to - clean up if TimerUtil.destroy() is called. </para> - - <para>Release Notes - JBoss Remoting - Version 2.2.0.Alpha5</para> - - <para> ** Bug </para> - - <para>* [JBREM-666] - Broken or malicious clients can lock up the remoting - server </para> - - <para>* [JBREM-667] - Worker thread names are confusing </para> - - <para>** Feature Request </para> - - <para>* [JBREM-668] - jrunit should allow TRACE level logging </para> - - <para>Release Notes - JBoss Remoting - Version 2.2.0.Alpha4 </para> - - <para>** Bug </para> - - <para>* [JBREM-649] - Concurrent exceptions on Lease when - connecting/disconnecting new Clients </para> - - <para>Release Notes - JBoss Remoting - Version 2.2.0.Alpha3 (Bluto) </para> - - <para>** Bug </para> - - <para>* [JBREM-594] - invoker not torn down upon connector startup error - </para> - - <para>* [JBREM-596] - Lease stops working if the First Client using the same - Locator is closed </para> - - <para>* [JBREM-602] - If LeasePeriod is not set and if enableLease==true - leasePeriod assumes negative value </para> - - <para>* [JBREM-610] - Prevent org.jboss.remoting.callback.CallbackPoller - from delivering callbacks out of order. </para> - - <para>* [JBREM-611] - Initializing Client.sessionId outside constructor - leads to java.lang.NoClassDefFoundError in certain circumstances </para> - - <para>* [JBREM-615] - If CallbackStore.add() is called twice quickly, - System.currentTimeMillis() might not change, leading to duplicate file - names. </para> - - <para>* [JBREM-616] - Deletion of callback files in getNext() is not - synchronized, allowing callbacks to be returned multiple times. </para> - - <para>* [JBREM-619] - In SocketServerInvoker.run() and - MultiplexServerInvoker().run, guarantee ServerSocketRefresh thread - terminates. </para> - - <para>* [JBREM-622] - InvokerLocator already exists for listener </para> - - <para>* [JBREM-625] - MicroSocketClientInvoker should decrement count of - used sockets when a socket is discarded. </para> - - <para>* [JBREM-629] - NPE in sending notification of lost client </para> - - <para>** Feature Request </para> - - <para>* [JBREM-419] - Invokers Encryption </para> - - <para>* [JBREM-429] - Create JBossSerialization MarshalledValue more - optimized for RemoteCalls </para> - - <para>* [JBREM-548] - Support one way invocations with no response </para> - - <para>* [JBREM-597] - Allow access to underlying stream in marshaller with - socket transport </para> - - <para>* [JBREM-604] - allow socket server invoker to accept third party - requests </para> - - <para>* [JBREM-605] - Inform a server side listener that a callback has been - delivered. </para> - - <para>* [JBREM-607] - Add idle timeout setting for invoker threads </para> - - <para>* [JBREM-609] - Support nonserializable callbacks in CallbackStore - </para> - - <para>** Task </para> - - <para>* [JBREM-562] - publish performance benchmarks </para> - - <para>* [JBREM-601] - Integrate http with messaging </para> - - <para>* [JBREM-612] - Verify push callback connection with multiplex - transport shares client to server connection. </para> - - <para>* [JBREM-613] - ServerInvoker.InvalidStateException should be a static - class. </para> - - <para>* [JBREM-617] - CallbackPoller should have its own thread. </para> - - <para>* [JBREM-620] - If HTTPClientInvoker receives an Exception in an - InvocationRespose, it should throw it instead of creating a new Exception. - </para> - - <para>* [JBREM-621] - http transport should behave more like other - transports. </para> - - <para>* [JBREM-624] - Add JBoss EULA </para> - - <para>* [JBREM-627] - Fix - org.jboss.test.remoting.transport.multiplex.MultiplexInvokerShutdownTestCase - failure. </para> - - <para>* [JBREM-630] - Fix client/server race in - org.jboss.test.remoting.transport.multiplex.LateClientShutdownTestCase. - </para> - - <para>* [JBREM-632] - Modify src/etc/log4j.xml to allow DEBUG level logging - for org.jboss.remoting loggers in jrunit test cases.</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 2.0.0.GA (Boon)</para> - - <para>** Bug</para> - - <para>* [JBREM-568] - SSLSocketBuilderMBean does not have matching - getter/setter attribute types</para> - - <para>* [JBREM-569] - HTTP(S) proxy broken</para> - - <para>* [JBREM-576] - deadlock with socket invoker</para> - - <para>* [JBREM-579] - transporter does not handle reflection conversion for - primitive types</para> - - <para>* [JBREM-580] - detection can not be used with ssl based - transports</para> - - <para>* [JBREM-586] - socket client invoker connection pooling not - bounded</para> - - <para>* [JBREM-590] - SSL client socket invoker does not use configuration - map for SSLSocketBuilder</para> - - <para>** Feature Request</para> - - <para>* [JBREM-564] - Default client socket factory configured by a system - property</para> - - <para>* [JBREM-575] - local client invoker should convert itself to remote - client invoker when being serialized</para> - - <para>** Task</para> - - <para>* [JBREM-570] - Change log in ConnectionValidator to be debug instead - of warn when not able to ping server</para> - - <para>* [JBREM-571] - fix/cleanup doc</para> - - <para>* [JBREM-574] - Write SSL info for virtual sockets and server sockets - in toString()</para> - - <para>* [JBREM-578] - add spring remoting to performance benchmark - tests</para> - - <para>* [JBREM-582] - remove System.out.println and printStackTrace - calls</para> - - <para>* [JBREM-583] - Fix ConcurrentModificationException in - MultiplexingManager.notifySocketsOfException()</para> - - <para>* [JBREM-584] - Get - org.jboss.test.remoting.performance.spring.rmi.SpringRMIPerformanceTestCase - to run with multiple clients and callback handlers</para> - - <para>* [JBREM-587] - - ClientConfigurationCallbackConnectorTestCase(jboss_serialization) - failure.</para> - - <para>* [JBREM-593] - Synchronize client and server in - org.jboss.test.remoting.transport.multiplex.LateClientShutdownTestCase</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 2.0.0.CR1 (Boon)</para> - - <para>** Bug</para> - - <para>* [JBREM-303] - - org.jboss.test.remoting.transport.multiplex.BasicSocketTestCase(jboss_serialization) - failure</para> - - <para>* [JBREM-387] - classloading problem - using wrong classloader</para> - - <para>* [JBREM-468] - No connection possible after an illegitimate - attempt</para> - - <para>* [JBREM-484] - AbstractDetector.checkInvokerServer() is probably - broken</para> - - <para>* [JBREM-494] - ClientDisconnectedException does not have serial - version UID</para> - - <para>* [JBREM-495] - classes that do not have serial version UID</para> - - <para>* [JBREM-500] - ServerThread never dies</para> - - <para>* [JBREM-502] - not getting REMOVED notification from registry for - intra-VM detection</para> - - <para>* [JBREM-503] - NPE in abstract detector</para> - - <para>* [JBREM-506] - StreamHandler throws index out of bounds - exception</para> - - <para>* [JBREM-508] - serialization exception with mustang</para> - - <para>* [JBREM-519] - StreamServer never shuts down the server</para> - - <para>* [JBREM-526] - TimeUtil not using daemon thread</para> - - <para>* [JBREM-528] - ConcurrentModificationException when checking for dead - servers (AbstractDetector)</para> - - <para>* [JBREM-530] - Detection heartbeat requires small timeout (for dead - server detection)</para> - - <para>* [JBREM-534] - multiplex client cannot re-connect to server after it - has died and then been re-started</para> - - <para>* [JBREM-537] - - org.jboss.test.remoting.transport.rmi.ssl.handshake.RMIInvokerTestCase(java_serialization) - - failing</para> - - <para>* [JBREM-541] - null pointer when receiving detection message</para> - - <para>* [JBREM-545] - setting of the bind address within MulticastDetector - not working</para> - - <para>* [JBREM-546] - InvokerLocator.equals is broken</para> - - <para>* [JBREM-552] - cannot init cause of ClassCastException</para> - - <para>* [JBREM-553] - deadlock when disconnecting</para> - - <para>* [JBREM-556] - versioning tests failing</para> - - <para>* [JBREM-561] - http chuncked test cases failing under jdk 1.5</para> - - <para>** Feature Request</para> - - <para>* [JBREM-427] - SSL Connection: load a new keystore at runtime</para> - - <para>* [JBREM-430] - transporter needs to be customizable</para> - - <para>* [JBREM-461] - Better documentation for sslmultiplex</para> - - <para>* [JBREM-491] - need to implement using ssl client mode for push - callbacks for all transports</para> - - <para>* [JBREM-492] - would like an API to indicate if a transport requires - SSL configuration</para> - - <para>* [JBREM-499] - need indication if invoker is secured by ssl</para> - - <para>* [JBREM-501] - give descriptive names to threads</para> - - <para>* [JBREM-504] - some synch blocks in AbstractDetector could - change</para> - - <para>* [JBREM-520] - Organize configuring of ServerSocketFactory's and - callback SocketFactory's.</para> - - <para>* [JBREM-527] - Allow user to pass Connector to be used for stream - server</para> - - <para>* [JBREM-532] - need synchronous call from detector client to get all - remoting servers on network</para> - - <para>* [JBREM-539] - add sslservlet procotol</para> - - <para>* [JBREM-544] - http client invoker (for http, https, servlet, and - sslservlet) needs to handle exceptions in same manner as other transport - implementations</para> - - <para>** Task</para> - - <para>* [JBREM-21] - Add stress tests</para> - - <para>* [JBREM-218] - investigate why jrunit report on cruisecontrol - inaccurate</para> - - <para>* [JBREM-311] - need required library matrix</para> - - <para>* [JBREM-320] - optimize pass by value within remoting</para> - - <para>* [JBREM-321] - performance tuning</para> - - <para>* [JBREM-368] - Configure SSLSockets and SSLServerSockets used in - callbacks to be in server mode and client mode, respectively.</para> - - <para>* [JBREM-383] - Document new versioning for remoting</para> - - <para>* [JBREM-384] - correct manifest to comply with new standard</para> - - <para>* [JBREM-390] - finish multiplex</para> - - <para>* [JBREM-412] - Remoting Guide lacks left margin</para> - - <para>* [JBREM-423] - document how remoting identity works and how to - configure</para> - - <para>* [JBREM-428] - add the samples/transporter/multiple/ to the - distribution build (think may be there by default) and update the - docs</para> - - <para>* [JBREM-434] - fix configuration data within document (socketTimeout - should be timeout)</para> - - <para>* [JBREM-435] - break out remoting jars (serialization)</para> - - <para>* [JBREM-442] - need full doc on how socket invoker works (connection - pooling, etc.)</para> - - <para>* [JBREM-447] - convert static transporter factory methods into - constructor calls</para> - - <para>* [JBREM-452] - Send the pre-release jar to the messaging team for - testing</para> - - <para>* [JBREM-454] - cache socket wrapper classes</para> - - <para>* [JBREM-477] - remove Client.setInvoker() and Client.getInvoker() - methods</para> - - <para>* [JBREM-487] - Eliminate possible synchronization problem in - InvokerRegistry</para> - - <para>* [JBREM-490] - consolidate the remoting security related - classes</para> - - <para>* [JBREM-493] - Update version of jboss serialization being - used</para> - - <para>* [JBREM-496] - restructure service providers for remoting</para> - - <para>* [JBREM-497] - change InvokerLocator to respect hostname over ip - address</para> - - <para>* [JBREM-498] - change logging on cleaning up failed detection</para> - - <para>* [JBREM-507] - need to make configuration properties - consistent</para> - - <para>* [JBREM-509] - Fix call to super() in ServerInvoker's two argument - constructor.</para> - - <para>* [JBREM-511] - Allow HTTPSClientInvoker to create a HostnameVerifier - from classname.</para> - - <para>* [JBREM-513] - Create SSL version of RMI transport.</para> - - <para>* [JBREM-514] - Fix potential NullPointerException in - SSLSocketClientInvoker.createSocket().</para> - - <para>* [JBREM-516] - add very simple transporter sample</para> - - <para>* [JBREM-517] - HTTPServerInvoker needs to be deprecated</para> - - <para>* [JBREM-523] - connection pool on socket client invoker needs to be - bound</para> - - <para>* [JBREM-524] - Clean up MicrosocketClientInvoker code</para> - - <para>* [JBREM-529] - Need to be able to reuse socket connections after move - to TIME_WAIT state</para> - - <para>* [JBREM-533] - remove external http GET test</para> - - <para>* [JBREM-535] - add config to force use of remote invoker instead of - local</para> - - <para>* [JBREM-536] - turn off host verification when doing push callback - from server using same ssl config as server</para> - - <para>* [JBREM-538] - update remoting dist build to break out transports - into individual jars</para> - - <para>* [JBREM-540] - need to make servlet-invoker.war part of remoting - distribution</para> - - <para>* [JBREM-542] - change how remoting servlet finds servlet - invoker</para> - - <para>* [JBREM-543] - fix servlet invoker error handling to be more like - that of the http invoker</para> - - <para>* [JBREM-547] - need test case for exposing multiple interfaces for - transporter server target pojo</para> - - <para>* [JBREM-551] - - org.jboss.test.remoting.transport.multiplex.MultiplexInvokerTestCase(java_serialization) - failure</para> - - <para>* [JBREM-555] - fix connection validator to not require extra thread - to execute ping every time</para> - - <para>* [JBREM-558] - Break master.xml documentation into chapter - files</para> - - <para>* [JBREM-559] - update doc for 2.0.0.CR1 release</para> - - <para>* [JBREM-560] - InvokerGroupTestCase(java_serialization) - failure</para> - - <para>* [JBREM-563] - Multiplex - ClientConfigurationCallbackConnectorTestCase(jboss_serialization) - failure</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 2.0.0.Beta2 (Boon)</para> - - <para>** Bug</para> - - <para>* [JBREM-304] - - org.jboss.test.remoting.transport.multiplex.MultiplexInvokerTestCase(java_serialization) - fails</para> - - <para>* [JBREM-371] - HTTPClientInvoker does not pass an ObjectOutputStream - to the marshaller</para> - - <para>* [JBREM-405] - NPE when calling stop() twice on - MulticastDetector</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-449] - Failure Information lost in - RemotingSSLSocketFactory</para> - - <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-470] - javax.net.ssl.SSLException: No available certificate - corresponds to the SSL cipher suites</para> - - <para>* [JBREM-472] - Misspelled serialization type generates obscure - NPE</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-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-481] - Changing StringUtilBuffer creation on - JBossSerialization</para> - - <para>** Task</para> - - <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-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> - - <para>* [JBREM-319] - ability to inject socket factory by classname or - instance in all remoting transports</para> - - <para>* [JBREM-323] - client lease config changes</para> - - <para>* [JBREM-329] - create global transport config for timeout</para> - - <para>* [JBREM-330] - create socket server factory based off of - configuration properties</para> - - <para>* [JBREM-335] - Client.invoke() should pass configuration map to - InvokerRegistry.createClientInvoker().</para> - - <para>* [JBREM-336] - InvokerRegistry doesn't purge InvokerLocators from - static Set registeredLocators.</para> - - <para>* [JBREM-337] - PortUtil.findFreePort() should return ports only - between 1024 and 65535.</para> - - <para>* [JBREM-342] - Thread usage for timers and lease functionality</para> - - <para>* [JBREM-354] - ServerInvokerCallbackHandler should make its subsystem - accessible.</para> - - <para>* [JBREM-356] - ServerInvoker should destroy its callback - handlers.</para> - - <para>* [JBREM-359] - MultiplexInvokerConfigTestCase should execute - MultiplexInvokerConfigTestServer instead of - MultiplexInvokerTestServer.</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 1.4.0 final</para> - - <para>** Feature Request</para> - - <para>* [JBREM-91] - UIL2 type transport (duplex calling of same - socket)</para> - - <para>* [JBREM-117] - clean up callback client after several failures - delivering callbacks</para> - - <para>* [JBREM-138] - HTTP/Servlet invokers require content length to be - set</para> - - <para>* [JBREM-229] - Remove dependency on ThreadLocal for - SerializationManagers and pluggable serialization</para> - - <para>* [JBREM-233] - Server side exception listeners for client - connections</para> - - <para>* [JBREM-257] - Append client stack trace to thrown remote - exception</para> - - <para>* [JBREM-261] - Integration with IMarshalledValue from - JBossCommons</para> - - <para>* [JBREM-278] - remoting detection needs ability to accept detection - of server invoker running locally</para> - - <para>* [JBREM-280] - no way to add path to invoker uri when using complex - configuration</para> - - <para>** Bug</para> - - <para>* [JBREM-41] - problem using localhost/127.0.0.1</para> - - <para>* [JBREM-115] - http server invoker does not wait to finish processing - on stop</para> - - <para>* [JBREM-223] - Broken Pipe if client don't do any calls before the - timeout value</para> - - <para>* [JBREM-224] - java.net.SocketTimeoutException when socket timeout on - the keep alive</para> - - <para>* [JBREM-231] - bug in invoker locator when there are no params - (NPE)</para> - - <para>* [JBREM-234] - StreamCorruptedException in DTM testcase</para> - - <para>* [JBREM-240] - TestUtil does not always give free port for - server</para> - - <para>* [JBREM-243] - socket client invoker sharing pooled - connections</para> - - <para>* [JBREM-250] - InvokerLocator doesn't support URL in IPv6 format (ex: - socket://3000::117:5400/)</para> - - <para>* [JBREM-251] - transporter passes method signature based on concrete - object and not the parameter type</para> - - <para>* [JBREM-256] - NullPointer in MarshallerLoaderHandler.java:69</para> - - <para>* [JBREM-259] - Unmarshalling of server response is not using caller's - classloader</para> - - <para>* [JBREM-271] - http client invoker needs to explicitly set the - content type if not provided</para> - - <para>* [JBREM-277] - error shutting down coyote invoker when using APR - protocol</para> - - <para>* [JBREM-281] - getting random port for connectors is not - reliable</para> - - <para>* [JBREM-282] - ServletServerInvoker not working with depployed for - use as ejb invoker</para> - - <para>* [JBREM-286] - Socket server does not clean up server threads on - shutdown</para> - - <para>* [JBREM-289] - PortUtil only checking for free ports on - localhost</para> - - <para>** Task</para> - - <para>* [JBREM-7] - Add more tests for local invoker</para> - - <para>* [JBREM-121] - improve connection failure callback</para> - - <para>* [JBREM-126] - add tests for client vs. server address - bindings</para> - - <para>* [JBREM-195] - Performance optimization</para> - - <para>* [JBREM-199] - remoting clients required to include - servlet-api.jar</para> - - <para>* [JBREM-207] - clean up build file</para> - - <para>* [JBREM-214] - multiplex performance tests getting out of memory - error</para> - - <para>* [JBREM-215] - re-write http transport/handler documentation</para> - - <para>* [JBREM-216] - Need to add new samples to example build in - distro</para> - - <para>* [JBREM-217] - create samples documentation</para> - - <para>* [JBREM-219] - move remoting site to jboss labs</para> - - <para>* [JBREM-226] - Release JBoss Remoting 1.4.0 final</para> - - <para>* [JBREM-230] - create interface for marshallers to implement for - swapping out serialization impl</para> - - <para>* [JBREM-235] - add new header to source files</para> - - <para>* [JBREM-239] - Update the LGPL headers</para> - - <para>* [JBREM-242] - Subclass multiplex invoker from socket invoker.</para> - - <para>* [JBREM-249] - http invoker (tomcat connector) documentation</para> - - <para>* [JBREM-253] - Convert http server invoker implementation to use - tomcat connector and protocols</para> - - <para>* [JBREM-255] - HTTPClientInvoker not setting response code or - message</para> - - <para>* [JBREM-275] - fix package error in examle-service.xml</para> - - <para>* [JBREM-276] - transporter does not throw original exception from - server implementation</para> - - <para>* [JBREM-279] - socket server invoker spits out error messages on - shutdown when is not needed</para> - - <para>* [JBREM-287] - need to complete javadoc for all user - classes/interfaces</para> - - <para>* [JBREM-288] - update example-service.xml with new - configurations</para> - - <para>** Reactor Event</para> - - <para>* [JBREM-241] - Refactor SocketServerInvoker so that can be subclassed - by MultiplexServerInvoker</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 1.4.0 beta</para> - - <para></para> - - <para>** Feature Request</para> - - <para>* [JBREM-28] - Marshaller for non serializable objects</para> - - <para>* [JBREM-40] - Compression marshaller/unmarshaller</para> - - <para>* [JBREM-120] - config for using hostname in locator url instead of - ip</para> - - <para>* [JBREM-140] - can not set response headers from invocation - handlers</para> - - <para>* [JBREM-148] - support pluggable object serialization packages</para> - - <para>* [JBREM-175] - Remove Dependencies to Server Classes from - UnifiedInvoker</para> - - <para>* [JBREM-180] - add plugable serialization</para> - - <para>* [JBREM-187] - Better HTTP 1.1 stack support for HTTP invoker</para> - - <para>* [JBREM-201] - Remove dependency from JBossSerialization</para> - - <para></para> - - <para>** Bug</para> - - <para>* [JBREM-127] - RMI Invoker will not bind to specified address</para> - - <para>* [JBREM-192] - distro contains samples in src and examples - directory</para> - - <para>* [JBREM-193] - HTTPClientInvoker doesn't call getErrorStream() on - HttpURLConnection when an error response code is returned</para> - - <para>* [JBREM-194] - multiplex performance tests hang</para> - - <para>* [JBREM-202] - getUnmarshaller always calls Class.forName operation - for creating Unmarshallers</para> - - <para>* [JBREM-203] - rmi server invoker hangs if custom unmarshaller</para> - - <para>* [JBREM-205] - Spurious java.net.SocketException: Connection reset - error logging</para> - - <para>* [JBREM-210] - InvokerLocator should be insensitive to parameter - order</para> - - <para></para> - - <para>** Task</para> - - <para>* [JBREM-9] - Fix performance tests</para> - - <para>* [JBREM-33] - Add GET support within HTTP server invoker</para> - - <para>* [JBREM-145] - convert user guide from MS word doc to docbook</para> - - <para>* [JBREM-182] - Socket timeout too short (and better error - message)</para> - - <para>* [JBREM-183] - keep alive support for http invoker</para> - - <para>* [JBREM-196] - reducde the number of retries for socket client - invoker</para> - - <para>* [JBREM-204] - create complex remoting example using dynamic proxy to - endpoint</para> - - <para>* [JBREM-212] - create transporter implementation</para> - - <para>* [JBREM-213] - allow config of ignoring https host validation (ssl) - via metadata</para> - - <para></para> - - <para></para> - - <para>** Patch</para> - - <para>* [JBREM-152] - NullPointerException in SocketServerInvoker.stop() at - line 185.</para> - - <para>* [JBREM-153] - LocalClientInvoker's outlive their useful lifetime, - causing anomalous behavior</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 1.2.1 final</para> - - <para>** Feature Request</para> - - <para>* [JBREM-161] - Upgrade JRunit to Beta 2</para> - - <para>** Bug</para> - - <para>* [JBREM-147] - Invalid reuse of target location</para> - - <para>* [JBREM-163] - NPE in Mutlicast Detector</para> - - <para>* [JBREM-164] - HTTP Invoker unable to send large amounts of - data</para> - - <para>* [JBREM-176] - Correct inheritance structure for detectors</para> - - <para>* [JBREM-177] - configuration attribute spelled incorrectly in - ServerInvokerMBean</para> - - <para>* [JBREM-178] - SocketServerInvoker hanging on Linux</para> - - <para>* [JBREM-179] - socket timeout not being set properly</para> - - <para>** Task</para> - - <para>* [JBREM-156] - Better exception handling within socket server - invoker</para> - - <para>* [JBREM-158] - Clean up test cases</para> - - <para>* [JBREM-162] - add version to the remoting jar</para> - - <para>Release Notes - JBoss Remoting - Version 1.2.0 final</para> - - <para>** Feature Request</para> - - <para>* [JBREM-8] - Ability to stream files via remoting</para> - - <para>* [JBREM-22] - Manipulation of the client proxy interceptor - stack</para> - - <para>* [JBREM-24] - Allow for specific network interface bindings</para> - - <para>* [JBREM-27] - Support for HTTP/HTTPS proxy</para> - - <para>* [JBREM-35] - Servlet Invoker - counterpart to HTTP Invoker (runs - within web container)</para> - - <para>* [JBREM-43] - custom socket factories</para> - - <para>* [JBREM-46] - Connection failure callback</para> - - <para>* [JBREM-87] - Add handler metadata to detection messages</para> - - <para>* [JBREM-93] - Callback handler returning a generic Object</para> - - <para>* [JBREM-94] - callback server specific implementation</para> - - <para>* [JBREM-109] - Add support for JaasSecurityDomain within SSL - support</para> - - <para>* [JBREM-122] - need log4j.xml in examples</para> - - <para>** Bug</para> - - <para>* [JBREM-58] - Bug with multiple callback handler registered with same - server</para> - - <para>* [JBREM-64] - Need MarshalFactory to produce new instance per get - request</para> - - <para>* [JBREM-84] - Duplicate Connector shutdown using same server - invoker</para> - - <para>* [JBREM-92] - in-VM push callbacks don't work</para> - - <para>* [JBREM-97] - Won't compile under JDK 1.5</para> - - <para>* [JBREM-108] - can not set bind address and port for rmi and - http(s)</para> - - <para>* [JBREM-114] - getting callbacks for a callback handler always - returns null</para> - - <para>* [JBREM-125] - can not configure transport, port, or host for the - stream server</para> - - <para>* [JBREM-131] - invoker registry not update if server invoker changes - locator</para> - - <para>* [JBREM-134] - can not remove callback listeners from multiple - callback servers</para> - - <para>* [JBREM-137] - Invalid RemoteClientInvoker reference maintained by - InvokerRegistry after invoker disconnect()</para> - - <para>* [JBREM-141] - bug connecting client invoker when client detects that - previously used one is disconnected</para> - - <para>* [JBREM-143] - NetworkRegistry should not be required for detector to - run on server side</para> - - <para>** Task</para> - - <para>* [JBREM-11] - Create seperate JBoss Remoting module in CVS</para> - - <para>* [JBREM-20] - break out remoting into two seperate projects</para> - - <para>* [JBREM-34] - Need to add configuration properties for HTTP server - invoker</para> - - <para>* [JBREM-39] - start connector on new thread</para> - - <para>* [JBREM-55] - Clean up Callback implementation</para> - - <para>* [JBREM-57] - Remove use of InvokerRequest in favor of Callback - object</para> - - <para>* [JBREM-62] - update UnifiedInvoker to use remote marshall - loading</para> - - <para>* [JBREM-67] - Add ability to set ThreadPool via configuration</para> - - <para>* [JBREM-98] - remove isDebugEnabled() within code as is now - depricated</para> - - <para>* [JBREM-101] - Fix serialization versioning between releases of - remoting</para> - - <para>* [JBREM-104] - Release JBossRemoting 1.1.0</para> - - <para>* [JBREM-110] - create jboss-remoting-client.jar</para> - - <para>* [JBREM-113] - Convert remote tests to use JRunit instead of - distributed test framework</para> - - <para>* [JBREM-123] - update detection samples</para> - - <para>* [JBREM-128] - standardize address and port binding configuration for - all transports</para> - - <para>* [JBREM-130] - updated wiki for checkout and build</para> - - <para>* [JBREM-132] - write test case for JBREM-131</para> - - <para>* [JBREM-133] - Document use of Client (as a session object)</para> - - <para>* [JBREM-135] - Remove ClientInvokerAdapter</para> - - <para>** Reactor Event</para> - - <para>* [JBREM-65] - move callback specific classes into new callback - package</para> - - <para>* [JBREM-111] - pass socket's output/inputstream directly to - marshaller/unmarshaller</para> - - <para>Release Notes - JBoss Remoting - Version 1.0.2 final</para> - - <para>** Bug</para> - - <para>* [JBREM-36] - performance tests fail for http transports</para> - - <para>* [JBREM-66] - Race condition on startup</para> - - <para>* [JBREM-82] - Bad warning in Connector.</para> - - <para>* [JBREM-88] - HTTP invoker only binds to localhost</para> - - <para>* [JBREM-89] - HTTPUnMarshaller finishing read early</para> - - <para>* [JBREM-90] - HTTP header values not being picked up on the http - invoker server</para> - - <para>** Task</para> - - <para>* [JBREM-70] - Clean up build.xml. Fix .classpath and .project for - eclipse</para> - - <para>* [JBREM-83] - Updated Invocation marshalling to support standard - payloads</para> - - <para>Release Notes - JBoss Remoting - Version 1.0.1 final</para> - - <para>** Feature Request</para> - - <para>* [JBREM-54] - Need access to HTTP response headers</para> - - <para>** Bug</para> - - <para>* [JBREM-1] - Thread.currentThread().getContextClassLoader() is - wrong</para> - - <para>* [JBREM-31] - Exception handling in http server invoker</para> - - <para>* [JBREM-32] - HTTP Invoker - check for threading issues</para> - - <para>* [JBREM-50] - Need ability to set socket timeout on socket client - invoker</para> - - <para>* [JBREM-59] - Pull callback collection is unbounded - possible Out of - Memory</para> - - <para>* [JBREM-60] - Incorrect usage of debug level logging</para> - - <para>* [JBREM-61] - Possible RMI exception semantic regression</para> - - <para>** Task</para> - - <para>* [JBREM-15] - merge UnifiedInvoker from remoting branch</para> - - <para>* [JBREM-30] - Better integration for registering invokers with - MBeanServe</para> - - <para>* [JBREM-37] - backport to 4.0 branch before 1.0.1 final - release</para> - - <para>* [JBREM-56] - Add Callback object instead of using - InvokerRequest</para> - - <para>** Reactor Event</para> - - <para>* [JBREM-51] - defining marshaller on remoting client</para> - - <para></para> - - <para>Release Notes - JBoss Remoting - Version 1.0.1 beta</para> - - <para></para> - - <para>** Bug</para> - - <para>* [JBREM-19] - Try to reconnect on connection failure within socket - invoker</para> - - <para>* [JBREM-25] - Deadlock in InvokerRegistry</para> - - <para></para> - - <para>** Feature Request</para> - - <para>* [JBREM-12] - Support for call by value</para> - - <para>* [JBREM-26] - Ability to use MBeans as handlers</para> - - <para></para> - - <para>** Task</para> - - <para>* [JBREM-3] - Fix Asyn invokers - currently not operable</para> - - <para>* [JBREM-4] - Added test for throwing exception on server side</para> - - <para>* [JBREM-5] - Socket invokers needs to be fixed</para> - - <para>* [JBREM-16] - Finish HTTP Invoker</para> - - <para>* [JBREM-17] - Add CannotConnectException to all transports</para> - - <para>* [JBREM-18] - Backport remoting from HEAD to 4.0 branch</para> - - <para></para> - - <para></para> - - <para>** Reactor Event</para> - - <para>* [JBREM-23] - Refactor Connector so can configure transports</para> - - <para>* [JBREM-29] - Over load invoke() method in Client so metadata not - required</para> - - <para></para> -</chapter> \ No newline at end of file + <para>If you have questions, comments, bugs, fixes, contributions, or + flames, please post them to the JBoss Remoting users forum <!--<link linkend="???">http://www.jboss.com/index.html?module=bb&... + (<ulink + url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... + http://www.jboss.com/index.html?module=bb&amp;op=viewforum&amp;f=222 + </ulink>). You can also find more information about JBoss Remoting on our + <!--<link linkend="???">http://www.jboss.org/wiki/Wiki.jsp?page=Remoti... + wiki (<ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=Remoting"> + http://www.jboss.org/wiki/Wiki.jsp?page=Remoting </ulink> ). The wiki will + usually contain the latest updates to doc and features that did not make it + into the previous release.</para> + </chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap3.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap3.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap3.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -50,6 +50,16 @@ <para><code>new InvokerLocator("http://localhost:1234/services/uri:Test").isSameEndpoint(new InvokerLocator("http://127.0.0.1:1234"))</code> returns false</para> + <para><emphasis role="bold">N.B.</emphasis> As of version 2.4, + <classname>InvokerLocator</classname> uses the class + <classname>java.net.URI</classname>, rather than its original ad hoc parsing + code, to parse the String passed to its constructor. If, for some reason, the + new algorithm causes problems for legacy code, it is possible to configure + <classname>InvokerLocator</classname> to use the original parsing code by + calling the static method + <methodname>org.jboss.remoting.InvokerLocator.setUseLegacyParsing()</methodname>. + </para> + <para><emphasis role="bold">org.jboss.remoting.transport.Connector</emphasis> - is an MBean that loads a particular ServerInvoker implementation for a given transport Modified: remoting2/branches/2.x/docs/guide/en/chap4.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap4.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap4.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -60,11 +60,6 @@ <para><emphasis role="bold">jboss-remoting-rmi.jar</emphasis> - contains all the classes needed for the rmi and sslrmi transports to function as a client and a server.</para> - - <para><emphasis role="bold">jboss-remoting-multiplex.jar</emphasis> - - contains all the classes needed for the multiplex and sslmultiplex - transports to function as a client and a server. Use of this jar also - requires jboss-remoting-socket.jar be on classpath as well.</para> <para><emphasis role="bold">jboss-remoting-bisocket.jar</emphasis> - contains all the classes needed for the bisocket and sslbisocket transports @@ -131,11 +126,13 @@ <para><emphasis role="bold">HTTP server:</emphasis> jboss-remoting-http.jar, tomcat-coyote.jar, tomcat-util.jar, - commons-logging-api.jar, tomcat-http.jar</para> + tomcat-http.jar, commons-logging-api.jar; alternatively, the tomcat jars + can be replaced by jbossweb.jar</para> - <para>Note: need tomcat-apr.jar and tcnative-1.dll/tcnative-1.so on - system path if want to use APR based tomcat connector</para> - + <para>Note: need tomcat-apr.jar (if using tomcat jars) and + tcnative-1.dll/tcnative-1.so on system path to use APR based tomcat + connector</para> + <para><emphasis role="bold">HTTP client:</emphasis> jboss-remoting-http-client.jar</para> @@ -149,9 +146,6 @@ <para><emphasis role="bold">RMI server and client:</emphasis> jboss-remoting-rmi.jar</para> - <para><emphasis role="bold">Multiplex server and client:</emphasis> - jboss-remoting-socket.jar, jboss-remoting-multiplex.jar</para> - <para><emphasis role="bold">JBoss serialization:</emphasis> jboss-serialization.jar, trove.jar</para> </section> Modified: remoting2/branches/2.x/docs/guide/en/chap5.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap5.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap5.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -2,15 +2,17 @@ <chapter> <title>Configuration</title> - <para>This covers the configuration for JBoss Remoting discovery, - connectors, marshallers, and transports. All the configuration properties - specified can be set either via calls to the object itself, including via - JMX (so can be done via the JMX or Web console), or via a JBoss AS service - xml file. Examples of service xml configurations can be seen with each of - the sections below. There is also an example-service.xml file included in - the remoting distribution that shows full examples of all the remoting - configurations.</para> - + <para>This covers the configuration for JBoss Remoting discovery, connectors, + marshallers, and transports. All the configuration properties specified can be + set either via calls to the object itself, including via JMX (so can be done + via the JMX or Web console), via a JBoss AS service xml file. Examples of + service xml configurations can be seen with each of the sections below. There + is also an example-service.xml file included in the remoting distribution that + shows full examples of all the remoting configurations. In the presence of the + JBoss Microcontainer, Remoting servers may be configured by the injection of + an <classname>org.jboss.remoting.ServerConfiguration</classname> object + specified in an *-beans.xml file.</para> + <section id="section-configuration" xreflabel="General transport configuration"> <title>General transport configuration</title> @@ -48,7 +50,8 @@ file and use it to configure MBeans such as <classname>Connector</classname>s.</para> - <section> + <section id="section-programmatic-configuration" xreflabel="Programmatic configuration"> + <title>Programmatic configuration.</title> <para>The simplest way to configure a <classname>Connector</classname> @@ -184,14 +187,54 @@ <para>An example of this option in use can be found in <classname>org.jboss.test.remoting.configuration.SocketClientConfigurationTestCase</classname>.</para> - </section> + <para>A fifth option, which exists primarily to support the injection of + POJOs in the presence of the JBoss Microcontainer, is to pass an + <classname>org.jboss.remoting.ServerConfiguration</classname> object to + the <methodname>Connector.setServerConfiguration()</methodname> method. + The following fragment duplicates the behavior of the first and second + examples above.</para> + + <programlisting> + HashMap config = new HashMap(); + config.put(ServerInvoker.TIMEOUT, 120000); + Connector connector = new Connector(config); + + // Create ServerConfiguration object for socket transport + ServerConfiguration serverConfig = new ServerConfiguration("socket"); + + // Add invokerLocatorParameters (applicable to client and server) + Map locatorConfig = new HashMap(); + locatorConfig.put("serverBindAddress", "test.somedomain.com"); + locatorConfig.put("serverBindPort", "8084"); + serverConfig.setInvokerLocatorParameters(locatorConfig); + + // Add serverParameters (applicable to server) + Map serverParameters = new HashMap(); + locatorConfig.put("clientLeasePeriod", "10000"); + serverConfig.setServerParameters(serverParameters); + + // Add invocation handlers + Map handlers = new HashMap(); + handlers.put("mock", "org.jboss.remoting.transport.mock.SampleInvocationHandler"); + serverConfig.setInvocationHandlers(handlers); + + connector.setServerConfiguration(serverConfig); + connector.create(); + connector.start(); + </programlisting> + + <para>For more information about <classname>ServerConfiguration</classname>, + see the section "Declarative configuration: POJOs".</para> + + </section> + <section> - <title>Declarative configuration</title> + <title>Declarative configuration: MBeans</title> - <para>The configuration option discussed at the end of the previous - section, passing an XML document to the - <classname>Connector</classname>, works in conjunction with the + <para>One configuration option discussed in Section <xref + linkend="section-programmatic-configuration" />, passing an XML document + to the <classname>Connector</classname>, works in conjunction with the service archive deployer (SARDeployer) inside the JBoss Application Server to allow declarative configuration on the server side. In particular, the SARDeployer reads XMl documents containing MBean @@ -235,7 +278,7 @@ in greater detail is to provide an <code>invoker</code> sub-element within the config element of the Configuration attribute. The only attribute of invoker element is transport, which will specify which - transport type to use (e.g.. socket, rmi, http, or multiplex). All the + transport type to use (e.g.. socket, rmi, or http). All the sub-elements of the invoker element will be attribute elements with a name attribute specifying the configuration property name and then the value. An <code>isParam</code> attribute can also be added to indicate @@ -314,6 +357,96 @@ </section> <section> + <title>Declarative configuration: POJOs</title> + + <para>The last configuration option discussed in Section <xref + linkend="section-programmatic-configuration" />, passing an + <classname>org.jboss.remoting.ServerConfiguration</classname> object to + the <methodname>Connector.setServerConfiguration()</methodname> method, + works in conjunction with the JBoss Microcontainer, which supports the + injection of POJOs. In particular, the Microcontainer reads XML + documents containing POJO descriptors from files whose name has the form + "*-beans.xml".</para> + + <para>A <classname>ServerConfiguration</classname> object holds four components:</para> + + <itemizedlist> + <listitem> + <para>transport (supplied by constructor)</para> + </listitem> + <listitem> + <para>invokerLocatorParameters: this is a map of all parameter names + and values that will go into the + org.jboss.remoting.InvokerLocator</para> + </listitem> + <listitem> + <para>serverParameters: this is a map of parameter names and values + that will be used by the server but will not go into the + InvokerLocator</para> + </listitem> + <listitem> + <para>invocationHandlers: this is a map of invocation handlers. The key + is the subsystem, or comma separated list of subsystems.</para> + </listitem> + </itemizedlist> + + <para>An sample remoting-beans.xml file which duplicates the example in the + previous sections is:</para> + + <programlisting> + &lt;?xml version="1.0" encoding="UTF-8"?&gt; + &lt;deployment xmlns="urn:jboss:bean-deployer:2.0"&gt; + + &lt;bean name="remoting:invocationHandler" class="org.jboss.remoting.transport.mock.SampleInvocationHandler"/&gt; + + &lt;bean name="remoting:serverConfiguration" class="org.jboss.remoting.ServerConfiguration"&gt; + &lt;constructor&gt; + &lt;parameter&gt;socket&lt;/parameter&gt; + &lt;/constructor&gt; + &lt;property name="invokerLocatorParameters"&gt; + &lt;map keyClass="java.lang.String" valueClass="java.lang.String"&gt; + &lt;entry&gt; + &lt;key&gt;serverBindAddress&lt;/key&gt; + &lt;value&gt;test.somedomain.com&lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt;serverBindPort&lt;/key&gt; + &lt;value&gt;8084&lt;/value&gt; + &lt;/entry&gt; + &lt;/map&gt; + &lt;/property&gt; + &lt;property name="serverParameters"&gt; + &lt;map keyClass="java.lang.String" valueClass="java.lang.String"&gt; + &lt;entry&gt; + &lt;key&gt;clientLeasePeriod&lt;/key&gt; + &lt;value&gt;10000&lt;/value&gt; + &lt;/entry&gt; + &lt;/map&gt; + &lt;/property&gt; + &lt;property name="invocationHandlers"&gt; + &lt;map keyClass="java.lang.String" valueClass="org.jboss.remoting.ServerInvocationHandler"&gt; + &lt;entry&gt; + &lt;key&gt;mock&lt;/key&gt; + &lt;value&gt;&lt;inject bean="remoting:invocationHandler"/&gt;&lt;/value&gt; + &lt;/entry&gt; + &lt;/map&gt; + &lt;/property&gt; + &lt;/bean&gt; + + &lt;bean name="remoting:connector" class="org.jboss.remoting.transport.Connector"&gt; + &lt;property name="serverConfiguration"&gt;&lt;inject bean="remoting:serverConfiguration"/&gt;&lt;/property&gt; + &lt;/bean&gt; + + &lt;/deployment&gt; + </programlisting> + + <para>For more information about using the JBoss Microcontainer, see + <ulink url="http://www.jboss.org/jbossmc/"> + http://www.jboss.org/jbossmc/</ulink>.</para> + + </section> + + <section> <title>Callback client configuration</title> <para> @@ -392,7 +525,7 @@ is covered in <xref linkend="section-socket-factories" />.</para> <para>Finally, a third programmatic option is available for those - configuration properties which happen to be client invoker MBean + configuration properties which happen to be settable client invoker properties. In the following fragment, the client invoker is obtained from the <classname>Client</classname> and a <classname>SocketFactory</classname> is passed to it by way of a setter @@ -418,7 +551,7 @@ after that method has been called.</para> </section> </section> - + <section> <title>Handlers</title> @@ -807,14 +940,268 @@ </section> <section> - <title>Transports (Invokers)</title> + <title>Transports (Invokers)</title> - <para>This section covers configuration issues for each of the transports, - beginning with a set of properties that apply to all transports. The - material in a later section in this chapter, <xref - linkend="section-socket-factories" />, also applies to all - transports.</para> + <para>This section covers configuration issues for each of the transports, + beginning with material that applies to all transports. The + material in a later section in this chapter, <xref + linkend="section-socket-factories" />, also applies to all + transports.</para> + + <section> + <title>Features introduced in Remoting version 2.4</title> + <para>A number of transport independent features are introduced in Remoting + version 2.4.</para> + + <section> + <title>Multihome servers</title> + + <para>Before version 2.4, a Remoting server could bind either to a specific IP address, e.g., + </para> + + <programlisting>socket://192.168.0.2:6500</programlisting> + + <para>or to <emphasis>all</emphasis> IP addresses on a given host, e.g.,</para> + + <programlisting>socket://0.0.0.0:6500</programlisting> + + <para>As of release 2.4, it is possible to a configure a server to bind to a + subset of the interfaces available on a given host. Suppose, for example, + that a host machine has NICs configured with addresses 10.32.4.2, + 192.168.4.2, and 192.168.8.2, and suppose that 192.168.8.2 is on a LAN from + which access is meant to be denied. It is now possible to create a single + server that binds to 10.32.4.2 and 192.168.4.2.</para> + + <para>It would be convenient to be able to create an <classname>InvokerLocator</classname> + that looks something like:</para> + + <programlisting>socket://10.32.4.2&amp;192.168.4.2:6500</programlisting> + + <para>but, unfortunately, that violates the URI syntax. Instead, a special + placeholder, "multihome", is used in the host position, and the actual host + addresses are given in the query component, e.g.,</para> + + <programlisting>socket://multihome/?homes=10.32.4.2:6500!192.168.4.2:6500</programlisting> + + <para>An abbreviated syntax allows factoring out the bind port:</para> + + <programlisting>socket://multihome:6500/?homes=10.32.4.2!192.168.4.2</programlisting> + + <para>The value in the port position is treated as a default value which can be + overriden in the "homes" parameter:</para> + + <programlisting>socket://multihome:6500/?homes=10.32.4.2!192.168.4.2:6501</programlisting> + + <para>binds to 10.32.4.2:6500 and 192.168.4.2:6501.</para> + + <para>In the presence of a NAT router, it may be necessary for the client to + connect to addresses different than the bind addresses, and a set of connect + addresses may be specified with a "connecthomes" parameter:</para> + + <programlisting>socket://multihome/?homes=10.32.4.2:6500!192.168.4.2:6501&amp;connecthomes=10.32.42.2:7500!192.168.42.2:7501</programlisting> + + <para>specifies a server that binds to 10.32.4.2:6500 and 192.168.4.2:6501, + as before, but now a client connects to it using the addresses + 10.32.42.2:7500 and 192.168.42.2:7501.</para> + + <para>Multihome servers may be configured, also, in *-service.xml MBean + files and *-beans.xml POJO files. The following MBean definition is + equivalent to the preceding locator:</para> + + <programlisting> + &lt;mbean code="org.jboss.remoting.transport.Connector" + name="jboss.remoting:service=Connector,transport=Socket" + display-name="Socket transport Connector"&gt; + + &lt;attribute name="Configuration"&gt; + &lt;config&gt; + &lt;invoker transport="socket"&gt; + <emphasis role="bold"> + &lt;attribute name="homes"&gt; + &lt;home&gt;10.32.4.2:6500&lt;/home&gt; + &lt;home&gt;192.168.4.2:6501&lt;/home&gt; + &lt;/attribute&gt; + &lt;attribute name="connecthomes"&gt; + &lt;connecthome&gt;10.32.42.2:7500&lt;/connecthome&gt; + &lt;connecthome&gt;192.168.42.2:7501&lt;/connecthome&gt; + &lt;/attribute&gt; + </emphasis> + &lt;/invoker&gt; + &lt;handlers&gt; + ... + &lt;/handlers&gt; + &lt;/config&gt; + &lt;/attribute&gt; + &lt;/mbean&gt; + </programlisting> + + <para>The "serverBindPort" and "clientConnectPort" attributes may be used to + give default values for bind ports and connect ports, respectively.</para> + + <para>The same server may be configured with the + <classname>org.jboss.remoting.ServerInvocation</classname> object as well. + For example,</para> + <programlisting> + Connector connector = new Connector(); + + // Create ServerConfiguration object for socket transport + ServerConfiguration serverConfig = new ServerConfiguration("socket"); + + // Add invokerLocatorParameters (applicable to client and server) + Map locatorConfig = new HashMap(); + <emphasis role="bold"> + locatorConfig.put("homes", "10.32.4.2:6500!192.168.4.2:6501"); + locatorConfig.put("connecthomes", "10.32.42.2:7500!192.168.42.2:7501"); + </emphasis> + serverConfig.setInvokerLocatorParameters(locatorConfig); + + // Add invocation handlers + ... + + connector.setServerConfiguration(serverConfig); + connector.create(); + connector.start(); + </programlisting> + + <para>is equivalent to the preceding MBean definition.</para> + + <para><emphasis role="bold">Note.</emphasis> The Strings "homes" and + "connecthomes" are available as constants in the + <classname>InvokerLocator</classname> class: + <code>InvokerLocator.HOMES_KEY</code> and + <code>InvokerLocator.CONNECT_HOMES_KEY</code>.</para> + </section> + + <section> + <title>Socket creation listeners</title> + + <para>Sometimes it is useful to be able to grab a socket right after it + has been created to either apply some additional configuration or + retrieve some information. It is possible to configure Remoting with + instantions of the interface + <classname>org.jboss.remoting.socketfactory.SocketCreationListener</classname> + </para> + + <programlisting> + public interface SocketCreationListener + { + /** + * Called when a socket has been created. + * + * @param socket socket that has been created + * @param source SocketFactory or ServerSocket that created the socket + * @throws IOException + */ + void socketCreated(Socket socket, Object source) throws IOException; + } + </programlisting> + + <para>Socket creation listeners can be configured through the use of + the keys + <code>org.jboss.remoting.Remoting.SOCKET_CREATION_CLIENT_LISTENER</code> + (actual value "socketCreationClientListener") and + <code>org.jboss.remoting.Remoting.SOCKET_CREATION_SERVER_LISTENER</code> + (actual value "socketCreationServerListener"), which install listeners + for <code>javax.net.SocketFactory</code>s and + <code>java.net.ServerSocket</code>s, respectively. The value associated + with these keys may be (1) an object that implements + <classname>SocketCreationListener</classname> or (2) a string that + names a class that implements + <classname>SocketCreationListener</classname>. In the latter case, the + default constructor will be used to create an object of the designated + class.</para> + </section> + + <section> + <title>Making client IP address available to application</title> + + <para>All of the transports (bisocket, sslbisocket, http, https, rmi, + sslrmi, servlet, sslservlet, socket, and sslsocket) capture the IP + address of the client side of a TCP connection from client to server + and make it available to application code on both the client side and + server side. On the client side, the method + <methodname>org.jboss.remoting.Client.getAddressSeenByServer()</methodname>, + with signature</para> + + <programlisting> + public InetAddress getAddressSeenByServer() throws Throwable + </programlisting> + + <para>returns the IP address of the client as seen by the server. On + the server side, the same IP address is placed in the request payload + map held by the + <classname>org.jboss.remoting.InvocationRequest</classname>. It may be + retrieved by the + <classname>org.jboss.remoting.ServerInvocationHandler</classname> as + follows:</para> + + <programlisting> + public Object invoke(InvocationRequest invocation throws Throwable + { + ... + InetAddress address = invocation.getRequestPayload().get(Remoting.CLIENT_ADDRESS); + ... + } + </programlisting> + </section> + + + <section> + <title>Support for IPv6 IP addresses</title> + + <para><classname>org.jboss.remoting.InvokerLocator</classname> will now + accept IPv6 IP addresses. For example,</para> + + <programlisting> + socket://[::1]:3333/?timeout=10000 + socket://[::]:4444/?timeout=10000 + socket://[::ffff:127.0.0.1]:5555/?timeout=10000 + socket://[fe80::205:9aff:fe3c:7800%7]:6666/?timeout=10000 + socket://multihome/?homes=[fe80::205:9aff:fe3c:7800%7]:7777![fe80::214:22ff:feef:68bb%4]:8888 + </programlisting> + </section> + + <section> + <title>Delayed destruction of client invokers</title> + + <para>Multiple clients may share a single client invoker. For example, in the code</para> + + <programlisting> + InvokerLocator locator = new InvokerLocator("socket://127.0.0.1:5555"); + Client client1 = new Client(locator); + Client client2 = new Client(locator); + </programlisting> + + <para><code>client1</code> and <code>client2</code> will both + communicate with the server through a single + <classname>org.jboss.remoting.transport.socket.MicroSocketClientInvoker</classname>. + The number of <classname>Client</classname>s using a single client + invoker is tracked, and the invoker is destroyed when the count goes to + zero. It may be useful to delay the destruction of the invoker when it + is known that another <classname>Client</classname> will want to use it + in the near future. The delayed destruction of a client invoker may be + achieved through the use of the key + <code>Client.INVOKER_DESTRUCTION_DELAY</code> (actual value + "invokerDestructionDelay"). For example,</para> + + <programlisting> + InvokerLocator locator = new InvokerLocator("socket://127.0.0.1:5555/?invokerDestructionDelay=5000"); + Client client = new Client(locator); + client.connect(); + ... + client.disconnect(); + </programlisting> + + <para>will cause <code>client</code> to delay the destruction of its + client invoker (assuming <code>client</code> is the only user), by 5000 + milliseconds. Of course, "invokerDestructionDelay" may be passed to the + <classname>Client</classname> by way of a configuration map, as + well.</para> + + </section> + </section> + <section> <title>Server Invokers</title> @@ -944,161 +1331,52 @@ </section> <section> - <title>Socket Invoker</title> + <title>Socket transport</title> - <para>The following configuration properties can be set at any time, but - will not take effect until the socket invoker, on the server side, is - stopped and restarted.</para> - - <para><emphasis role="bold">timeout</emphasis> - The socket timeout - value passed to the Socket.setSoTimeout() method. The default on the - server side is 60000 (one minute). If the timeout parameter is set, its - value will also be passed to the client side (see below).</para> - - <para><emphasis role="bold">backlog</emphasis> - The preferred number of - unaccepted incoming connections allowed at a given time. The actual - number may be greater than the specified backlog. When the queue is - full, further connection requests are rejected. Must be a positive value - greater than 0. If the value passed if equal or less than 0, then the - default value will be assumed. The default value is 200.</para> - - <para><emphasis role="bold">numAcceptThreads</emphasis> - The number of - threads that exist for accepting client connections. The default is - 1.</para> - - <para><emphasis role="bold">maxPoolSize</emphasis> - The number of - server threads for processing client. The default is 300.</para> - - <para><emphasis role="bold">serverSocketClass</emphasis> - specifies the - fully qualified class name for the custom SocketWrapper implementation - to use on the server.</para> - - <para><emphasis role="bold">socket.check_connection</emphasis> - - indicates if the invoker should try to check the connection before - re-using it by sending a single byte ping from the client to the server - and then back from the server. This config needs to be set on both - client and server to work. This if false by default.</para> - - <para><emphasis role="bold">idleTimeout</emphasis> - indicates the - number of seconds a pooled server thread can be idle (meaning time since - last invocations request processed) before it should be cleaned up and - removed from the thread pool. The value for this property must be - greater than zero in order to enable idle timeouts on pooled server - threads (otherwise they will not be checked). Setting to value less than - zero will disable idle timeout checks on pooled server threads, in the - case was previously enabled. The default value for this property is - -1.</para> - - <bridgehead>Configurations affecting the Socket invoker - client</bridgehead> - - <para>There are some configurations which will impact the socket invoker - client. These will be communicated to the client invoker via parameters - in the Locator URI. These configurations can not be changed during - runtime, so can only be set up upon initial configuration of the socket - invoker on the server side. The following is a list of these and their - effects.</para> - - <para><emphasis role="bold">enableTcpNoDelay</emphasis> - can be either - true or false and will indicate if client socket should have TCP_NODELAY - turned on or off. TCP_NODELAY is for a specific purpose; to disable the - Nagle buffering algorithm. It should only be set for applications that - send frequent small bursts of information without getting an immediate - response; where timely delivery of data is required (the canonical - example is mouse movements). The default is false.</para> - - <para><emphasis role="bold">timeout</emphasis> - The socket timeout - value passed to the Socket.setSoTimeout() method. The default on the - client side is 1800000 (or 30 minutes).</para> - - <para><emphasis role="bold">clientMaxPoolSize</emphasis> - the client - side maximum number of active socket connections. This basically equates - to the maximum number of concurrent client calls that can be made from - the socket client invoker. The default is 50.</para> - - <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 implementation - to use on the client. Note, will need to make sure this is marked as a - client parameter (using the 'isParam' attribute). Making this change - will not affect the marshaller/unmarshaller that is used, which may also - be a requirement.</para> - - <para><emphasis role="bold">socket.check_connection</emphasis> - - indicates if the invoker should try to check the connection before - re-using it by sending a single byte ping from the client to the server - and then back from the server. This config needs to be set on both - client and server to work. This if false by default.</para> - - <para>An example of locator uri for a socket invoker that has - TCP_NODELAY set to false and the client's max pool size of 30 would - be:</para> - - <para><code> - socket://test.somedomain.com:8084/?enableTcpNoDelay=false&amp;maxPoolSize=30 - </code></para> - - <para>To reiterate, these client configurations can only be set within - the server side configuration and will not change during runtime.</para> - + <para>The Socket transport 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> + <section> - <title>How the Socket Invoker works</title> + <title>How the Socket transport 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><emphasis role="bold">Server</emphasis></bridgehead> - <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, + <para>When the socket server invoker is started, it will create one, and + only one, instance of <classname>java.net.ServerSocket</classname> for + each configured bind address. Typically there would exactly one + <classname>ServerSocket</classname>, but there would be more than one + for a mltihome server with multiple bind addresses. 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> - + by the "numAcceptThreads" property. If "numAcceptThreads" is set to "n" + (it defaults to 1), there will be "n" accept threads per + <classname>ServerSocket</classname>. 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> + to as server threads + (<classname>org.jboss.remoting.transport.socket.ServerThread</classname>), + are stored in a pool. The accept thread will try to retrieve 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 @@ -1119,7 +1397,7 @@ 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 + the "backlog" property and can be useful in managing sudden bursts in requests.</para> <para>If take an example with a socket server invoker that has max @@ -1147,23 +1425,74 @@ data from the client. Inactive server threads are ones that have finished processing on a particular socket connection and have been returned to the thread pool for later reuse. </para> + + <para><emphasis role="bold">Note.</emphasis> As of Remoting version 2.4, + some changes have been made to + <classname>ServerThread</classname>.</para> + + <orderedlist> + <listitem> + <para>Once a server thread has completed an invocation, it will try + to read another invocation instead of returning to the thread pool. + It follows that the fact that a server thread is not in the thread + pool does not necessarily indicate that it is busy: it might just + be blocked in a <methodname>InputStream.read()</methodname>. + Therefore, when an accept thread needs a server thread and the + thread pool is empty, it will try to appropriate server threads + which are not in the thread pool. While a server thread is in the + middle of processing an invocation, it cannot be interrupted, but + if it is blocked waiting for the next invocation, it is available + to be interrupted. However, when the server is busy, it is + conceivable for an accept thread to grab a server thread and before + the server thread gets a chance to read an invocation, it gets + interrupted again by the accept thread. To prevent server threads + from bouncing around like that, the parameter + <code>ServerThread.EVICTABILITY_TIMEOUT</code> (actual value + "evictabilityTimeout) has been introduced. If less than that period + has elapsed since the server thread has started waiting for the + next invocation, it will not allow itself to be pre-empted. </para> + </listitem> + + <listitem> + <para>Prior to version 2.4, if a server thread experienced a + <classname>java.net.SocketTimeoutException</classname>, it would + return itself to the thread pool and could not be reused until a + new socket connection was created for it to use. In principle, it + would be more efficient for the server thread simply to try again + to read the next invocation. Unfortunately, + <classname>java.io.ObjectInputStream</classname> ceases to function + once it experiences a + <classname>SocketTimeoutException</classname>. The good news is + that + <classname>org.jboss.serial.io.JBossObjectInputStream</classname>, + made available by the JBossSerialization project, does not suffer + from that problem. Therefore, when it experiences a + <classname>SocketTimeoutException</classname>, a server thread will + check whether it is using a + <classname>JBossObjectInputStream</classname> or not and act + accordingly. Just to allow for the possibility that an application + is using yet another version of + <classname>ObjectInputStream</classname>, the parameter + <code>ServerThread.CONTINUE_AFTER_TIMEOUT</code> (actual value + "continueAfterTimeout") allows the behavior following a + <classname>SocketTimeoutException</classname> to be configured + explicitly.</para> + </listitem> + </orderedlist> - <bridgehead>client</bridgehead> + <bridgehead><emphasis role="bold">Client</emphasis></bridgehead> - <para>When the socket client invoker makes its first invocation, it - will check to see if there is an available socket connection in its - pool. Since is the first invocation, there will not be and will create - a new socket connection and use it for making the invocation. Then - when finished making invocation, will return the still active socket - connection to the pool. As more client invocations are made, is - possible for the number of socket connections to reach the maximum - allowed (which is controlled by 'clientMaxPoolSize' property). At this - point, when the next client invocation is made, it will keep trying to - get an available connection from the pool, waiting 1 second in between - tries for up to maximum number of retries (which is controlled by the - numberOfRetries property). If runs out of retries, will throw - SocketException saying how long it waited to find available socket - connection.</para> + <para>When the socket client invoker makes its first invocation, it will + check to see if there is an available socket connection in its pool. + Since is the first invocation, there will not be and will create a new + socket connection and use it for making the invocation. Then when + finished making invocation, will return the still active socket + connection to the pool. As more client invocations are made, is possible + for the number of socket connections to reach the maximum allowed (which + is controlled by 'clientMaxPoolSize' property). At this point, when the + next client invocation is made, it will wait up to 30 seconds, at which + point it will throw an + <classname>org.jboss.remoting.InvocationFailureException</classname>.</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 @@ -1179,10 +1508,165 @@ occur is when have had a burst of client invocations and then a long period of inactivity.</para> </section> + + <section> + <title>Configuration</title> + + <para>The following configuration properties can be set at any time, but + will not take effect until the socket invoker, on the server side, is + stopped and restarted.</para> + + <para><emphasis role="bold">timeout</emphasis> - The socket timeout + value passed to the Socket.setSoTimeout() method. The default on the + server side is 60000 (one minute). If the timeout parameter is set, its + value will also be passed to the client side (see below).</para> + + <para><emphasis role="bold">backlog</emphasis> - The preferred number of + unaccepted incoming connections allowed at a given time. The actual + number may be greater than the specified backlog. When the queue is + full, further connection requests are rejected. Must be a positive value + greater than 0. If the value passed if equal or less than 0, then the + default value will be assumed. The default value is 200.</para> + + <para><emphasis role="bold">numAcceptThreads</emphasis> - The number of + threads that exist for accepting client connections. The default is + 1.</para> + + <para><emphasis role="bold">maxPoolSize</emphasis> - The number of + server threads for processing client. The default is 300.</para> + + <para><emphasis role="bold">serverSocketClass</emphasis> - specifies the + fully qualified class name for the custom SocketWrapper implementation + to use on the server.</para> + + <para><emphasis role="bold">socket.check_connection</emphasis> - + indicates if the invoker should try to check the connection before + re-using it by sending a single byte ping from the client to the server + and then back from the server. This config needs to be set on both + client and server to work. This if false by default.</para> + + <para><emphasis role="bold">idleTimeout</emphasis> - indicates the + number of seconds a pooled server thread can be idle (meaning time since + last invocations request processed) before it should be cleaned up and + removed from the thread pool. The value for this property must be + greater than zero in order to enable idle timeouts on pooled server + threads (otherwise they will not be checked). Setting to value less than + zero will disable idle timeout checks on pooled server threads, in the + case was previously enabled. The default value for this property is + -1.</para> + + <para><emphasis role="bold">evictabilityTimeout</emphasis> - indicates + the number of milliseconds during which a server thread waiting for the + next invocation will not be interruptible.</para> + + <para><emphasis role="bold">continueAfterTimeout</emphasis> - indicates + what a server thread should do after experiencing a + <classname>java.net.SocketTimeoutException</classname>. If set to + "true", the server thread will continue to wait for an invocation; + otherwise, it will return itself to the thread pool.</para> + + <bridgehead>Configurations affecting the Socket invoker + client</bridgehead> + + <para>There are some configurations which will impact the socket invoker + client. They can be set in the <classname>InvokerLocator</classname>, an + MBean or bean XML configuration file, or can be passed in the + configuration map when the <classname>Client</classname> is + created.</para> + + <para><emphasis role="bold">enableTcpNoDelay</emphasis> - can be either + true or false and will indicate if client socket should have TCP_NODELAY + turned on or off. TCP_NODELAY is for a specific purpose; to disable the + Nagle buffering algorithm. It should only be set for applications that + send frequent small bursts of information without getting an immediate + response; where timely delivery of data is required (the canonical + example is mouse movements). The default is false.</para> + + <para><emphasis role="bold">timeout</emphasis> - The socket timeout + value passed to the Socket.setSoTimeout() method. The default on the + client side is 1800000 (or 30 minutes).</para> + + <para><emphasis role="bold">clientMaxPoolSize</emphasis> - the client + side maximum number of active socket connections. This basically equates + to the maximum number of concurrent client calls that can be made from + the socket client invoker. The default is 50.</para> + + <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 implementation + to use on the client. Note, will need to make sure this is marked as a + client parameter (using the 'isParam' attribute). Making this change + will not affect the marshaller/unmarshaller that is used, which may also + be a requirement.</para> + + <para><emphasis role="bold">socket.check_connection</emphasis> - + indicates if the invoker should try to check the connection before + re-using it by sending a single byte ping from the client to the server + and then back from the server. This config needs to be set on both + client and server to work. This if false by default.</para> + + <para>An example of locator uri for a socket invoker that has + TCP_NODELAY set to false and the client's max pool size of 30 would + be:</para> + + <para><code> + socket://test.somedomain.com:8084/?enableTcpNoDelay=false&amp;maxPoolSize=30 + </code></para> + + <para><emphasis role="bold">Note.</emphasis> As of Remoting version 2.4, + the following socket parameters, in addition to SO_TIMEOUT and + TCP_NODELAY, can be configured on the client client side: SO_KEEPALIVE, + OOBINLINE, SO_RCVBUF, SO_REUSEADDR, SO_SNDBUF, SO_LINGER, and "traffic + class". They are configured by the following parameter keys:</para> + + <para><emphasis role="bold">keepAlive</emphasis> - sets socket parameter + SO_KEEPALIVE</para> + + <para><emphasis role="bold">oOBInline</emphasis> - sets socket parameter + OOBINLINE</para> + + <para><emphasis role="bold">receiveBufferSize</emphasis> - sets socket + parameter SO_RCVBUF</para> + + <para><emphasis role="bold">reuseAddress</emphasis> - sets socket + parameter SO_REUSEADDR</para> + + <para><emphasis role="bold">sendBufferSize</emphasis> - sets socket + parameter SO_SNDBUF</para> + + <para><emphasis role="bold">soLinger</emphasis> - sets socket parameter + SO_LINGER</para> + + <para><emphasis role="bold">soLingerDuration</emphasis> - when socket + parameter SO_LINGER is set to "true", sets linger duration</para> + + <para><emphasis role="bold">trafficClass</emphasis> - sets socket + traffic class</para> + + <para>For more information about these parameters, see the + <classname>java.net.Socket</classname> javadoc (<ulink + url="http://java.sun.com/j2se/1.4.2/docs/api/java/net/Socket.html&qu... + http://java.sun.com/j2se/1.4.2/docs/api/java/net/Socket.html</ulink>) or + a book about the TCP protocol.</para> + </section> + </section> <section> - <title>SSL Socket Invoker</title> + <title>SSL Socket transport</title> <para>Supports all the configuration attributes as the Socket Invoker. The main difference is that the SSL Socket Invoker uses an @@ -1192,7 +1676,7 @@ </section> <section> - <title>RMI Invoker</title> + <title>RMI transport</title> <para><emphasis role="bold">registryPort</emphasis> - the port on which to create the RMI registry. The default is 3455. This also needs to have @@ -1205,6 +1689,18 @@ methods discussed in section <xref linkend="section-socket-factories" />, then the user is responsible for supplying a serializable socket factory.</para> + + <para><emphasis role="bold">Note.</emphasis> Prior to Remoting version + 2.4, the RMI transport performed marshalling and unmarshalling only in the + client to server direction. As of version 2.4, it will use a marshaller + and unmarshaller in the server to client direction, as well. Moreover, + marshalling and unmarshalling in the client to server direction has been + made more efficient, which results in the transmission of a different + sequence of bytes. In case a version 2.4 release of Remoting needs to + communicate with an older version, it is possible to request the original + marshalling behavior by setting the parameter + <code>org.jboss.remoting.transport.rmi.RMIServerInvoker.RMI_ONEWAY_MARSHALLING</code> + (actual value "rmiOnewayMarshalling") to "true".</para> </section> <section> @@ -1227,50 +1723,57 @@ </section> <section id="section-http-invoker" xreflabel="HTTP Invoker"> - <title>HTTP Invoker</title> + <title>HTTP transport</title> - <para>The HTTP server invoker implementation is based on the Apache - Tomcat connector components which support GET, POST, HEAD, OPTIONS, and - HEAD method types and keep-alive. Therefore, most any configuration - allowed for Tomcat can be configured for the remoting HTTP server - invoker. For more information on the configuration attributes available - for the Tomcat connectors, please refer to <ulink + <para>The HTTP server invoker implementation is based on the Coyote + HTTP/1.1 Connector Tomcat component, which may be supplied either by the + apache implementation, in jars tomcat-coyote.jar, tomcat-util.jar, and + tomcat-http.jar, or in the JBossWeb implementation, in jbossweb.jar. The + coyote Connector supports GET, POST, HEAD, OPTIONS, and HEAD method types + and keep-alive, and most any configuration allowed for Tomcat can be + configured for the remoting HTTP server invoker. For more information on + the configuration attributes available for the Tomcat connectors, please + refer to <ulink url="http://tomcat.apache.org/tomcat-5.5-doc/config/http.html"&...;. - http://tomcat.apache.org/tomcat-5.5-doc/config/http.html - <!--<link linkend="???">http://tomcat.apache.org/tomcat-5.5-doc/config... - So for example, if wanted to set the maximum number of threads to be - used to accept incoming http requests, would use the 'maxThreads' - attribute. The only exception when should use remoting configuration - over the Tomcat configuration is for attribute 'address' (use - serverBindAddress instead) and attribute 'port' (use serverBindPort - instead).</para> - + http://tomcat.apache.org/tomcat-5.5-doc/config/http.html <!--<link + linkend="???">http://tomcat.apache.org/tomcat-5.5-doc/config... + So for example, if wanted to set the maximum number of threads to be used + to accept incoming http requests, would use the 'maxThreads' attribute. + The only exception when should use remoting configuration over the Tomcat + configuration is for attribute 'address' (use serverBindAddress instead) + and attribute 'port' (use serverBindPort instead).</para> + <para>Note: The http invoker no longer has the configuration attributes 'maxNumThreadsHTTP' or 'HTTPThreadPool' as thread pooling is now handled within the Tomcat connectors, which does not expose external API for setting these.</para> - + + <para>A feature introduced in Remoting version 2.4 is the ability to + configure <classname>HTTPClientInvoker</classname> to make multiple + attempts to complete an invocation. The feature is invoked by setting + parameter <code>HTTPClientInvoker.NUMBER_OF_CALL_ATTEMPTS</code> (actual + value "numberOfCallAttempts") to the desired integer. The parameter can be + configured in the <classname>InvokerLocator</classname> or in the + configuration map passed to the <classname>Client</classname>. The default + value is 1.</para> + <para>Since the remoting HTTP server invoker implementation is using Tomcat connectors, is possible to swap out the Tomcat protocol implementations being used. By default, the protocol being used is <code>org.apache.coyote.http11.Http11Protocol</code>. However, it is possible to switch to use the - <code>org.apache.coyote.http11.Http11AprProtocol</code> protocol, which - is based on the Apache Portable Runtime (see <ulink + <code>org.apache.coyote.http11.Http11AprProtocol</code> protocol, which is + based on the Apache Portable Runtime (see <ulink url="http://tomcat.apache.org/tomcat-5.5-doc/apr.html">http:... - and <ulink url="http://apr.apache.org/">http://apr.apache.org/</ulin... - for more details). If want to use the APR implementation, simply put the - tcnative-1.dll (or tcnative-1.so) on the system path so can be loaded. - The APR native binaries can be found at <ulink - url="http://tomcat.heanet.ie">http://tomcat.heanet.ie</ulink>.</para> - - <para>Note: There is a bug with release 1.1.1 of APR where get an error - upon shutting down (see JBREM-277 for more information). This does not - impact anything while running, but is still an issue when shutting down - (as upon starting up again, can get major problems). This should be - fixed in a later release of APR so can just replace the 1.1.1 version of - tcnative-1.dll with the new one.</para> - + and <ulink url="http://apr.apache.org/">http://apr.apache.org/</ulin... for + more details). If want to use the APR implementation, simply put the + tcnative-1.dll (or tcnative-1.so) on the system path so can be loaded. The + JBossWeb native libraries, which include tcnative-1.dll/tcnative-1.so, may + be downloaded from <ulink + url="http://www.jboss.org/jbossweb/">http://www.jboss.org/jb...;. + The Apache versions of the APR native binaries can be found at <ulink + url="http://www.gtlib.gatech.edu/pub/apache">http://www.gtli... + <bridgehead>Client request headers</bridgehead> <para>The HTTP Invoker allows for some of the properties to be passed as @@ -1293,10 +1796,48 @@ <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>Response headers</bridgehead> + + <para>If a request on the HTTP transport is made with the + <classname>org.jboss.remoting.Client</classname> method</para> + + <programlisting> + public Object invoke(Object param, Map metadata) throws Throwable + </programlisting> + + <para>then + <classname>org.jboss.remoting.transport.http.HTTPClientInvoker</classname> + returns the HTTP response headers in a map in metadata, associated with + the key + <code>org.jboss.remoting.transport.http.HTTPMetadataConstants.RESPONSE_HEADERS</code> + (actual value "ResponseHeaders"). For example, the response header "Date" + can be retrieved as follows:</para> + + <programlisting> + Object payload = ... ; + HashMap metadata = new HashMap(); + client.invoke(payload, metadata); + Map responseHeaders = (Map) metadata.get(HTTPMetadataConstants.RESPONSE_HEADERS); + String date = (String) responseHeaders.get("Date"); + </programlisting> + + <bridgehead>CR/LF in HTTP transport</bridgehead> + + <para>By default, the HTTP transport uses + <classname>org.jboss.remoting.marshal.http.HTTPMarshaller</classname> and + <classname>org.jboss.remoting.marshal.http.HTTPUnMarshaller</classname> to + marshal and unmarshal invocations and responses. Prior to Remoting version + 2.4, <classname>HTTPUnMarshaller</classname> stripped CR/LF characters. As + of version 2.4, the default behavior remains the same, but it is possible + to change the behavior, on the client and the server, by setting the + parameter <code>HTTPUnMarshaller.PRESERVE_LINES</code> (actual value + "preserveLines") to "true". </para> + </section> - + <section> - <title>HTTPS Invoker</title> + <title>HTTPS transport</title> <para>Supports all the configuration attributes as the HTTP Invoker, plus the following:</para> @@ -1436,7 +1977,7 @@ </section> <section> - <title>Servlet Invoker</title> + <title>Servlet transport</title> <para>The servlet invoker is a server invoker implementation that uses a servlet running within a web container to accept initial client @@ -1538,17 +2079,34 @@ 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> - - <para>One of the issues of using Servlet invoker is that the invocation - handlers (those that implement ServerInvocationHandler) can not return - very much detail in regards to a web context. For example, the content - type used for the response is the same as that of the request.</para> + + <para><emphasis role="bold">Note.</emphasis> Prior to Remoting version + 2.4, + <classname>org.jboss.remoting.transport.servlet.ServletServerInvoker</classname> + generated a single MBean ObjectName for representing + <classname>ServletServerInvoker</classname>s as MBeans, which meant that + an MBeanServer could be aware of only a single + <classname>ServletServerInvoker</classname> MBean. As of version 2.4, that + restriction has been eliminated.</para> + + <para><emphasis role="bold">Note.</emphasis> Prior to Remoting version + 2.4, when + <classname>org.jboss.remoting.transport.servlet.web.ServerInvokerServlet</classname> + retrieved an MBeanServer, it looked only for an MBeanServer whose default + domain was "jboss". As of version 2.4, the default domain can be + configured by adding an "mbeanServer" init-param element to the web.xml + file. If the "mbeanServer" value is set to "*platform*" and jdk 1.5 or + greater is in use, <classname>ServerInvokerServlet</classname> will + retrieve the platform MBeanServer by calling + <methodname>java.lang.management.ManagementFactory.getPlatformMBeanServer()</methodname>. + In the absence of a configured default domain, + <classname>ServerInvokerServlet</classname> will still use "jboss" as the + default domain.</para> + </section> <section> - <title>SSL Servlet Invoker</title> + <title>SSL Servlet transport</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'. @@ -1624,913 +2182,56 @@ 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 + 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 thrown 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 + server. Throwing an exception may be turned off with the parameter <code>HTTPMetadataConstants.NO_THROW_ON_ERROR</code> (actual text value - 'NoThrowOnError') and a value of of type java.lang.String set to 'true'. - This will cause the http client invoker to not throw an exception, but - instead return the data from the web server error stream. In the case - that the data returned from this error stream is of type - java.lang.String (i.e. is error html), it will be wrapped in a - WebServerError and returned as this type. The raw data from the web - server can the be retrieved by getting the WebServerError's - message.</para> - </section> + "NoThrowOnError") set to "true". This parameter may be passed in the + <classname>InvokerLocator</classname> or configuration map when the + <classname>org.jboss.remoting.Client</classname> is created, or it may be + included in the metadata map passed to</para> + + <programlisting> + public Object invoke(Object param, Map metadata) throws Throwable; + </programlisting> + . + <para>This will cause the http client invoker to not throw an exception, + but instead return the data from the web server error stream. In the case + that the data returned from this error stream is of type java.lang.String + (i.e. is error html), it will be wrapped in a WebServerError and returned + as this type. The raw data from the web server can the be retrieved by + getting the WebServerError's message.</para> + + <para><emphasis role="bold">Note.</emphasis> Prior to Remoting version + 2.4, the servlet transport returned a simple error message in the event of + an error on the server side. As of version 2.4, the discussion about + exception handling applies to the servlet and sslservlet transports as + well. The original behavior of returning an error message can be requested + by configuring the server with the parameter + <code>org.jboss.remoting.transport.http.HTTPMetadataConstants.DONT_RETURN_EXCEPTION</code> + (actual value "dont-return-exception") set to "true".</para> + + </section> <section id="section-multiplex-invoker" xreflabel="Multiplex Invoker"> - <title>Multiplex Invoker</title> + <title>Multiplex transport</title> - <para>The multiplex invoker is intended to replicate the functionality - of the socket invoker with the added feature that it supports multiple - streams of communication over a single pair of sockets. Multiplexing may - be motivated by, for example, a desire to conserve socket resources or - by firewall restrictions on port availability. This additional service - is made possible by the Multiplex subproject, which provides "virtual" - sockets and "virtual" server sockets. Please refer to the Multiplex - documentation at</para> - - <blockquote> - <para><ulink - url="http://labs.jboss.com/portal/jbossremoting/docs/index.html"... - http://labs.jboss.com/portal/jbossremoting/docs/index.html</ulink>&... - </blockquote> - - <para>for further details.</para> - - <para>In a typical multiplexed scenario a <classname>Client</classname> - on a client host, through a - <classname>MultiplexClientInvoker</classname> <emphasis>C</emphasis>, - could make synchronous method invocations to a - <classname>MultiplexServerInvoker</classname> on a server host, and at - the same time (and over the same TCP connection) asynchronous push - callbacks could be made to a - <classname>MultiplexServerInvoker</classname> <emphasis>S</emphasis> on - the client host. In this, the <emphasis role="bold">Prime - Scenario</emphasis>, which motivated the creation of the multiplex - invoker, <emphasis>C</emphasis> and <emphasis>S</emphasis> use two - different virtual sockets but share the same port and same actual - socket. We say that <emphasis>C</emphasis> and <emphasis>S</emphasis> - belong to the same <emphasis role="bold">invoker - group</emphasis>.</para> - - <para>One of the primary design goals of the Multiplex subsystem is for - virtual sockets and virtual server sockets to demonstrate behavior as - close as possible to their real counterparts, and, indeed, they - implement complete socket and server socket APIs. However, they are - necessarily different in some respects, and it follows that the - multiplex invoker is somewhat different than the socket invoker. In - particular, there are three areas specific to the multiplex invoker that - must be understood in order to use it effectively:</para> - - <orderedlist> - <listitem> - <para>Establishing on the server an environment prerequisite for - creating multiplex connections</para> - </listitem> - - <listitem> - <para>Configuring the client for multiplexed method invocations and - callbacks</para> - </listitem> - - <listitem> - <para>Shutting down invoker groups.</para> - </listitem> - </orderedlist> - - <section> - <title>Setting up the server</title> - - <para>There are two kinds of - <classname>MultiplexServerInvoker</classname>s, <emphasis - role="bold">master</emphasis> and <emphasis - role="bold">virtual</emphasis>, corresponding to the two kinds of - virtual server sockets: <classname>MasterServerSocket</classname> and - <classname>VirtualServerSocket</classname>. Briefly, the difference - between the two virtual server socket classes is that a - <classname>MasterServerSocket</classname> is derived from - <classname>java.net.ServerSocket</classname> and its - <methodname>accept()</methodname> method is implemented by way of the - inherited method <methodname>super.accept()</methodname>. A - <classname>MasterServerSocket</classname> can accept connect requests - from multiple machines. A <classname>VirtualServerSocket</classname>, - on the other hand, is based on an actual socket connected to another - actual socket on some host <emphasis>H</emphasis>, and consequently a - <classname>VirtualServerSocket</classname> can accept connect requests - only from <emphasis>H</emphasis>.</para> - - <para>Each multiplex connection depends on a pair of connected real - sockets, one on the client host and one on the server host, and this - connection is created when an actual socket contacts an actual server - socket. It follows that a multiplex connection begins with a - connection request to a <classname>MasterServerSocket</classname>. - Once the connection is established, it is possible to build up - <emphasis role="bold">virtual socket groups</emphasis>, consisting of - virtual sockets (and at most one - <classname>VirtualServerSocket</classname>) revolving around the - actual socket at each end of the connection. Each virtual socket in a - socket group at one end is connected to a virtual socket in the socket - group at the other end.</para> - - <para>Master and virtual - <classname>MultiplexServerInvoker</classname>s assume the - characteristics of their server sockets: - <classname>MasterServerSocket</classname> and - <classname>VirtualServerSocket</classname>, respectively. That is, a - master <classname>MultiplexServerInvoker</classname> can accept - requests from any host, while a virtual - <classname>MultiplexServerInvoker</classname> can accept requests only - from the particular host to which it has a multiplex connection. Since - a multiplex connection begins with a connection request to a - <classname>MasterServerSocket</classname>, it follows that the use of - the multiplex invoker must begin with a connection request from the - client (made by either a <classname>MultiplexClientInvoker</classname> - or a virtual <classname>MultiplexServerInvoker</classname>: see below) - to a master <classname>MultiplexServerInvoker</classname> on the - server. The master <classname>MultiplexServerInvoker</classname> - responds by "cloning" itself (metaphorically, not necessarily through - the use of <methodname>clone()</methodname>) into a virtual - <classname>MultiplexServerInvoker</classname> with the same parameters - and same set of invocation handlers but with a - <classname>VirtualServerSocket</classname> belonging to a new socket - group. In so doing the master - <classname>MultiplexServerInvoker</classname> builds up a <emphasis - role="bold">server invoker farm</emphasis> of virtual - <classname>MultiplexServerInvoker</classname>s, each in contact with a - different <classname>MultiplexClientInvoker</classname> over a - distinct multiplex connection. The virtual - <classname>MultiplexServerInvoker</classname>s do the actual work of - responding to method invocation requests, sent by their corresponding - <classname>MultiplexClientInvoker</classname>s through virtual sockets - in a socket group at the client end of a multiplex connection to - virtual sockets created by the - <classname>VirtualServerSocket</classname> in the socket group at the - server end of the connection. Note that virtual - <classname>MultiplexServerInvoker</classname>s share data structures - with the master, so that registering invocation handlers with the - master makes them available to the members of the farm. The members of - a master <classname>MultiplexServerInvoker</classname>'s invoker farm - are accessible by way of the methods</para> - - <blockquote> - <orderedlist> - <listitem> - <para><methodname>MultiplexServerInvoker.getServerInvokers()</methodname> - and</para> - </listitem> - - <listitem> - <para><methodname>MultiplexServerInvoker.getServerInvoker(InetSocketAddress)</methodname></para> - </listitem> - </orderedlist> - </blockquote> - - <para>the latter of which returns a virtual - <classname>MultiplexServerInvoker</classname> keyed on the address to - which its <classname>VirtualServerSocket</classname> is connected. - When the master <classname>MultiplexServerInvoker</classname> shuts - down, its farm of virtual invokers shuts down as well</para> - - <para>There are two ways of constructing a virtual - <classname>MultiplexServerInvoker</classname>, one being the cloning - method just discussed. It is also possible to construct one directly. - Once a multiplex connection is established, a virtual - <classname>MultiplexServerInvoker</classname> can be created with a - <classname>VirtualServerSocket</classname> belonging to a socket group - at one end of the connection. The - <classname>MultiplexServerInvoker</classname> constructor determines - whether to create a virtual or master invoker according to the - presence or absence of certain parameters, discussed below, that may - be added to its <classname>InvokerLocator</classname>. Server rules 1 - through 3 described below result in the construction of a virtual - <classname>MultiplexServerInvoker</classname>, and server rule 4 (the - absence of these parameters) results in the construction of a master - <classname>MultiplexServerInvoker</classname>.</para> - - <para>Setting up the server, then, is simply a matter of starting a - master <classname>MultiplexServerInvoker</classname> with a simple - <classname>InvokerLocator</classname>, unadorned with any parameters - specific to the multiplex invoker. As always, the server invoker is - not created directly but by way of a <classname>Connector</classname>, - as in the following:</para> - - <blockquote> - <programlisting> - Connector connector = new Connector(); - Connector.setInvokerLocator("multiplex://demo.jboss.com:8080"); - Connector.create() - Connector.start() - </programlisting> - </blockquote> - </section> - - <section> - <title>Setting up the client</title> - - <para>Before multiplex connections can be established, a master - <classname>MultiplexServerInvoker</classname> must be created as - described in the previous section. For example, the Prime Scenario - would begin with starting a master - <classname>MultiplexServerInvoker</classname> on the server host, - followed by starting, on the client host, a - <classname>MultiplexClientInvoker</classname> <emphasis>C</emphasis> - and a virtual <classname>MultiplexServerInvoker</classname> - <emphasis>S</emphasis> (in either order). The first to start initiates - a multiplex connection to the master - <classname>MultiplexServerInvoker</classname> and requests the - creation of a virtual <classname>MultiplexServerInvoker</classname>. - Note that it is crucial for <emphasis>C</emphasis> and - <emphasis>S</emphasis> to know that they are meant to share a - multiplex connection, i.e., that they are meant to belong to the same - invoker group. Consider the following attempt to set up a shared - connection between hosts bluemonkey.acme.com and demo.jboss.com. - First, <emphasis>C</emphasis> is initialized on host - bluemonkey.acme.com with the <classname>InvokerLocator</classname> - multiplex://demo.jboss.com:8080, and, assuming the absence of an - existing multiplex connection to demo.jboss.com:8080, a new virtual - socket group based on a real socket bound to an arbitrary port, say - 32000, is created. Then <emphasis>S</emphasis> is initialized with - <classname>InvokerLocator</classname> - multiplex://bluemonkey.acme.com:4444, but since it needs to bind to - port 4444, it is unable to share the existing connection. [Actually, - the example is slightly deceptive, since - multiplex://bluemonkey.acme.com:4040 would result in the creation of a - master <classname>MultiplexServerInvoker</classname>. But if it were - suitably extended with the parameters discussed below so that a - virtual <classname>MultiplexServerInvoker</classname> were created, - the virtual invoker would be unable to share the existing - connection.]</para> - - <para>So <emphasis>C</emphasis> and <emphasis>S</emphasis> need to - agree on the address and port of the real socket underlying the - virtual socket group they are intended to share on the client host and - the address and port of the real socket underlying the peer virtual - socket group on the server host. Or, more succintly, they must know - that they are meant to belong to the same invoker group. Note the - relationship between an invoker group and the virtual socket group - which supports it: a <classname>MultiplexClientInvoker</classname> - uses virtual sockets in its underlying virtual socket group, and a - <classname>MultiplexServerInvoker</classname> in an invoker group has - a <classname>VirtualServerSocket</classname> that creates virtual - sockets in the underlying virtual socket group.</para> - - <para><emphasis>C</emphasis> and <emphasis>S</emphasis> each get half - of the information necessary to identify their invoker group directly - from their respective <classname>InvokerLocator</classname>s. In - particular, <emphasis>C</emphasis> gets the remote address and port, - and <emphasis>S</emphasis> gets the binding address and port. The - additional information may be provided through the use of <emphasis - role="bold">invoker group parameters</emphasis>, which may be - communicated to <emphasis>C</emphasis> and <emphasis>S</emphasis> in - one of two ways:</para> - - <orderedlist> - <listitem> - <para>they may be appended to the - <classname>InvokerLocator</classname> passed to the - <classname>Client</classname> which creates <emphasis>C</emphasis> - and/or to the <classname>InvokerLocator</classname> passed to the - <classname>Connector</classname> which creates - <emphasis>S</emphasis></para> - </listitem> - - <listitem> - <para>they may be stored in a configuration - <classname>Map</classname> which is passed to the - <classname>Client</classname> and/or - <classname>Connector</classname>.</para> - </listitem> - </orderedlist> - - <para>In either case, there are two ways in which the missing - information can be supplied to <emphasis>C</emphasis> and - <emphasis>S</emphasis>:</para> - - <orderedlist> - <listitem> - <para>The information can be provided explicitly by way of invoker - group parameters:</para> - - <orderedlist> - <listitem> - <para><emphasis>multiplexBindHost</emphasis> and - <emphasis>multiplexBindPort</emphasis> parameters can be - passed to <emphasis>C</emphasis>, and</para> - </listitem> - - <listitem> - <para><emphasis>multiplexConnectHost</emphasis> and - <emphasis>multiplexConnectPort</emphasis> parameters can be - passed to <emphasis>S</emphasis>.</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para><emphasis>C</emphasis> and <emphasis>S</emphasis> can be - tied together by giving them the same <emphasis - role="bold">multiplexId</emphasis>, supplied by invoker group - parameters:</para> - - <orderedlist> - <listitem> - <para><emphasis>clientMultiplexId</emphasis>, for the - <classname>MultiplexClientInvoker</classname>, and</para> - </listitem> - - <listitem> - <para><emphasis>serverMultiplexId</emphasis>, for the - <classname>MultiplexServerInvoker</classname>.</para> - </listitem> - </orderedlist> - - <para>Giving them matching multiplexIds tells them that they are - meant to belong to the same invoker group and that they should - provide the missing information to each other.</para> - </listitem> - </orderedlist> - - <para>The behavior of a starting - <classname>MultiplexClientInvoker</classname> <emphasis>C</emphasis> - is governed by the following four <emphasis role="bold">client - rules</emphasis>:</para> - - <orderedlist> - <listitem> - <para>If <emphasis>C</emphasis> has a - <emphasis>clientMultiplexId</emphasis> parameter, it will use it - to attempt to find a <classname>MultiplexServerInvoker</classname> - <emphasis>S</emphasis> with a - <emphasis>serverMultiplexId</emphasis> parameter with the same - value. If it succeeds, it will retrieve binding host and port - values, create or reuse a suitable multiplex connection to the - server, and start. Moreover, if <emphasis>S</emphasis> was unable - to start because of insufficient information (server rule 3), then - <emphasis>C</emphasis> will supply the missing information and - <emphasis>S</emphasis> will start. Note that in this situation - <emphasis>C</emphasis> will ignore any - <emphasis>multiplexBindHost</emphasis> and - <emphasis>multiplexBindPort</emphasis> parameters passed to - it.</para> - </listitem> - - <listitem> - <para>If <emphasis>C</emphasis> does not find a - <classname>MultiplexServerInvoker</classname> through a - multiplexId (either because it did not get a - <emphasis>clientMultiplexId</emphasis> parameter or because there - is no <classname>MultiplexServerInvoker</classname> with a - matching multiplexId), but it does have - <emphasis>multiplexBindHost</emphasis> and - <emphasis>multiplexBindPort</emphasis> parameters, then it will - create or reuse a suitable multiplex connection to the server, and - start. Also, if it has a multiplexId, it will advertise itself for - the benefit of a <classname>MultiplexServerInvoker</classname> - that may come along later (see server rule 1).</para> - </listitem> - - <listitem> - <para>If <emphasis>C</emphasis> has a multiplexId and neither - finds a <classname>MultiplexServerInvoker</classname> with a - matching multiplexId nor has - <emphasis>multiplexBindHost</emphasis> and - <emphasis>multiplexBindPort</emphasis> parameters, then it will - not start, but it will advertise itself so that it may be found - later by a <classname>MultiplexServerInvoker</classname> (see - server rule 1).</para> - </listitem> - - <listitem> - <para>If <emphasis>C</emphasis> has neither - <emphasis>clientMultiplexId</emphasis> nor - <emphasis>multiplexBindHost</emphasis> and - <emphasis>multiplexBindPort</emphasis> parameters, it will create - or reuse a multiplex connection from an arbitrary local port to - the host and port given in its - <classname>InvokerLocator</classname>, and start.</para> - </listitem> - </orderedlist> - - <para>Similarly, the behavior of a starting - <classname>MultiplexServerInvoker</classname> <emphasis>S</emphasis> - is governed by the following four <emphasis role="bold">server - rules</emphasis>:</para> - - <orderedlist> - <listitem> - <para>If <emphasis>S</emphasis> has a - <emphasis>serverMultiplexId</emphasis> parameter, it will use it - to attempt to find a <classname>MultiplexClientInvoker</classname> - <emphasis>C</emphasis> with a matching - <emphasis>clientMultiplexId</emphasis>. If it succeeds, it will - retrieve server host and port values, create a - <classname>VirtualServerSocket</classname>, create or reuse a - suitable multiplex connection to the server, and start. Moreover, - if <emphasis>C</emphasis> was unable to start due to insufficient - information (client rule 3), then <emphasis>S</emphasis> will - supply the missing information and <emphasis>C</emphasis> will - start. Note that in this situation <emphasis>S</emphasis> will - ignore <emphasis>multiplexConnectHost</emphasis> and - <emphasis>multiplexConnectPort</emphasis> parameters, if any, in - its <classname>InvokerLocator</classname>.</para> - </listitem> - - <listitem> - <para>If <emphasis>S</emphasis> does not find a - <classname>MultiplexClientInvoker</classname> through a - multiplexId (either because it did not get a - <emphasis>serverMultiplexId</emphasis> parameter or because there - is no <classname>MultiplexClientInvoker</classname> with a - matching multiplexId), but it does have - <emphasis>multiplexConnectHost</emphasis> and - <emphasis>multiplexConnectPort</emphasis> parameters, then it will - create a <classname>VirtualServerSocket</classname>, create or - reuse a suitable multiplex connection to the server, and start. - Also, if it has a multiplexId, it will advertise itself for the - benefit of a <classname>MultiplexClientInvoker</classname> that - may come along later (see client rule 1).</para> - </listitem> - - <listitem> - <para>If <emphasis>S</emphasis> has a multiplexId and neither - finds a <classname>MultiplexClientInvoker</classname> with a - matching multiplexId nor has - <emphasis>multiplexConnectHost</emphasis> and - <emphasis>multiplexConnectPort</emphasis> parameters, then it will - not start, but it will advertise itself so that it may be found - later by a <classname>MultiplexClientInvoker</classname> (see - client rule 1).</para> - </listitem> - - <listitem> - <para>If <emphasis>S</emphasis> has neither - <emphasis>serverMultiplexId</emphasis> nor - <emphasis>multiplexConnectHost</emphasis> and - <emphasis>multiplexConnectPort</emphasis> parameters, it will - create a <classname>MasterServerSocket</classname> bound to the - host and port in its <classname>InvokerLocator</classname> and - start.</para> - </listitem> - </orderedlist> - - <section> - <title>Notes</title> - - <orderedlist> - <listitem> - <para>Like server invokers, client invokers are not started - directly but are started indirectly through calls to - <methodname>Client(InvokerLocator locator)</methodname>, such - as:</para> - - <programlisting> - Client client = new Client("multiplex://demo.jboss.com:8080/?clientMultiplexId=id0"); - client.connect(); - </programlisting> - - <para><emphasis role="bold">N.B.</emphasis> For the multiplex - invoker, it is important to call - <methodname>Client.connect()</methodname>. Otherwise, the last - <classname>MultiplexClientInvoker</classname> that leaves an - invoker group will not get a chance to shut the group - down.</para> - </listitem> - - <listitem> - <para>It should not be inferred that - <classname>MultiplexClientInvoker</classname>s and - <classname>MultiplexServerInvoker</classname>s belong to the - same invoker group <emphasis>only if </emphasis> they are - required to do so by invoker group parameters. In fact, if two - <classname>Client</classname>s are created with the - <classname>InvokerLocator</classname> - multiplex://demo.jboss.com, the second one, lacking any - constraints on its binding address and port, is certainly not - prevented from sharing a connection with the first. Rather, the - function of the invoker group parameters is to - <emphasis>force</emphasis> - <classname>MultiplexClientInvoker</classname>s and - <classname>MultiplexServerInvoker</classname>s to share a - connection.</para> - </listitem> - - <listitem> - <para>There are situations in which the method of passing - parameters by way of the configuration map is preferable to - appending them to an <classname>InvokerLocator</classname>. One - of the functions of an <classname>InvokerLocator</classname> is - to identify a server, and modifying the content of its - <classname>InvokerLocator</classname> may interfere with the - ability to locate the server. For example, one of the features - of JBoss Remoting is the substitution of method calls for remote - invocations when it discovers that a server runs in the same JVM - as the client. However, appending multiplex parameters to the - <classname>InvokerLocator</classname> by which the server is - identified will prevent the Remoting runtime from recognizing - the local presence of the server, and the optimization will not - occur.</para> - </listitem> - - <listitem> - <para>It is possible, and convenient, to set up a multiplexing - scenario using no parameters other than - <emphasis>clientMultiplexId</emphasis> and - <emphasis>serverMultiplexId</emphasis>. Note, however, that in - this case neither the <classname>Clients</classname> nor the - <classname>Connector</classname> will be fully initialized until - after both have been started. If the - <classname>Clients</classname> and the - <classname>Connector</classname> are to be started - independently, then the other parameters must be used. <emphasis - role="bold">N.B.</emphasis> If a <classname>Client</classname> - depends on <classname>Connector</classname> in the same invoker - group to supply binding information, it is an error to call - methods such as <methodname>Client.connect()</methodname> and - <methodname>Client.invoke()</methodname> until the - <classname>Connector</classname> has been started.</para> - </listitem> - - <listitem> - <para><classname>Clients</classname> and the optional - <classname>Connector</classname> may be created (and the - <classname>Connector</classname> started) in any order.</para> - </listitem> - </orderedlist> - </section> - </section> - - <section> - <title>Shutting down invoker groups.</title> - - <para>A virtual socket group will shut down, releasing a real socket - and a number of threads, when (1) its last member has closed and (2) - the socket group at the remote end of the multiplex connection agrees - to the proposed shut down. The second condition prevents a situation - in which a new virtual socket tries to join what it thinks is a viable - socket group at the same time that the peer socket group is shutting - down. So for a virtual socket group to shut down, all members at both - ends of the connection must be closed.</para> - - <para>The implication of this negotiated shutdown mechanism is that as - long as the <classname>VirtualServerSocket</classname> used by a - virtual <classname>MultiplexServerInvoker</classname> remains open, - resources at the client end of the connection cannot be freed, and for - this reason it is important to understand how to close virtual - <classname>MultiplexServerInvoker</classname>s.</para> - - <para>There are three ways in which a virtual - <classname>MultiplexServerInvoker</classname> that belongs to a master - <classname>MultiplexServerInvoker</classname>'s invoker farm can shut - down. <itemizedlist> - <listitem> - <para>When a master - <classname>MultiplexServerInvoker</classname> is closed, it - closes all of the virtual - <classname>MultiplexServerInvoker</classname>s it - created.</para> - </listitem> - - <listitem> - <para>A virtual <classname>MultiplexServerInvoker</classname> - can be retrieved by calling either - <methodname>MultiplexServerInvoker.getServerInvokers()</methodname> - or - <methodname>MultiplexServerInvoker.getServerInvoker(InetSocketAddress)</methodname> - on its master <classname>MultiplexServerInvoker</classname> and - then closed directly.</para> - </listitem> - - <listitem> - <para>When the <methodname>accept()</methodname> method of its - <classname>VirtualServerSocket</classname> times out, and when - it detects that all multiplex invokers in the invoker group at - the client end of the connection have shut down, a virtual - <classname>MultiplexServerInvoker</classname> will shut itself - down. Note that when all members leave an invoker group, it is - guaranteed not to be revived, i.e., no new members may - join.</para> - </listitem> - </itemizedlist> The third method insures that without any explicit - intervention, closing all multiplex invokers on the client (by way of - calling <methodname>Client.disconnect()</methodname> and - <methodname>Connector.stop()</methodname>) is guaranteed to result in - the eventual release of resources. The timeout period may be adjusted - by setting the <emphasis>timeout</emphasis> parameter (see below). - Alternatively, the second method, in conjunction with the use of - <methodname>MultiplexServerInvoker.isSafeToShutdown()</methodname>, - which returns <code>true</code> on - <classname>MultiplexServerInvoker</classname> <code>M</code> if and - only if (1) <code>M</code> is not virtual, or (2) all of the multiplex - invokers in the invoker group at the client end of <code>M</code>'s - connection have shut down. For example, a thread could be dedicated to - looking for useless <classname>MultiplexServerInvoker</classname>s and - terminating them before their natural expiration through timing - out.</para> - </section> - - <section> - <title>Examples</title> - - <para>The following are examples of setting up a client for - multiplexed synchronous and asynchronous communication. They each - assume the existence of a master - <classname>MultiplexServerInvoker</classname> running on - demo.jboss.com:8080.</para> - - <para>For complete examples see the section <xref - linkend="section-multiplex-invoker" />.</para> - - <orderedlist> - <listitem> - <para>A <classname>MultiplexClientInvoker</classname> - <emphasis>C</emphasis> starts first:</para> - - <programlisting> - String parameters = "multiplexBindHost=localhost&amp;multiplexBindPort=7070&amp;clientMultiplexId=demoId1"; - String locatorURI = "multiplex://demo.jboss.com:8080/?" + parameters; - InvokerLocator locator = new InvokerLocator(locatorURI); - Client client = new Client(locator); - client.connect(); - </programlisting> - - <para>and then it is found by a - <classname>MultiplexServerInvoker</classname> with a matching - multiplexId, which joins <emphasis>C</emphasis>'s invoker group - and starts:</para> - - <programlisting> - Connector connector = new Connector(); - String parameters = "serverMultiplexId=demoId1"; - String locatorURI = "multiplex://localhost:7070/?" + parameters; - InvokerLocator locator = new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - </programlisting> - </listitem> - - <listitem> - <para>A <classname>MultiplexClientInvoker</classname> - <emphasis>C</emphasis> starts:</para> - - <programlisting> - String parameters = "multiplexBindHost=localhost&amp;multiplexBindPort=7070"; - String locatorURI = "multiplex://demo.jboss.com:8080/?" + parameters; - InvokerLocator locator = new InvokerLocator(locatorURI); - Client client = new Client(locator); - client.connect(); - </programlisting> - - <para>and a <classname>MultiplexServerInvoker</classname> - <emphasis>S</emphasis> starts independently, joining - <emphasis>C</emphasis>'s invoker group by virtue of having - matching local and remote addresses and ports:</para> - - <programlisting> - Connector connector = new Connector(); - String parameters = "multiplexConnectHost=demo.jboss.com&amp;multiplexConnectPort=8080"; - String locatorURI = "multiplex://localhost:7070/?" + parameters; - InvokerLocator locator = new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - </programlisting> - </listitem> - - <listitem> - <para>A <classname>MultiplexClientInvoker</classname> - <emphasis>C</emphasis> is created but does not start:</para> - - <programlisting> - String parameters = "clientMultiplexId=demoId2"; - String locatorURI = "multiplex://demo.jboss.com:8080/?" + parameters; - InvokerLocator locator = new InvokerLocator(locatorURI); - Client client = new Client(locator); - </programlisting> - - <para>and then a <classname>MultiplexServerInvoker</classname> - <emphasis>S</emphasis> is created with a matching multiplexId, - allowing both <emphasis>C</emphasis> and <emphasis>S</emphasis> to - start:</para> - - <programlisting> - Connector connector = new Connector(); - String parameters = "serverMultiplexId=demoId2"; - String locatorURI = "multiplex://localhost:7070/?" + parameters; - InvokerLocator locator = new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - client.connect(); - </programlisting> - - <para>Note the call to <methodname>Client.connect()</methodname> - after the call to - <methodname>Connector.start()</methodname>.</para> - </listitem> - - <listitem> - <para>A <classname>MultiplexClientInvoker</classname> - <emphasis>C</emphasis> starts in an invoker group based on a real - socket bound to an arbitrary local port:</para> - - <programlisting> - String locatorURI = "multiplex://demo.jboss.com:8080"; - InvokerLocator locator = new InvokerLocator(locatorURI); - Client client = new Client(locator); - client.connect(); - </programlisting> - - <para>and then a <classname>MultiplexServerInvoker</classname> - <emphasis>S</emphasis> starts independently:</para> - - <programlisting> - Connector connector = new Connector(); - String locatorURI = "multiplex://localhost:7070"; - InvokerLocator locator = new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - </programlisting> - - <para>Note that <emphasis>S</emphasis> creates a - <classname>MasterServerSocket</classname> rather than a - <classname>VirtualServerSocket</classname> in this case and so - does not share a multiplex connection and does not belong to an - invoker group.</para> - </listitem> - - <listitem> - <para>This is example 1, rewritten so that the invoker group - parameters are passed by way of a configuration - <classname>Map</classname> instead of - <classname>InvokerLocator</classname>s. A - <classname>MultiplexClientInvoker</classname> - <emphasis>C</emphasis> starts first:</para> - - <programlisting> - String locatorURI = "multiplex://demo.jboss.com:8080"; - InvokerLocator locator = new InvokerLocator(locatorURI); - Map configuration = new HashMap(); - configuration.put(MultiplexInvokerConstants.MULTIPLEX_BIND_HOST_KEY, "localhost"); - configuration.put(MultiplexInvokerConstants.MULTIPLEX_BIND_PORT_KEY, "7070"); - configuration.put(MultiplexInvokerConstants.CLIENT_MULTIPLEX_ID_KEY, "demoId1"); - Client client = new Client(locator, configuration); - client.connect(); - </programlisting> - - <para>and then it is found by a - <classname>MultiplexServerInvoker</classname> with a matching - multiplexId, which joins <emphasis>C</emphasis>'s invoker group - and starts:</para> - - <programlisting> - String locatorURI = "multiplex://localhost:7070"; - InvokerLocator locator = new InvokerLocator(locatorURI); - Map configuration = new HashMap(); - configuration.put(MultiplexInvokerConstants.SERVER_MULTIPLEX_ID_KEY, "demoId1"); - Connector connector = new Connector(locator.getLocatorURI(), configuration); - connector.create(); - connector.start(); - </programlisting> - </listitem> - </orderedlist> - </section> - - <section> - <title>Configuration properties</title> - - <para>There are four categories of configuration properties supported - by the multiplex invoker, the last three of which are specific to the - multiplex invoker. Properties in categories 2 and 3 may be configured - by appending them to the server's locator URI. Properties in - categories 2, 3, and 4 may be configured by putting their values in a - configuration <classname>HashMap</classname> and passing the map to a - <classname>MultiplexServerInvoker</classname> and/or - <classname>MultiplexClientInvoker</classname> constructor, according - to the category. Constants for the property names in categories 2, 3, - and 4 are found in - <classname>org.jboss.remoting.transport.multiplex.Multiplex</classname>. - Note that some of them are also found in the older - <classname>org.jboss.remoting.transport.multiplex.MultiplexInvokerConstants</classname>, - but the use of that class is now deprecated.</para> - - <orderedlist numeration="arabic"> - <listitem> - <para>The following properties are managed by ancestor classes of - <classname>MultiplexServerInvoker</classname>. See the discussion - under <classname>SocketServerInvoker</classname> for more - information.</para> - - <para><emphasis role="bold">socketTimeout</emphasis> - The socket - timeout value passed to the - <methodname>Socket.setSoTimeout()</methodname> method and the - <methodname>ServerSocket.setSoTimeout()</methodname> method. The - default is 60000 (or 1 minute).</para> - - <para><emphasis role="bold">numAcceptThreads</emphasis> - The - number of threads that exist for accepting client connections. The - default is 1.</para> - </listitem> - - <listitem> - <para>The following properties are intended to be passed to a - virtual <classname>MultiplexServerInvoker</classname> to configure - its multiplex connection. These properties are specific to the - multiplex invoker.</para> - - <para><emphasis role="bold">multiplexConnectHost</emphasis> - the - name or address of the host to which the multiplex connection - should be made.</para> - - <para><emphasis role="bold">multiplexConnectPort</emphasis> - the - port to which the multiplex connection should be made.</para> - - <para><emphasis role="bold">serverMultiplexId</emphasis> - a - string that associates a - <classname>MultiplexServerInvoker</classname> with a - <classname>MultiplexClientInvoker</classname> with which it should - share a multiplex connection.</para> - - <para><emphasis role="bold">multiplex.maxAcceptErrors</emphasis> - - Master and virtual <classname>MultiplexServerInvoker</classname>s - keep a counter of errors experienced by their server socket, and - they terminate when this maximum is exceeded. Note that - <classname>SSLHandshakeException</classname>s are excluded from - the count, since they could indicate a client rather than server - error.</para> - </listitem> - - <listitem> - <para>The following properties are intended to be passed to a - virtual <classname>MultiplexClientInvoker</classname> to configure - its multiplex connection. These properties are specific to the - multiplex invoker.</para> - - <para><emphasis role="bold">multiplexBindHost</emphasis> - the - host name or address to which the local end of the multiplex - connection should be bound.</para> - - <para><emphasis role="bold">multiplexBindPort</emphasis> - the - port to which the local end of the multiplex connection should be - bound</para> - - <para><emphasis role="bold">clientMultiplexId</emphasis> - a - string that associates a - <classname>MultiplexClientInvoker</classname> with a - <classname>MultiplexServerInvoker</classname> with which it should - share a multiplex connection.</para> - </listitem> - - <listitem> - <para>There is also a set of properties which are specific to the - Multiplex subsystem internal classes. See the Multiplex - documentation at</para> - - <blockquote> - <para><ulink - url="http://labs.jboss.com/portal/jbossremoting/docs/index.html"... - http://labs.jboss.com/portal/jbossremoting/docs/index.html</ulink>&... - </blockquote> - - <para>for more information.</para> - </listitem> - </orderedlist> - </section> + <para>As of Remoting version 2.4, the multiplex transport is deprecated + and will no longer be supported.</para> </section> <section> - <title>SSL Multiplex Invoker</title> + <title>SSL Multiplex transport</title> - <para>This transport is essentially identical to the Multiplex - transport, except that it will create SSL socket factories and server - socket factories by default.</para> - - <para>The twist to be found with the multiplex transport is that virtual - <classname>MultiplexServerInvoker</classname>s use a - <classname>VirtualServerSocket</classname>, which is based on a client - rather than a server socket, and consequently they act like a client in - some ways. In particular, a virtual - <classname>MultiplexServerInvoker</classname> will, in some cases, - attempt to connect to a remote master - <classname>MultiplexServerInvoker</classname>, for which it will need an - actual client socket. All of the rules for configuring socket factories - apply to the <classname>MultiplexServerInvoker</classname>, which calls - the same method that client invokers use to get a socket factory. - Moreover, if necessary, it will look for a - <classname>ServerSocketFactoryMBean</classname> to get SSL information - when configuring a socket factory. See section <xref - linkend="section-socket-factories" /> for more information.</para> + <para>As of Remoting version 2.4, the sslmultiplex transport is deprecated + and will no longer be supported.</para> </section> <section> - <title>Bisocket invoker</title> + <title>Bisocket transport</title> <para> The <emphasis role="bold">bisocket transport</emphasis>, like the @@ -2647,6 +2348,32 @@ <classname>BisocketServerInvoker</classname> uses it to govern the number of attempts it should make to create both ordinary and control sockets. The default value is 10. </para> + + <para> + <emphasis role="bold">SECONDARY_BIND_PORT</emphasis> (actual value is + "secondaryBindPort"): The server side uses this parameter to determine + the bind port for the secondary + <classname>ServerSocket</classname>.</para> + + <para> + <emphasis role="bold">SECONDARY_BIND_PORTS</emphasis> (actual value is + "secondaryBindPorts"): The server side uses this parameter to + determine the bind ports for the secondary + <classname>ServerSocket</classname>s in a multihome server.</para> + + <para> + <emphasis role="bold">SECONDARY_CONNECT_PORT</emphasis> (actual value + is "secondaryConnectPort"): The server side uses this parameter to + determine the connect port used by the client side to connect to the + secondary <classname>ServerSocket</classname>.</para> + + <para> + <emphasis role="bold">SECONDARY_CONNECT_PORTS</emphasis> (actual value + is "secondaryConnectPorts"): The server side uses this parameter to + determine the connect ports used by the client side to connect to the + secondary <classname>ServerSocket</classname>s in a multihome + server.</para> + </section> <section> @@ -2866,7 +2593,7 @@ </section> <section> - <title>SSL Bisocket invoker</title> + <title>SSL Bisocket transport</title> <para> The SSL bisocket transport has the same relation to the bisocket @@ -3034,21 +2761,23 @@ <title>Callback overview</title> <para> - Although this section covers callback configuration, it will be useful to begin - with a little general information about callbacks within Remoting. In addition - to the ordinary remote method invocation model, in which invocation results are - returned synchronously, Remoting also supports an invocation model in which the - server asynchronously generates information to be returned to the client. + Although this section covers callback configuration, it will be useful + to begin with a little general information about callbacks within + Remoting. In addition to the ordinary remote method invocation model, in + which invocation results are returned synchronously, Remoting also + supports an invocation model in which the server asynchronously + generates information to be returned to the client. </para> <para> There are two models for callbacks, <emphasis role="bold">push - callbacks</emphasis> and <emphasis role="bold">pull callbacks</emphasis>. - In the push model, the client registers a client side callback server with - the target server. When the target server has a callback to deliver, it - will call on the callback server directly and send the callback message. - The other model, pull callbacks, allows the client to call on the target - server to collect the callback messages waiting for it. + callbacks</emphasis> and <emphasis role="bold">pull + callbacks</emphasis>. In the push model, the client registers a client + side callback server with the target server. When the target server has + a callback to deliver, it will call on the callback server directly and + send the callback message. The other model, pull callbacks, allows the + client to call on the target server to collect the callback messages + waiting for it. </para> <section> @@ -3069,18 +2798,18 @@ <para> method of the application's - <classname>org.jboss.remoting.ServerInvocationHandler</classname>. The - <classname>org.jboss.remoting.callback.InvokerCallbackHandler</classname> - parameter (actual type - <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>) - is the server side representation of the callback connection, - essentially a proxy for the client side - <classname>InvokerCallbackHandler</classname> passed to the - <methodname>addListener()</methodname> method. The - <classname>ServerInvocationHandler</classname> is free to do whatever - it wants with the <classname>InvokerCallbackHandler</classname>, but a - typical practice would be to keep a list of them and transmit each - generated callback to some or all of them. + <classname>org.jboss.remoting.ServerInvocationHandler</classname>. The + <classname>org.jboss.remoting.callback.InvokerCallbackHandler</classname> + parameter (actual type + <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>) + is the server side representation of the callback connection, + essentially a proxy for the client side + <classname>InvokerCallbackHandler</classname> passed to the + <methodname>addListener()</methodname> method. The + <classname>ServerInvocationHandler</classname> is free to do whatever + it wants with the <classname>InvokerCallbackHandler</classname>, but a + typical practice would be to keep a list of them and transmit each + generated callback to some or all of them. </para> <para> @@ -3422,10 +3151,10 @@ <title>Registering callback handlers.</title> <para>There are several ways in which callback handlers can be configured. - The main distinction in type of callback setup is whether the callbacks will - be push (asynchronous) or pull (synchronous) callbacks.</para> + The main distinction in type of callback setup is whether the callbacks + will be push (asynchronous) or pull (synchronous) callbacks.</para> - <section> + <section id="subsection-pull-callbacks" xreflabel="Pull callbacks"> <title>Pull callbacks.</title> <para> @@ -3468,6 +3197,43 @@ <classname>InvokerCallbackHandler</classname>, the two objects together identify a particular callback connection. </para> + + <para><emphasis role="bold">Note. </emphasis>As of Remoting version 2.4 + there are two versions of pull callbacks: non-blocking (original) and + blocking (new). [The new version has been ported to Remoting release + 2.2.2.GA, so it exists in later versions of the 2.2 family]. In the + original, non-blocking mode, a call to + <classname>Client.getCallbacks()</classname> will return more or less + immediately, whether or not any callbacks are waiting on the server + side. In the new, blocking mode, the call will block on the server side + until either it times out or a callback becomes available. The blocking + mode eliminates the overhead of busy polling. Blocking and non-blocking + mode are configured on a per-invocation basis by setting + <code>org.jboss.remoting.ServerInvoker.BLOCKING_MODE</code> (actual + value "blockingMode") to either + <classname>ServerInvoker.BLOCKING</classname> (actual value "blocking") + or <classname>ServerInvoker.NONBLOCKING</classname> (actual value + "nonblocking") in the metadata map passed to</para> + + <programlisting> + public List getCallbacks(InvokerCallbackHandler callbackHandler, Map metadata) throws Throwable; + </programlisting> + + <para>in <classname>org.jboss.remoting.Client</classname>. The default + value is <code>ServerInvoker.NONBLOCKING</code>. The blocking timeout value + may be configured in two ways:</para> + + <orderedlist> + <listitem><para>the <classname>Connector</classname> can be + configured with a default value; and</para> + </listitem> + <listitem><para>a per-invocation timeout value can be configured with + the key <code>ServerInvoker.BLOCKING_TIMEOUT</code> in the metadata + map passed to <methodname>Client.getCallbacks()</methodname>.</para> + </listitem> + </orderedlist> + + <para>In the absence of any configured timeout, the default value is 5000 ms.</para> </section> @@ -3589,9 +3355,9 @@ <classname>Socket</classname> to a <classname>ServerSocket</classname>. There are currently three bidirectional transports: local (i.e., the client and server reside in - the same JVM), bisocket, and multiplex. When one of the second set of - <methodname>addListener()</methodname> methods is invoked for a - bidirectional transport, it will create a callback + the same JVM), bisocket, and multiplex (deprecated). When one of the + second set of <methodname>addListener()</methodname> methods is + invoked for a bidirectional transport, it will create a callback <classname>Connector</classname>, even if <code>serverToClient</code> is set to false. The other option is to use any of the <emphasis role="bold">unidirectional</emphasis> transports (socket, http, rmi) @@ -3664,17 +3430,30 @@ with only one callback connection. </para> + <para><emphasis role="bold">Note. </emphasis>As of Remoting version 2.4, + there are two versions of pull callbacks: non-blocking (original) and + blocking (new). For more information, see <xref + linkend="subsection-pull-callbacks"/>. Since the + <classname>CallbackPoller</classname> uses pull callbacks, this + distinction is relevant to polled callbacks as well. The default + behavior of <classname>CallbackPoller</classname> is to use non-blocking + mode, but blocking mode can be requested by using the key + <code>ServerInvoker.BLOCKING_MODE</code> set to + <code>ServerInvoker.BLOCKING</code> in the metadata map passed to + <methodname>Client.addListener()</methodname>.</para> + <para> - There are six parameters that can be passed to - <methodname>addListener()</methodname> in the <code>metadata</code> - map which are specific to push callback configuration. The first three - apply to push callbacks and the latter three apply to polled - callbacks. For convenience, the keys related to push callbacks are - defined as constants in the + There are nine parameters that can be passed to + <methodname>Client.addListener()</methodname> in the + <code>metadata</code> map which are specific to push callback + configuration. The first three apply to push callbacks and the latter + six apply to polled callbacks. For convenience, the keys related to + push callbacks are defined as constants in the <classname>org.jboss.remoting.Client</classname> class, and the keys related to polled callbacks are defined in the <classname>org.jboss.remoting.callback.CallbackPoller</classname> - class. + class (with the exception of + <code>ServerInvoker.BLOCKING_MODE</code> and <code>ServerInvoker.BLOCKING_TIMEOUT</code>). </para> <para> @@ -3727,12 +3506,58 @@ <classname>CallbackPoller</classname> to print statistics that might be useful for configuring the other parameters.. </para> + + <para> + <emphasis role="bold">MAX_ERROR_COUNT</emphasis> (actual value is + "maxErrorCount"): determines the maximum number of errors that may + be experienced during polling before + <classname>CallbackPoller</classname> will shut itself down. The + default value is "5". + </para> + <para> + <emphasis role="bold">SYNCHRONIZED_SHUTDOWN</emphasis> (actual value + is "doSynchronizedShutdown"): if set to "true", + <methodname>CallbackPoller.stop()</methodname> will wait for + <methodname>Client.getCallbacks()</methodname> to return, and if set + to "false" it will not wait. For blocking polled callbacks, the + default value is "false" and for non-blocking polled callbacks, the + default value is "true". + </para> + + <para> + <emphasis role="bold">BLOCKING_MODE</emphasis> (actual value is + "blockingMode"): if set to <code>ServerInvoker.BLOCKING</code> + (actual value "blocking"), <classname>CallbackPoller</classname> + will do blocking polled callbacks, and if set to + <code>ServerInvoker.NONBLOCKING</code> (actual value "nonblocking"), + <classname>CallbackPoller</classname> will do non-blocking polled + callbacks. + </para> + + <para> + <emphasis role="bold">BLOCKING_TIMEOUT</emphasis> (actual value is + "blockingTimeout"): the value is used as the per-invocation timeout + </para> + <para> Note that all of the elements in <code>metadata</code> will be passed to the callback <classname>Connector</classname> and appended to its <classname>InvokerLocator</classname>. </para> + + <para><emphasis role="bold">Note. </emphasis> As of Remoting version 2.4, + it is possible to configure a server side timeout value for sending push + callbacks that is distinct from the timeout value used by the server. + [This feature has been ported to Remoting release 2.2.2.GA, so it exists + in later versions of the 2.2 family]. The parameter is + <code>org.jboss.remoting.callback.ServerInvokerCallbackHandler.CALLBACK_TIMEOUT</code> + (actual value "callbackTimeout"), and it should be used to configure the + <classname>Connector</classname>. In the absence of + <code>ServerInvokerCallbackHandler.CALLBACK_TIMEOUT</code>, the timeout + value configured for the <classname>Connector</classname> will be + used.</para> + </section> </section> @@ -3940,6 +3765,23 @@ callback listener proxy on the server side. The number of exceptions the DefaultCallbackErrorHandler will allow before removing the listener can by configured by the 'callbackErrorsAllowed' attribute.</para> + + <para><emphasis role="bold">Note. </emphasis>As of Remoting version 2.4, + an + <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>, + which manages both push and pull callbacks on the server side, can + register to be informed of a failure on the connection to the client that + it is servicing. In particular, if there is a lease registered for the + connection for that particular client, then the + <classname>ServerInvokerCallbackHandler</classname> can be registered as a + <classname>org.jboss.remoting.ConnectionListener</classname> for that + lease. The default behavior is to do the registration, but the parameter + <code>org.jboss.remoting.ServerInvoker.REGISTER_CALLBACK_LISTENER</code> + (actual value "registerCallbackListener") may be set to "false" to prevent + registration. If leasing is enabled and registration is turned on, a + <classname>ServerInvokerCallbackHandler</classname> will shut itself down upon being informed of a connection + failure. For more information about leasing, see <xref + linkend="chapter-connection-failure"/>.</para> </section> </section> @@ -4078,7 +3920,7 @@ <listitem> <para>Configure an appropriate set of SSL system properties and - use one of the SSL transports (https, sslmultiplex, sslrmi, or + use one of the SSL transports (https, sslrmi, or sslsocket). The properties will be used to create some kind of <classname>SSLServerSocketFactory</classname>, as determined by the transport.</para> @@ -4225,7 +4067,7 @@ <listitem> <para>Configure an appropriate set of SSL system properties and - use one of the SSL transports (https, sslmultiplex, sslrmi, or + use one of the SSL transports (https, sslrmi, or sslsocket). The properties will be used to create some kind of <classname>SSLSocketFactory</classname>, as determined by the transport.</para> @@ -4349,7 +4191,7 @@ <listitem> <para>Configure an appropriate set of SSL system properties and - use one of the SSL transports (https, sslmultiplex, sslrmi, or + use one of the SSL transports (https, sslrmi, or sslsocket). The properties will be used to create some kind of <classname>SSLServerSocketFactory</classname>, as determined by the transport.</para> @@ -4426,7 +4268,7 @@ <listitem> <para>Configure an appropriate set of SSL system properties and - use one of the SSL transports (https, sslmultiplex, sslrmi, or + use one of the SSL transports (https, sslrmi, or sslsocket). The properties will be used to create some kind of <classname>SSLSocketFactory</classname>, as determined by the transport.</para> @@ -4465,21 +4307,6 @@ </listitem> <listitem> - <para><emphasis role="bold">sslmultiplex: </emphasis> Whichever of - <classname>SSLMultiplexClientInvoker</classname> or - <classname>SSLMultiplexServerInvoker</classname> first gets - sufficient bind and connect information to create a priming socket - (see the section on the multiplex invoker for a discussion of - priming sockets) passes the current - <classname>SocketFactory</classname> to be used to create the - actual socket that supports the multiplexed connection. This - happens during the call to either - <methodname>Client.connect()</methodname> or - <methodname>Connector.create()</methodname>. Once the actual - socket is created, no further configuration is possible</para> - </listitem> - - <listitem> <para><emphasis role="bold">sslrmi: </emphasis> A <classname>SocketFactory</classname> is either created or configured for future creation during @@ -4702,7 +4529,7 @@ <para> The creation listener facility currently is supported by the following - transports: bisocket, sslbisocket, https, multiplex, sslmultiplex, rmi, + transports: bisocket, sslbisocket, https, rmi, sslrmi, socket, and sslsocket. It is not supported by http because <classname>HttpURLConnection</classname> does not expose its socket factory (though <classname>HttpsURLConnection</classname> does). It is @@ -4716,7 +4543,7 @@ <title>SSL transports</title> <para>There are now four transports that support SSL: https, - sslmultiplex, sslrmi, and sslsocket (plus sslservlet, which is not + sslrmi, and sslsocket (plus sslservlet, which is not relevant here). All of the preceding discussion applies to each of these, and, moreover, they are all extensions of their non-ssl counterparts, so only some ssl specific information will be added @@ -4783,20 +4610,6 @@ section <xref linkend="section-http-invoker" /> for more information on using the APR based transport.</para> - <bridgehead>sslmultiplex</bridgehead> - - <para>The sslmultiplex server invoker inherits from the socket server - invoker a method with signature</para> - - <programlisting> - public void setNewServerSocketFactory(ServerSocketFactory serverSocketFactory) - </programlisting> - - <para>which supports dynamic replacement of server socket factories. The - principal motivation for this facility is to be able to swap in a new - <classname>SSLServerSocketFactory</classname> configured with an updated - keystore.</para> - <bridgehead id="subsection-sslrmi" xreflabel="sslrmi">sslrmi</bridgehead> @@ -5437,7 +5250,7 @@ </section> </section> - <section id="secction-timeouts" xreflabel="Timeouts"> + <section id="section-timeouts" xreflabel="Timeouts"> <title>Timeouts</title> <para> @@ -5476,7 +5289,7 @@ <title>Per invocation timeouts</title> <para> - Beginning with release 2.2.0, some Remoting transports offer a per + As of version 2.4, all Remoting transports offer a per invocation transport facility, which allows a timeout value to be set for a particular invocation, overriding the client invoker's previously configured timeout value. The per invocation timeout is set by passing @@ -5533,7 +5346,7 @@ </section> <section> - <title>HTTP transport</title> + <title>HTTP and HTTPS transports</title> <para> The http server invoker looks for a configured timeout value at @@ -5568,7 +5381,7 @@ separate thread, which it waits on for the specified timeout. The threads are drawn from a thread pool, which is configurable. A custom thread pool may be set by calling the - <methodname>HTTPClientInvoker</methodname> method + <classname>HTTPClientInvoker</classname> method </para> <programlisting> @@ -5603,6 +5416,42 @@ </section> <section> + <title>RMI and SSLRMI transports</title> + + <para>Connection timeouts are handled on the server side by passing the + configured timeout value to the + <classname>org.jboss.remoting.transport.rmi.RemotingRMIClientSocketFactory</classname> + and + <classname>org.jboss.remoting.transport.rmi.RemotingRMIServerSocketFactory</classname> + objects passed when the + <classname>org.jboss.remoting.transport.RMIServerInvoker</classname> is + exported by the + <methodname>java.rmi.server.UnicastRemoteObject.exportObject(</methodname>) + method.</para> + + <para><classname>org.jboss.remoting.transport.rmi.RMIClientInvoker</classname> + handles per invocation timeouts by executing the invocation in a + separate thread, which it waits on for the specified timeout. The + threads are drawn from a + <classname>org.jboss.util.threadpool.BasicThreadPool</classname>, which + may be configured with the following parameters, defined as constants in + <classname>org.jboss.remoting.transport.rmi.RMIClientInvoker</classname>: + </para> + + <para> + <emphasis role="bold">MAX_NUM_TIMEOUT_THREADS</emphasis> (actual value + "maxNumTimeoutThreads"): the number of threads in the threadpool. The + default value is 10.</para> + + <para> + <emphasis role="bold">MAX_TIMEOUT_QUEUE_SIZE</emphasis> (actual value + "maxTimeoutQueueSize"): the size of the thread pool queue, which holds + execution requests when all of the threads are in use. The default + value is 1024.</para> + + </section> + + <section> <title>Quick client disconnect</title> <para> @@ -5638,6 +5487,231 @@ </section> + + <section id="section-security" xreflabel="Timeouts"> + <title>Running with a security manager</title> + + <para>As of version 2.4, Remoting is prepared to run in the presence of an + installed <classname>java.lang.SecurityManager</classname>. In Java, + certain security sensitive system calls, e.g., + <methodname>java.io.File.exists()</methodname>, + <methodname>java.lang.Class.getClassLoader()</methodname>, and + <methodname>java.lang.System.getProperty()</methodname>, consult a + <classname>SecurityManager</classname>, if one has been installed, to + determine if the calling code has permission to execute the action + performed by the method.</para> + + <para>In fact, the standard behavior is for the Java Virtual Machine to + examine, not only the calling code, but all methods on the stack, for the + appropriate permissions. This strategy prevents untrusted code from using + trusted code for its own nefarious purposes. However, the same strategy + could prevent trusted code from accomplishing security sensitive activities + without granting suitable permissions to any code that calls the trusted + code. The loophole that gets around this problem is the ability to wrap + security sensitive method calls in a "privileged block" which prevents the + JVM from proceeding up the stack. In other words, the code in the privileged + block can employ its granted permissions even if the calling code does not + have those same permissions.</para> + + <para>More precisely, a privileged block consists of an + <classname>java.security.PrivilegedAction</classname> or + <classname>java.security.PrivilegedExceptionAction</classname> object + passed to a + <methodname>java.security.AccessController.doPrivileged()</methodname> + call. As of version 2.4, Remoting wraps all security sensitive method calls + appropriately. For example, the call + <code>java.net.ServerSocket.accept()</code> has been replaced by + org.jboss.remoting.utility.SecurityUtility.accept():</para> + + <programlisting> + static public Socket accept(final ServerSocket ss) throws IOException + { + if (skipAccessControl) + { + return ss.accept(); + } + + try + { + return (Socket)AccessController.doPrivileged( new PrivilegedExceptionAction() + { + public Object run() throws Exception + { + return ss.accept(); + } + }); + } + catch (PrivilegedActionException e) + { + throw (IOException) e.getCause(); + } + } + </programlisting> + + <para>Note that the + <methodname>AccessController.doPrivileged()</methodname> call, with its + creation of a <classname>PrivilegedExceptionAction</classname> object, is + made only if the static variable + <code>SecurityUtility.skipAccessControl</code> is set to false, which is + the case if</para> + + <itemizedlist> + <listitem> + <para>no <classname>SecurityManager</classname> is installed, or</para> + </listitem> + <listitem> + <para>the system property <code>org.jboss.remoting.Remoting.SKIP_ACCESS_CONTROL</code> + is set to "false".</para> + </listitem> + </itemizedlist> + + <para>The Remoting code needs quite a few permissions since it interacts + extensively with the network, file system, etc., and there are a couple of + strategies for granting these permissions. The standard + <classname>java.lang.SecurityManager</classname> can read permission + information from an XML file, as described in <ulink + url="http://java.sun.com/j2se/1.5.0/docs/guide/security/PolicyFiles.... + http://java.sun.com/j2se/1.5.0/docs/guide/security/PolicyFiles.html</u...;, + and one straightforward strategy is to treat Remoting as highly trusted + code and to give it all possible permissions in a file that looks + like</para> + + <programlisting> + grant codeBase "file:${remoting.dir}/jboss-remoting.jar" + { + permission java.security.AllPermission; + }; + </programlisting> + + <para>This file grants all permissions to any class loaded from + jboss-remoting.jar. Alternatively, a more precisely tailored set of + permissions can be crafted to give Remoting, or some subset of its + facilities, sufficient permissions to function. The Remoting distribution + contains a sample permission set in etc/remoting.security.policy.core. It + may be necessary or desirable to modify the file, according to which + Remoting components are used, where certain files are located, etc:</para> + + <orderedlist> + <listitem> + <para>It may be necessary to change the java.io.FilePermission + permissions, according to the configuration of certain files.</para> </listitem> + <listitem> + <para>If Remoting is configured to operate with one or more MBeans in + place of POJOs, it might be necessary to grant additional + MBeanPermissions.</para> + </listitem> + <listitem> + <para>Some facilities always use MBeans. The MBean permissions given + in remoting.security.policy.core may be restricted to particular + ObjectNames.</para> + </listitem> + <listitem> + <para>Some permission may be eliminated, according to which Remoting + facilities are used.</para> + </listitem> + </orderedlist> + + <para>Other than changes made according to items 1 and 2, it should not be + necessary to grant any additional permissions.</para> + + <para>The etc directory also contains the policy files + remoting.security.policy.tests, remoting.security.policy.tests.marshal, and + remoting.security.policy.tests.minimal, which are used by the Remoting + functional test suite. These files give examples of modifying the + permissions given in remoting.security.policy.core.</para> + + </section> + + <section id="section-wire-version" xreflabel="Wire version"> + <title>Wire version</title> + + <para>Remoting has, on occasion, changed the format of communications over + the network, which could make it difficult for one version of Remoting to + communcate with another version. However, it is possible to configure newer + versions to communicate with older versions.</para> + + <para>There are currently three wire versions:</para> + + <itemizedlist> + <listitem> + <code>org.jboss.remoting.Version.VERSION_1</code> (actual value 1), + used by Remoting versions 1.2 and 1.4; + </listitem> + + <listitem> + <code>org.jboss.remoting.Version.VERSION_2</code> (actual value 2), + used by Remoting version 2.0; and + </listitem> + + <listitem> + <code>org.jboss.remoting.Version.VERSION_22</code> (actual value 22), + used by Remoting versions 2.2 and 2.4. + </listitem> + </itemizedlist> + + <para>Versinos 2.0, 2.2, and 2.4 can be configured to communicate with + versions 1.2 and 1.4 in one of three ways:</para> + + <orderedlist> + <listitem> + <para>set system property + <code>org.jboss.remoting.Version.PRE_2_0_COMPATIBLE</code> (actual + value "jboss.remoting.pre_2_0_compatible") to "true";</para> + </listitem> + + <listitem> + <para>set system property + <code>org.jboss.remoting.Version.REMOTING_VERSION_TO_USE</code> + (actual value "jboss.remoting.version") to + <code>org.jboss.remoting.Version.VERSION_1</code> (actual version + "1");</para> + </listitem> + + <listitem> + <para>configure the <classname>org.jboss.remoting.Client</classname> + or <classname>org.jboss.remoting.transport.Connector</classname> with + the parameter + <code>org.jboss.remoting.Remoting.REMOTING_VERSION</code> (actual + value "remotingVersion") set to + <code>org.jboss.remoting.Version.VERSION_1</code> (actual version + "1").</para> + </listitem> + </orderedlist> + + <para>Similarly, versions 2.2 and 2.4 can be configured to communicate with + version 2.0:</para> + + <orderedlist> + <listitem> + <para>set system property + <code>org.jboss.remoting.Version.REMOTING_VERSION_TO_USE</code> + (actual value "jboss.remoting.version") to + <code>org.jboss.remoting.Version.VERSION_2</code> (actual version + "2");</para> + </listitem> + + <listitem> + <para>configure the <classname>org.jboss.remoting.Client</classname> + or <classname>org.jboss.remoting.transport.Connector</classname> with + the parameter + <code>org.jboss.remoting.Remoting.REMOTING_VERSION</code> (actual + value "remotingVersion") set to + <code>org.jboss.remoting.Version.VERSION_2</code> (actual version + "2").</para> + </listitem> + </orderedlist> + + <para>Versions 2.2. and 2.4 use the same wire format, so there's no need to + configure version 2.4 to communicate with version 2.2.</para> + + <para><emphasis role="bold">Note. </emphasis> Setting these versions is not + necessary in all circumstances. For example, it is not necessary when using + JBossSerialization. But, upon encountering a problem when using mismatched + clients and servers, be sure that the versions are set properly.</para> + + </section> + + <section id="section-configuration-by-properties" xreflabel="Configuration by properties"> <title>Configuration by properties</title> @@ -5646,7 +5720,8 @@ configuration properties already covered and is just another view to some of the same information.</para> - <bridgehead>org.jboss.remoting.InvokerLocator</bridgehead> + <section> + <title>org.jboss.remoting.InvokerLocator</title> <para><emphasis role="bold">SERVER_BIND_ADDRESS</emphasis> (actual value is 'jboss.bind.address') - indicates the system property key for bind @@ -5771,9 +5846,10 @@ property is not set (and CLIENT_LEASE is), will use the lease period as specified by the server.</para> - <para></para> + </section> - <bridgehead>org.jboss.remoting.Client</bridgehead> + <section> + <title>org.jboss.remoting.Client</title> <para><emphasis role="bold">RAW</emphasis> (actual value is 'rawPayload') - key to use for the metadata Map passed when making an invoke() call and @@ -5809,7 +5885,7 @@ a callback handler and internal callback server connector is created. The value should be the transport protocol to be used. By default will use the same protocol as being used by this client (e.g. http, socket, rmi, - multiplex, etc.).</para> + etc.).</para> <para><emphasis role="bold">CALLBACK_SERVER_HOST</emphasis> (actual value is 'callbackServerHost') - key for the configuration when adding a @@ -5865,9 +5941,10 @@ overrides the client's default unmarshaller (or any set within configuration).</para> - <para></para> + </section> - <bridgehead>org.jboss.remoting.Remoting</bridgehead> + <section> + <title>org.jboss.remoting.Remoting</title> <para><emphasis role="bold">CUSTOM_SERVER_SOCKET_FACTORY</emphasis> (actual value is 'customServerSocketFactory') - key for the configuration @@ -5887,10 +5964,34 @@ javax.net.SocketFactory and has a void constructor. This property will not be used if CUSTOM_SOCKET_FACTORY is also set.</para> - <para></para> + <para><emphasis role="bold">SOCKET_CREATION_CLIENT_LISTENER</emphasis> + (actual value is "socketCreationClientListener") - key for the configuration + map passed to a Client or Connector to indicate a socket creation listener + for sockets created by a SocketFactory.</para> + + <para><emphasis role="bold">SOCKET_CREATION_SERVER_LISTENER</emphasis> + (actual value is "socketCreationServerListener") - key for the configuration + map passed to a Client or Connector to indicate a socket creation listener + for sockets created by a ServerSocket.</para> + + <para><emphasis role="bold">CLIENT_ADDRESS</emphasis> (actual value is + "clientAddress") - key with which host address of client will be associated + in <classname>InvocationRequest</classname> request payload.</para> - <bridgehead>org.jboss.remoting.ServerInvoker</bridgehead> + <para><emphasis role="bold">REMOTING_VERSION</emphasis> (actual value is + "remotingVersion") - key for configuring Remoting wire version.</para> + + <para><emphasis role="bold">SKIP_ACCESS_CONTROL</emphasis> (actual value is + "skipAccessControl") - key for telling Remoting to execute security + sensitive code outside of + <methodname>java.security.AccessController.doPrivileged()</methodname> + calls..</para> + </section> + + <section> + <title>org.jboss.remoting.ServerInvoker</title> + <para><emphasis role="bold">MAX_NUM_ONEWAY_THREADS_KEY</emphasis> (actual value is 'maxNumThreadsOneway') - key for the maximum number of threads to be used in the thread pool for one way invocations (server side). This @@ -5957,6 +6058,33 @@ instance of it (which requires it to have a void constructor). The instance will then be cast to type javax.net.ServerSocketFactory.</para> + <para> + <emphasis role="bold">BLOCKING_MODE</emphasis> (actual value is + "blockingMode"): if set to <code>ServerInvoker.BLOCKING</code> (actual + value "blocking"), + <methodname>org.jboss.remoting.Client.getCallbacks()</methodname> will do + blocking pull callbacks and <classname>CallbackPoller</classname> will do + blocking polled callbacks; if set to + <code>ServerInvoker.NONBLOCKING</code> (actual value "nonblocking"), + <methodname>Client.getCallbacks()</methodname> will do non-blocking pull + callbacks and <classname>CallbackPoller</classname> will do non-blocking + polled callbacks. + </para> + + <para> + <emphasis role="bold">BLOCKING_TIMEOUT</emphasis> (actual value is + "blockingTimeout"): the timeout value used for blocking callback. + </para> + + <para> + <emphasis role="bold">REGISTER_CALLBACK_LISTENER</emphasis> (actual value + is "registerCallbackListener"): determines if + <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>s + should register as + <classname>org.jboss.remoting.ConnectionListener</classname>s with leases. + The default value is "true". + </para> + <para></para> <para><emphasis role="bold">Bean properties (meaning have @@ -5988,9 +6116,10 @@ <para><emphasis role="bold">OnewayThreadPool</emphasis> - the oneway thread pool to use.</para> - <para></para> + </section> - <bridgehead>org.jboss.remoting.callback.CallbackPoller</bridgehead> + <section> + <title>org.jboss.remoting.callback.CallbackPoller</title> <para><emphasis role="bold">CALLBACK_POLL_PERIOD</emphasis> (actual value is 'callbackPollPeriod') - key for setting the frequency (in milliseconds) @@ -5998,12 +6127,45 @@ callbacks. The default value is five seconds.</para> <para> - <emphasis role="bold">CALLBACK_SCHEDULE_MODE</emphasis> (actual value is "scheduleMode"): may be set to either <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> (actual value "scheduleFixedRate") or <code>CallbackPoller.SCHEDULE_FIXED_DELAY</code> (actual value "scheduleFixedDelay"). In either case, polling will take place at approximately regular intervals, but in the former case the scheduler will attempt to perform each poll CALLBACK_POLL_PERIOD milliseconds after the previous attempt, and in the latter case the scheduler will attempt to schedule polling so that the <emphasis>average</emphasis> interval will be approximately CALLBACK_POLL_PERIOD milliseconds. <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> is the default. + <emphasis role="bold">CALLBACK_SCHEDULE_MODE</emphasis> (actual value is + "scheduleMode"): may be set to either + <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> (actual value + "scheduleFixedRate") or <code>CallbackPoller.SCHEDULE_FIXED_DELAY</code> + (actual value "scheduleFixedDelay"). In either case, polling will take + place at approximately regular intervals, but in the former case the + scheduler will attempt to perform each poll CALLBACK_POLL_PERIOD + milliseconds after the previous attempt, and in the latter case the + scheduler will attempt to schedule polling so that the + <emphasis>average</emphasis> interval will be approximately + CALLBACK_POLL_PERIOD milliseconds. + <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> is the default. </para> <para> - <emphasis role="bold">REPORT_STATISTICS</emphasis> (actual value is "reportStatistics"): The presence of this key in <code>metadata</code>, regardless of its value, will cause the <classname>CallbackPoller</classname> to print statistics that might be useful for configuring the other parameters.. + <emphasis role="bold">REPORT_STATISTICS</emphasis> (actual value is + "reportStatistics"): The presence of this key in <code>metadata</code>, + regardless of its value, will cause the + <classname>CallbackPoller</classname> to print statistics that might be + useful for configuring the other parameters.. </para> + + <para> + <emphasis role="bold">SYNCHRONIZED_SHUTDOWN</emphasis> (actual value is + "doSynchronizedShutdown"): if set to "true", + <methodname>CallbackPoller.stop()</methodname> will wait for + <methodname>Client.getCallbacks()</methodname> to return, and if set to + "false" it will not wait. For blocking polled callbacks, the default value + is "false" and for non-blocking polled callbacks, the default value is + "true". + </para> + + <para> + <emphasis role="bold">MAX_ERROR_COUNT</emphasis> (actual value is + "maxErrorCount"): determines the maximum number of errors that may + be experienced during polling before + <classname>CallbackPoller</classname> will shut itself down. The + default value is "5". + </para> <para><classname>CallbackPoller</classname> configuration is only necessary when using one of the @@ -6017,9 +6179,10 @@ (e.g. socket, http, rmi). Bi-directional transports will not need to poll. </para> - <para></para> + </section> - <bridgehead>org.jboss.remoting.callback.CallbackStore</bridgehead> + <section> + <title>org.jboss.remoting.callback.CallbackStore</title> <para><emphasis role="bold">FILE_PATH_KEY</emphasis> (actual value is 'StoreFilePath') - key for setting the directory in which to write the @@ -6032,9 +6195,10 @@ 'StoreFileSuffix') - key for setting the file suffix to use for the callback objects written to disk. The default value is 'ser'.</para> - <para></para> + </section> - <bridgehead>org.jboss.remoting.callback.DefaultCallbackErrorHandler</bridgehead> + <section> + <title>org.jboss.remoting.callback.DefaultCallbackErrorHandler</title> <para><emphasis role="bold">CALLBACK_ERRORS_ALLOWED</emphasis> (actual value is 'callbackErrorsAllowed') - key for setting the number of callback @@ -6043,9 +6207,10 @@ callback) before cleaning up the callback listener. This only applies to push callback. The default if this property is not set is five.</para> - <para></para> + </section> - <bridgehead>org.jboss.remoting.callback.ServerInvokerCallbackHandler</bridgehead> + <section> + <title>org.jboss.remoting.callback.ServerInvokerCallbackHandler</title> <para><emphasis role="bold">CALLBACK_STORE_KEY</emphasis> (actual value is 'callbackStore') - key for specifing the callback store to be used. The @@ -6070,21 +6235,116 @@ allocated has reached its maximum value and the percent of free memory available is less than the callbackMemCeiling, this will trigger persisting of the callback message. The default value is 20.</para> + + <para><emphasis role="bold">CALLBACK_TIMEOUT</emphasis> (actual value is + 'callbackTimeout') - key for specifying the timeout to be used for doing + push callbacks. In the absence of + <code>ServerInvokerCallbackHandler.CALLBACK_TIMEOUT</code>, the timeout + value configured for the <classname>Connector</classname> will be + used.</para> - <para></para> + </section> + + <section> + <title>org.jboss.remoting.detection.jndi.JNDIDetector</title> - <bridgehead>org.jboss.remoting.detection.jndi.JNDIDetector</bridgehead> - <para><emphasis role="bold">Bean properties (meaning have getter/setter):</emphasis></para> <para><emphasis role="bold">SubContextName</emphasis> - sub context name under which detection messages will be bound and looked up.</para> - <para></para> + </section> + + <section> + <title>org.jboss.remoting.marshal.http.HTTPUnMarshaller</title> + + <para><emphasis role="bold">PRESERVE_LINES</emphasis> (actual value is + "preserveLines"): the key used to turn on or off + <classname>HTTPUnMarshaller</classname>'s behavior of stripping CR/LF + characters.</para> + + </section> + + <section> + <title>org.jboss.remoting.transport.bisocket.Bisocket</title> + <para> + <emphasis role="bold">IS_CALLBACK_SERVER</emphasis> (actual value is + "isCallbackServer"): when a bisocket server invoker receives this + parameter with a value of true, it avoids the creation of a + <classname>ServerSocket</classname>. Therefore, IS_CALLBACK_SERVER + should be used on the client side for the creation of a callback + server. The default value is false. + </para> + + <para> + <emphasis role="bold">PING_FREQUENCY</emphasis> (actual + value is "pingFrequency"): The server side uses this value + to determine the interval, in milliseconds, between pings that it will + send on the control connection. The client side uses this value to + calculate the window in which it must receive pings on the control + connection. In particular, the window is ping frequency * ping window factor. + See also the definition of PING_WINDOW_FACTOR. The default value is 5000. + </para> + + <para> + <emphasis role="bold">PING_WINDOW_FACTOR</emphasis> (actual + value is "pingWindowFactor"): The client side uses this value to + calculate the window in which it must receive pings on the control + connection. In particular, the window is ping frequency * ping window factor. + See also the definition of PING_FREQUENCY. The default value is 2. + </para> + + <para> + <emphasis role="bold">MAX_RETRIES </emphasis> (actual value is + "maxRetries"): This parameter is relevant only on the client side, + where the <classname>BisocketClientInvoker</classname> uses it + to govern the number of attempts it should make to get the address and + port of the secondary <classname>ServerSocket</classname>, and the + <classname>BisocketServerInvoker</classname> uses it to govern the + number of attempts it should make to create both ordinary and control + sockets. The default value is 10. </para> + + <para> + <emphasis role="bold">SECONDARY_BIND_PORT</emphasis> (actual value is + "secondaryBindPort"): The server side uses this parameter to determine + the bind port for the secondary + <classname>ServerSocket</classname>.</para> + + <para> + <emphasis role="bold">SECONDARY_BIND_PORTS</emphasis> (actual value is + "secondaryBindPorts"): The server side uses this parameter to + determine the bind ports for the secondary + <classname>ServerSocket</classname>s in a multihome server.</para> + + <para> + <emphasis role="bold">SECONDARY_CONNECT_PORT</emphasis> (actual value + is "secondaryConnectPort"): The server side uses this parameter to + determine the connect port used by the client side to connect to the + secondary <classname>ServerSocket</classname>.</para> + + <para> + <emphasis role="bold">SECONDARY_CONNECT_PORTS</emphasis> (actual value + is "secondaryConnectPorts"): The server side uses this parameter to + determine the connect ports used by the client side to connect to the + secondary <classname>ServerSocket</classname>s in a multihome + server.</para> + + </section> - <bridgehead>org.jboss.remoting.transport.http.HTTPMetadataConstants</bridgehead> + <section> + <title>org.jboss.remoting.transport.http.HTTPClientInvoker</title> + <para> <emphasis role="bold">NUMBER_OF_CALL_ATTEMPTS</emphasis> (actual + value is "numberOfCallAttempts"): This parameter is relevant only on the + client side, where it determines the maximum number of attempts that + will be made to complete an invocation. The default value is 1.</para> + + </section> + + <section> + <title>org.jboss.remoting.transport.http.HTTPMetadataConstants</title> + <para>The following are keys to use to get corresponding values from the Map returned from call to org.jboss.remoting.InvocationRequest.getRequestPayload() within a @@ -6114,7 +6374,7 @@ { if(methodType.equals("GET")) ... -</programlisting> + </programlisting> <para><emphasis role="bold">PATH</emphasis> (actual value is 'Path') - key for getting the path from the url request from the calling client. This @@ -6128,7 +6388,7 @@ Map headers = invocation.getRequestPayload(); String path = (String) headers.get(HTTPMetadataConstants.PATH); ... -</programlisting> + </programlisting> <para><emphasis role="bold">HTTPVERSION</emphasis> (actual value is 'HttpVersion') - key for getting the HTTP version from the calling client @@ -6147,7 +6407,7 @@ <programlisting>Map metadata = new HashMap(); Object response = remotingClient.invoke(myPayloadObject, metadata); Integer responseCode = (Integer) metadata.get(HTTPMetadataConstants.RESPONSE_CODE); -</programlisting> + </programlisting> <para>Will be used as key to put the response code in the return payload map from invocation handler. For example:</para> @@ -6156,7 +6416,7 @@ { Map responseHeaders = invocation.getReturnPayload(); responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE, new Integer(202)); -</programlisting> + </programlisting> <para><emphasis role="bold">RESPONSE_CODE_MESSAGE</emphasis> (actual value is 'ResponseCodeMessage') - key for getting and setting the HTTP response @@ -6176,8 +6436,21 @@ { Map responseHeaders = invocation.getReturnPayload(); responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, "Custom response code and message from remoting server"); -</programlisting> + </programlisting> + <para><emphasis role="bold">RESPONSE_HEADERS</emphasis> (actual value is + 'ResponseHeaders') - key for returning the value of + <methodname>java.net.URLConnection.getHeaderFields()</methodname>. In other + words, a map containing all of the response headers is stored in the + metadata map. For example,</para> + + <programlisting> + Object payload = ... ; + HashMap metadata = new HashMap(); + client.invoke(payload, metadata); + Map responseHeaders = (Map) metadata.get(HTTPMetadataConstants.RESPONSE_HEADERS); + </programlisting> + <para><emphasis role="bold">NO_THROW_ON_ERROR</emphasis> (actual value is 'NoThrowOnError') - key indicating if http client invoker (for transports http, https, servlet, and sslservlet) should throw an exception if the @@ -6187,7 +6460,11 @@ org.jboss.remoting.transport.http.WebServerError, whose message will be the error html returned from the web server.</para> - <para></para> + <para><emphasis role="bold">DONT_RETURN_EXCEPTION</emphasis> (actual value + is 'dont-return-exception') - key indicating if + <classname>org.jboss.remoting.transport.servlet.ServletServerInvoker</classname> + should revert to the orginal error handling behavior of returning an error + message.</para> <para>For every http client request made from remoting client, a remoting version and remoting specific user agent will be set as a request @@ -6197,10 +6474,11 @@ value will be set to the evaluation of '"JBossRemoting - " + Version.VERSION'.</para> - <para></para> + </section> + + <section> + <title>org.jboss.remoting.transport.http.ssl.HTTPSClientInvoker</title> - <bridgehead>org.jboss.remoting.transport.http.ssl.HTTPSClientInvoker</bridgehead> - <para><emphasis role="bold">IGNORE_HTTPS_HOST</emphasis> (actual value is 'org.jboss.security.ignoreHttpsHost') - key indicating if the http client invoker (for transports https and sslservlet) should ignore host name @@ -6214,19 +6492,25 @@ classname of class that implements javax.net.ssl.HostnameVerifier and has a void constructor.</para> - <para></para> + </section> - <bridgehead>org.jboss.remoting.transport.rmi.RMIServerInvoker</bridgehead> + <section> + <title>org.jboss.remoting.transport.rmi.RMIServerInvoker</title> <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> - <para></para> + <para><emphasis role="bold">RMI_ONEWAY_MARSHALLING</emphasis> (actual value + is 'rmiOnewayMarshalling') - if set to "true" will cause the RMI transport + to use the original client to server marshalling behavior.</para> - <bridgehead>org.jboss.remoting.transport.socket.MicroSocketClientInvoker</bridgehead> + </section> + <section> + <title>org.jboss.remoting.transport.socket.MicroSocketClientInvoker</title> + <para><emphasis role="bold">TCP_NODELAY_FLAG</emphasis> (actual value is 'enableTcpNoDelay') - can be either true or false and will indicate if client socket should have TCP_NODELAY turned on or off. TCP_NODELAY is for @@ -6248,10 +6532,26 @@ marshaller/unmarshaller that is used, which may also be a requirement.</para> - <para></para> + </section> + + <section> + <title>org.jboss.remoting.transport.socket.ServerThread</title> + + <para><emphasis role="bold">evictabilityTimeout</emphasis> - indicates the + number of milliseconds during which a server thread waiting for the next + invocation will not be preemptible.</para> + + <para><emphasis role="bold">continueAfterTimeout</emphasis> - indicates + what a server thread should do after experiencing a + <classname>java.net.SocketTimeoutException</classname>. If set to "true", + the server thread will continue to wait for an invocation; otherwise, it + will return itself to the thread pool.</para> + + </section> + + <section> + <title>org.jboss.remoting.transport.socket.SocketServerInvoker</title> - <bridgehead>org.jboss.remoting.transport.socket.SocketServerInvoker</bridgehead> - <para><emphasis role="bold">CHECK_CONNECTION_KEY</emphasis> (actual value is 'socket.check_connection') - key for indicating if socket invoker should continue to keep socket connection between client and server open @@ -6261,5 +6561,7 @@ <para><emphasis role="bold">SERVER_SOCKET_CLASS_FLAG</emphasis> (actual value is 'serverSocketClass') - specifies the fully qualified class name for the custom SocketWrapper implementation to use on the server.</para> + </section> + </section> </chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap6.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap6.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap6.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -1,121 +1,123 @@ -<chapter> - <title>Sending streams</title> +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="chapter-adding-new-transport" xreflabel="Adding a New Transport"> + <title>Adding a New Transport</title> + + <para>It is quite straightforward to extend Remoting with a new transport (other than the part about writing the new transport!). There are only three requirements. Suppose the new transport is to be called "nio", which would then be used by an <classname>InvokerLocator</classname> such as "nio://bluemonkey.com:5555/?timeout=10000".</para> + + <orderedlist> + <listitem> + <para>There needs to be a class <classname>org.jboss.remoting.transport.nio.TransportServerFactory</classname> which implements the interface <classname>org.jboss.remoting.transport.ServerFactory:</classname></para> + + <programlisting> + public interface ServerFactory + { + public ServerInvoker createServerInvoker(InvokerLocator locator, Map config) throws IOException; + + public boolean supportsSSL(); + } + </programlisting> + </listitem> + + <listitem> + <para>There needs to be a class <classname>org.jboss.remoting.transport.nio.TransportClientFactory</classname> which implements the interface <classname>org.jboss.remoting.transport.ClientFactory:</classname></para> + + <programlisting> + public interface ClientFactory + { + public ClientInvoker createClientInvoker(InvokerLocator locator, Map config) throws IOException; + + public boolean supportsSSL(); + } + </programlisting> + </listitem> + + <listitem> + <para>The factory classes must be loadable when the first "nio" <classname>InvokerLocator</classname> is encountered.</para> + </listitem> + + </orderedlist> + + <para>The factories can be quite simple. The + <methodname>createServerInvoker()</methodname> method must return an instance + of an appropriate subclass of + <classname>org.jboss.remoting.ServerInvoker</classname>, the + <methodname>createClientInvoker()</methodname> method must return an + appropriate implementation of the interface + <classname>org.jboss.remoting.transport.ClientInvoker</classname>, and the + <methodname>supportsSSL()</methodname> methods indicate if the transport + supports SSL.</para> + + <para>The factories for the "socket" transport, for example, are</para> + + <programlisting> + package org.jboss.remoting.transport.socket; + + import org.jboss.remoting.InvokerLocator; + import org.jboss.remoting.ServerInvoker; + import org.jboss.remoting.transport.ServerFactory; + import java.util.Map; - <para>Remoting supports the sending of InputStreams. It is important to - note that this feature DOES NOT copy the stream data directly from the - client to the server, but is a true on demand stream. Although this is - obviously slower than reading from a stream on the server that has been - copied locally, it does allow for true streaming on the server. It also - allows for better memory control by the user (versus the framework trying - to copy a 3 Gig file into memory and getting out of memory errors).</para> + public class TransportServerFactory implements ServerFactory + { + public ServerInvoker createServerInvoker(InvokerLocator locator, Map config) + { + return new SocketServerInvoker(locator, config); + } + + public boolean supportsSSL() + { + return false; + } + } + </programlisting> + + <para>and</para> + + <programlisting> + package org.jboss.remoting.transport.socket; + + import org.jboss.remoting.InvokerLocator; + import org.jboss.remoting.transport.ClientFactory; + import org.jboss.remoting.transport.ClientInvoker; + import java.io.IOException; + import java.util.Map; + + 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>Similarly, the server invoker factory for the "sslsocket" transport is</para> + + <programlisting> + package org.jboss.remoting.transport.sslsocket; + + import org.jboss.remoting.InvokerLocator; + import org.jboss.remoting.ServerInvoker; + import org.jboss.remoting.transport.ServerFactory; + import java.util.Map; - <para>Use of this new feature is simple. From the client side, there is a - method in org.jboss.remoting.Client with the signature:</para> - - <programlisting>public Object invoke(InputStream inputStream, Object param) throws Throwable - </programlisting> - - <para>So from the client side, would just call invoke as done in the past, - and pass the InputStream and the payload as the parameters. An example of - the code from the client side would be (this is taken directly from - org.jboss.test.remoting.stream.StreamingTestClient):</para> - - <programlisting> - String param = "foobar"; - File testFile = new File(fileURL.getFile()); - ... - Object ret = remotingClient.invoke(fileInput, param); - </programlisting> - - <para>From the server side, will need to implement - <code>org.jboss.remoting.stream.StreamInvocationHandler</code> instead of - <code>org.jboss.remoting.ServerInvocationHandler</code> . - StreamInvocationHandler extends ServerInvocationHandler, with the addition - of one new method:</para> - - <programlisting>public Object handleStream(InputStream stream, Object param)</programlisting> - - <para>The stream passed to this method can be called on just as any - regular local stream. Under the covers, the InputStream passed is really - proxy to the real input stream that exists in the client's VM. Subsequent - calls to the passed stream will actually be converted to calls on the real - stream on the client via this proxy. If the client makes an invocation on - the server passing an InputStream as the parameter and the server handler - 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 <methodname>invoke()</methodname> method on client and - 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 finishes reading, as will close the real - stream that lives within the client VM.</para> - - <section> - <title>Configuration</title> - - <para>By default, the stream server which runs within the client JVM - uses the following values for its locator uri:</para> - - <para>transport - socket</para> - - <para>host - tries to first get local host name and if that fails, the - local ip (if that fails, localhost).</para> - - <para>port - 5405</para> - - <para>Currently, the only way to override these settings is to set the - following system properties (either via JVM arguments or via - <code>System.setProperty()</code> method):</para> - - <para>remoting.stream.transport - sets the transport type (rmi, http, - socket, etc.)</para> - - <para>remoting.stream.host - host name or ip address to use</para> - - <para>remoting.stream.port - the port to listen on</para> - - <para>These properties are important because currently the only way for - a target server to get the stream data from the stream server (running - within the client JVM) is to have the server invoker make the invocation - on a new connection back to the client (see issues below).</para> - </section> - - <section> - <title>Issues</title> - - <para>This is a first pass at the implementation and needs some work in - regards to optimizations and configuration. In particular, there is a - remoting server that is started to service requests from the stream - proxy on the target server for data from the original stream. This - raises an issue with the current transports, since the client will have - to accept calls for the original stream on a different socket. This may - be difficult when control over the client's environment (including - firewalls) may not be available. A bi-directional transport, called - multiplex, is being introduced as of 1.4.0 release which will allow - calls from the server to go over the same socket connection established - by the client to the server (JBREM-91). This will make communications - back to client much simpler from this standpoint.</para> - </section> - </chapter> \ No newline at end of file + public class TransportServerFactory implements ServerFactory + { + public ServerInvoker createServerInvoker(InvokerLocator locator, Map config) + { + return new SSLSocketServerInvoker(locator, config); + } + + public boolean supportsSSL() + { + return true; + } + } + </programlisting> +</chapter> Modified: remoting2/branches/2.x/docs/guide/en/chap8.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap8.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap8.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -1,128 +1,44 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="chapter-connection-failure" xreflabel="Connection Exception - Listeners and Leasing"> - <title>Connection Exception Listeners and Leasing</title> + <chapter> + <title>Serialization</title> - <bridgehead>Client side</bridgehead> + <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> + and is a (as defined by its javadoc):</para> - <para>It is possible to register a listener with the remoting client to - receive callbacks when a connection failure to a remoting server is - detected, even when the client is idle.</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>The only requirement is to implement the - <code>org.jboss.remoting.ConnectionListener</code> interface, which has only - one method:</para> + <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 SerializationManager implementation and is backed by JBoss + Serialization.</para> - <programlisting>public void handleConnectionException(Throwable throwable, Client client)</programlisting> + <para>JBoss Serialization is a project intended to provide a + more performant implementation of object serialization. It complies with + java serialization standard with three exceptions:</para> - <para>Then call the <code>addConnectionListener(ConnectionListener - listener)</code> method on the Client class and pass your listener instance. - Can also call <code>addConnectionListener(ConnectionListener listener, int - pingPeriod)</code> if want to specify how frequently wish to ping - server.</para> + <para>- SerialUID not needed</para> - <para>Currently, the Client will use the - <code>org.jboss.remoting.ConnectionValidator</code> class to handle the - detection of connection failures. This is done by pinging the server - periodically (defaults to every 2 seconds). If there is a failure during - this ping, the exception and the Client will be passed to the - listener.</para> + <para>- java.io.Serializable is not required</para> - <bridgehead>Server side</bridgehead> + <para>- different protocol</para> - <para>A remoting server also has the capability to detect when a client is no - longer available. This is done by estabilishing a lease with the remoting - clients that connect to a server.</para> + <para>JBoss Serialization requires JDK 1.5</para> - <para>To turn on server side connection failure detection of remoting clients, - will need to satisfy two criteria. The first is that the client lease period - is set and is a value greater than 0. The value is represented in - milliseconds. The client lease period can be set by either the - 'clientLeasePeriod' attribute within the Connector configuration or by calling - the:<programlisting>public void setLeasePeriod(long - leasePeriodValue)</programlisting>method within Connector. The second - criterion is that an implementation of the - <code>org.jboss.remoting.ConnectionListener</code> interface is added as a - connection listener to the Connector, via the method:<programlisting>public - void addConnectionListener(ConnectionListener listener)</programlisting>Note, - there is no way to set the connection listener via xml based configuration for - the Connector. Once both criteria are met, the remoting server will turn on - client leasing.</para> + <para></para> - <para>The ConnectionListener will be notified of both client failures and - client disconnects via the handleConnectionException() method. If the client - failed, meaning its lease was not renewed within configured time period, the - first parameter to the handleConnectionException() method will be null. If the - client disconnected in a regular manner, the first parameter to the - handleConnectionException() method will be of type - ClientDisconnectedException (which indicates a normal termination). Note, - the client's lease will be renewed on the server with any and every - invocation made on the server from the client, whether it be a normal - invocation or a ping from the client internally.</para> - - <para>The actual lease window established on the server side is dynamic - based the rate at which the client updates its 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 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 to the - Client constructor. This map will be included in the Client instance passed to - the connection listener (via the handleConnectionException() method) via the - Client's getConfiguration() method.</para> - - <para>From the server side, there are two ways in which to disable leasing - (i.e. turn leasing off). The first is to call:</para> - - <programlisting>public void removeConnectionListener(ConnectionListener listener)</programlisting> - - <para>and remove all the registered ConnectionListeners. Once the last one - has been removed, leasing will be disabled and all the current leasing - sessions will be terminated. The other way is to call:</para> - - <programlisting>public void setLeasePeriod(long leasePeriodValue)</programlisting> - - <para>and pass a value less than zero. This will disable leasing, preventing - any new leases to be established but will allow current leasing sessions to - continue.</para> - - <para>For examples of how to use server side connection listeners, reference - org.jboss.test.remoting.lease.LeaseTestServer and - org.jboss.test.remoting.lease.LeaseTestClient.</para> -</chapter> \ No newline at end of file + <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 constructor).</para> + </chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap9.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap9.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/chap9.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -1,19 +1,278 @@ - <chapter> - <title>Transporters - beaming POJOs</title> +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="chapter-connection-failure" xreflabel="Network Connection Monitoring"> + <title>Network Connection Monitoring</title> + + <para>Remoting has two mechanisms for monitoring the health of estabilished + connections, which inform listeners on the client and server sides when a + possible connection failure has been detected.</para> + + <section> + <title>Client side monitoring</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>On the client side, an + <classname>org.jboss.remoting.ConnectionValidator</classname> periodically + sends a PING message to the server and reports a failure if the response + does not arrive within a specified timeout period. The PING is sent on one + thread, and another thread determines if the response arrives in time. + Separating these two activities allows Remoting to detect a failure + regardless of the cause of the failure.</para> + + <para>The creation of the <classname>ConnectionValidator</classname> is the + responsibility of the <classname>org.jboss.remoting.Client</classname> + class. All the application code needs to do is to register an implementation + of the <code>org.jboss.remoting.ConnectionListener</code> interface, which + has only one method:</para> + + <programlisting>public void handleConnectionException(Throwable throwable, Client client);</programlisting> + + <para>What actions the <classname>ConnectionListener</classname> chooses to + take are up to the application, but disconnecting the + <classname>Client</classname> might be a reasonable strategy.</para> + + <para>The <classname>Client</classname> class has three methods for + registering a <classname>ConnectionListener</classname>:</para> + + <programlisting> + public void addConnectionListener(ConnectionListener listener); + public void addConnectionListener(ConnectionListener listener, int pingPeriod); + public void addConnectionListener(ConnectionListener listener, Map metadata); + </programlisting> - <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. See the - transporter samples in the next chapter for detailed examples of how to - set up use of a transporter.</para> - </chapter> \ No newline at end of file + <para>The second method supports configuring the frequency of PING messages, + and the third method supports more general configuration of the + <classname>ConnectionValidator</classname>. Note that a given + <classname>Client</classname> maintains a single + <classname>ConnectionValidator</classname>, so the parameters in the + metadata map are applied only on the first call to + <methodname>Client.addConnectionListener()</methodname>. The following + parameters are supported by <classname>ConnectionValidator</classname>, + which is where the parameter names are defined:</para> + + <para><emphasis role="bold">VALIDATOR_PING_PERIOD</emphasis> (actual value + "validatorPingPeriod") - specifies the time, in milliseconds, that elapses + between the sending of PING messages to the server. The default value is + 2000.</para> + + <para><emphasis role="bold">VALIDATOR_PING_TIMEOUT</emphasis> (actual value + "validatorPingTimeout") - specifies the time, in milliseconds, allowed for + arrival of a response to a PING message. The default value is 1000.</para> + + <para>For more configuration parameters, see <xref + linkend="section-interactions"/>.</para> + + <para>Note, also, that <classname>ConnectionValidator</classname> creates a + client invoker to sends the PING messages, and it passes the metadata map to + configure the client invoker.</para> + + </section> + + <section id="section-server-side" xreflabel="Server side monitoring"> + <title>Server side monitoring</title> + + <para>A remoting server also has the capability to detect when a client is + no longer available. This is done by estabilishing a lease with the remoting + clients that connect to a server. On the client side, an + <classname>org.jboss.remoting.LeasePinger</classname> periodically sends + PING messages to the server, and on the server side an + <classname>org.jboss.remoting.Lease</classname> informs registered listeners + if the PING doesn't arrive withing the specified timeout period.</para> + + <para><emphasis role="bold">Server side activation.</emphasis> To turn on + server side connection failure detection of remoting clients, it is + necessary to satisfy two criteria. The first is that the client lease period + is set and is a value greater than 0. The value is represented in + milliseconds. The client lease period can be set by either the + 'clientLeasePeriod' attribute within the Connector configuration or by + calling the <classname>Connector</classname> method</para> + + <programlisting>public void setLeasePeriod(long leasePeriodValue);</programlisting> + + <para>The second + criterion is that an implementation of the + <code>org.jboss.remoting.ConnectionListener</code> interface is added as a + connection listener to the Connector, via the method</para> + + <programlisting>public void addConnectionListener(ConnectionListener listener)</programlisting> + + <para> Once both criteria are met, the remoting server will turn on client + leasing.</para> + + <para>Note that there is no way to register a + <classname>ConnectionListener</classname> via xml based configuration for + the <classname>Connector</classname>.</para> + + <para>The ConnectionListener will be notified of both client failures and + client disconnects via the handleConnectionException() method. If the client + failed, meaning its lease was not renewed within configured time period, the + first parameter to the handleConnectionException() method will be null. If + the client disconnected in a regular manner, the first parameter to the + handleConnectionException() method will be of type + ClientDisconnectedException (which indicates a normal termination). Note, + the client's lease will be renewed on the server with any and every + invocation made on the server from the client, whether it be a normal + invocation or a ping from the client internally.</para> + + <para>The actual lease window established on the server side is dynamic + based the rate at which the client updates its 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><emphasis role="bold">Client side activation.</emphasis> By default, + the client is not configured to do client leasing. To allow a client to do + leasing, either set the parameter "leasing" to "true" in the + <classname>InvokerLocator</classname> or set the parameter + <code>Client.ENABLE_LEASE</code> (actual value "enableLease") to true in the + <classname>InvokerLocator</classname> or in the + <classname>Client</classname> configuration map. [The use of + <code>Client.ENABLE_LEASE</code> is recommended.] 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 + suggested by the server. It is possible to override the suggested lease + period by setting the parameter + <code>org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PERIOD</code> (actual + value "lease_period") to a value greater than 0 and less than the value + suggested by the server. <emphasis role="bold">Note. </emphasis>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 to + the Client constructor. This map will be included in the Client instance + passed to the connection listener (via the handleConnectionException() + method) via the Client's getConfiguration() method.</para> + + <para>From the server side, there are two ways in which to disable leasing + (i.e. turn leasing off). The first is to call:</para> + + <programlisting>public void removeConnectionListener(ConnectionListener listener)</programlisting> + + <para>and remove all the registered ConnectionListeners. Once the last one + has been removed, leasing will be disabled and all the current leasing + sessions will be terminated. The other way is to call:</para> + + <programlisting>public void setLeasePeriod(long leasePeriodValue)</programlisting> + + <para>and pass a value less than zero. This will disable leasing, preventing + any new leases to be established but will allow current leasing sessions to + continue.</para> + + <para>The following parameter is relevant to leasing configuration on the server side:</para> + + <para><emphasis + role="bold"><code>org.jboss.remoting.ServerInvoker.CLIENT_LEASE_PERIOD</code></emphasis> + (actual value "clientLeasePeriod") - specifies the timeout period used by + the server to determine if a PING is late. The default value is "5000", + which indicates that leasing will be activated if an + <classname>org.jboss.remoting.ConnectionListener</classname> is registered + with the server. This is also the suggested lease period returned by the + server when the client inquires if leasing is activated.</para> + + <para>The following parameters are relevant to leasing configuration on the client side:</para> + + <para><emphasis + role="bold"><code>org.jboss.remoting.Client.ENABLE_LEASE</code></emphasis> + (actual value "enableLease") - if set to "true", will lead + <classname>org.jboss.remoting.Client</classname> to attempt to set up a + lease with the server, if leasing is activated on the server.</para> + + <para><emphasis + role="bold"><code>org.jboss.remoting.InvokerLocator.CLIENT_LEASE</code></emphasis> + (actual value "leasing") - if set to "true" in the + <classname>InvokerLocator</classname>, will lead + <classname>org.jboss.remoting.Client</classname> to attempt to set up a + lease with the server, if leasing is activated on the server. It is + suggested that this parameter be avoided, in favor of + <code>Client.ENABLE_LEASE</code>.</para> + + <para><emphasis + role="bold"><code>org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PERIOD</code></emphasis> + (actual value "lease_period") - if set to a value greater than 0 and less + than the suggested lease period returned by the server, will be used to + determine the time between PING messages sent by + <classname>LeasePinger</classname>.</para> + + <para><emphasis + role="bold"><code>org.jboss.remoting.LeasePinger.LEASE_PINGER_TIMEOUT</code></emphasis> + (actual value "leasePingerTimeout") - specifies the per invocation timeout + value use by <classname>LeasePinger</classname> when it sends PING messages. + In the absence of a configured value, the timeout value used by the + <classname>Client</classname> that created the + <classname>LeasePinger</classname> will be used.</para> + + <para>For examples of how to use server side connection listeners, reference + org.jboss.test.remoting.lease.LeaseTestServer and + org.jboss.test.remoting.lease.LeaseTestClient.</para> + + </section> + + <section id="section-interactions" xreflabel="Interactions between client side and server side connection monitoring"> + + <title>Interactions between client side and server side connection monitoring</title> + + <para>As of Remoting version 2.4, the client side and server side connection + monitoring mechanisms can be, and by default are, more closely related, in + two ways.</para> + + <orderedlist> + <listitem> If the parameter + <code>org.jboss.remoting.ConnectionValidator.TIE_TO_LEASE</code> (actual + value "tieToLease") is set to true, then, when the server receives a PING + message from an + <classname>org.jboss.remoting.ConnectionValidator</classname>, it will + return a boolean value that indicates whether a lease currently exists + for the connection being monitored. If leasing is activated on the client + and server side, then a value of "false" indicates that the lease has + failed, and the <classname>ConnectionValidator</classname> will treat a + returned value of "false" the same as a timeout; that is, it will notifiy + listeners of a connection failure. The default value of this parameter is + "true". <emphasis role="bold">Note. </emphasis>If leasing is not + activated on the client side, then this parameter has no + effect.</listitem> + + <listitem><para>If the parameter + <code>org.jboss.remoting.ConnectionValidator.STOP_LEASE_ON_FAILURE</code> + (actual value "stopLeaseOnFailure") is set to true, then, upon detecting + a connection failure, <classname>ConnectionValidator</classname> will + stop the <classname>LeasePinger</classname>, if any, pinging a lease on + the same connection. The default value is "true".</para> </listitem> + + </orderedlist> + + <para><emphasis role="bold">TIE_TO_LEASE</emphasis> (actual value + "tieToLease") - specifies whether <classname>ConnectionValidator</classname> + should treat the failure of a related lease on the server side as a + connection failure. The default value is "true".</para> + + <para><emphasis role="bold">STOP_LEASE_ON_FAILURE</emphasis> (actual value + "stopLeaseOnFailure") - specifies whether, when a + <classname>ConnectionValidator</classname> detects a connection failure, it + should stop the associated + <classname>org.jboss.remoting.LeasePinger</classname>, if any. The default + value is "true".</para> + + </section> +</chapter> \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/master.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/master.xml 2008-05-23 05:42:40 UTC (rev 4236) +++ remoting2/branches/2.x/docs/guide/en/master.xml 2008-05-27 23:57:45 UTC (rev 4237) @@ -17,14 +17,15 @@ <!ENTITY chap14 SYSTEM "chap14.xml"> <!ENTITY chap15 SYSTEM "chap15.xml"> <!ENTITY chap16 SYSTEM "chap16.xml"> +<!ENTITY chap17 SYSTEM "chap17.xml"> ]> <book> <bookinfo> <title>JBoss Remoting Guide</title> - <subtitle>JBoss Remoting version 2.2.0.GA</subtitle> + <subtitle>JBoss Remoting version 2.4.0.GA</subtitle> - <releaseinfo>March 19, 2007</releaseinfo> + <releaseinfo>May 28, 2008</releaseinfo> <mediaobject> <imageobject> @@ -33,7 +34,7 @@ </mediaobject> <copyright> - <year>2007 JBoss, a division of Red Hat</year> + <year>2008 JBoss, a division of Red Hat</year> <holder>.</holder> </copyright> @@ -70,4 +71,6 @@ &chap15; &chap16; + + &chap17; </book> \ No newline at end of file