From jboss-remoting-commits at lists.jboss.org Tue May 27 19:57:46 2008 Content-Type: multipart/mixed; boundary="===============6643954121660855825==" MIME-Version: 1.0 From: jboss-remoting-commits at lists.jboss.org To: jboss-remoting-commits at lists.jboss.org Subject: [jboss-remoting-commits] JBoss Remoting SVN: r4237 - remoting2/branches/2.x/docs/guide/en. Date: Tue, 27 May 2008 19:57:45 -0400 Message-ID: --===============6643954121660855825== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ Overview =
- What is JBoss Remoting + What is JBoss Remoting? = 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 @@ HTTP(S) - + = - Multiplex (SSL Multiplex) - - - Servlet (SSL Servlet) = - BiSocket (SSL BiSocket) + Bisocket (SSL Bisocket) @@ -171,10 +167,40 @@ How to get JBoss Remoting = The JBossRemoting distribution can be downloaded from - http://labs.jboss.com/portal/jbossremoting . This distribution + url=3D"http://www.jboss.org/jbossremoting/"> + http://www.jboss.org/jbossremoting/ . This distribution contains everything needed to run JBossRemoting stand alone. The distribution includes binaries, source, documentation, javadoc, and sa= mple code.
+ = +
+ What's new in version 2.4? + = + JBossRemoting 2.4.0.GA is an incremental release, with dozens of= bug fixes and several new features: + + = + + + servers can be bound to multiple IP addresses + + + can run in the presence of a security manager + + + greater configurability + + + supports IPv6 addresses + + + improved connection monitoring + + + server gets client address in invocations + + = + + = +
\ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap11.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - - Client programming model + + + How to use it - sample code = - 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 us= ed - exclusively to make calls on that server. This expectation dictates so= me - of the behavior of the remoting client. + Sample code demonstrating different remoting features can be found= in + the examples directory. They can be compiled and run manually via your I= DE + 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 = - 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 beca= use - 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. +
+ Simple invocation = - See test case - org.jboss.test.remoting.callback.push.MultipleCallbackServersTes= tCase - . - \ No newline at end of file + The simple invocation sample (found in the + org.jboss.remoting.samples.simple package), has two classes; SimpleCli= ent + and SimpleServer. It demonstrates making a simple invocation from a + remoting client to a remoting server. The SimpleClient class will crea= te + 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 call= ed + to make an invocation on the remoting server, passing the request payl= oad + 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. + + Within the SimpleServer, a remoting server is created and starte= d. + 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 initia= lize + 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 handl= er + is added to the Connector. Finally, the Connector is started and will + start listening for incoming client requests. + + 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 targ= et + 'run-simple-server' and then in another console window run the ant tar= get + 'run-simple-client'. For example: + + ant run-simple-serverant + then: + + ant run-simple-clientThe output + when running the SimpleClient should look like: + + 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 invocat= ion + + The output when running the SimpleServer should look like: + + Starting remoting server with locator uri of: socket:/= /localhost:5400 +Invocation request is: Do something +Returning response of: This is the return to SampleInvocationHandler invoc= ation + + Note: will have to manually shut down the SimpleServer once + started. +
+ +
+ HTTP invocation + + 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 t= he + 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, wil= l be + using the WebInvocationHandler (code shown below). + + public class WebInvocationHand= ler implements ServerInvocationHandler +{ + // Pre-defined returns to be sent back to client based on type of reque= st. + public static final String RESPONSE_VALUE =3D "This is the return to si= mple text based http invocation."; + public static final ComplexObject OBJECT_RESPONSE_VALUE =3D new Complex= Object(5, "dub", false); + public static final String HTML_PAGE_RESPONSE =3D "<html><head= ><title>Test HTML page</title></head><body>" + + "<h1>HTTP/Servlet= Test HTML page</h1><p>This is a simple page served for test." + + "<p>Should show u= p in browser or via invoker client</body></html>"; + + // Different request types that client may make + public static final String NULL_RETURN_PARAM =3D "return_null"; + public static final String OBJECT_RETURN_PARAM =3D "return_object"; + public static final String STRING_RETURN_PARAM =3D "return_string"; + + + /** + * called to handle a specific invocation + * + * @param invocation + * @return + * @throws Throwable + */ + public Object invoke(InvocationRequest invocati= on) throws Throwable + { + // Print out the invocation request + System.out.println("Invocation request from client is: " + invocatio= n.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 =3D invocation.getReturnPayload(); + responseMetadata.put(HTTPMetadataConstants.RESPONSE_CODE, new In= teger(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 exam= ple code. + return RESPONSE_VALUE; + } + else + { + return HTML_PAGE_RESPONSE; + } + } + + + 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 ch= eck + to see if the request parameter from the client was of type ComplexObj= ect. + If so, return the pre-built ComplexObject that was created as a static + variable. + + 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 messa= ge + to "Custom response code and message from remoting server". These are + non-standard code and message, but can be anything desired. + + Last, if have not found a matching invocation request parameter, + will just return some simple html. + + Now onto the client side for making the calls to this handler, w= hich + can be found in SimpleClient (code shown below). + + public class SimpleClient +{ + // Default locator values + private static String transport =3D "http"; + private static String host =3D "localhost"; + private static int port =3D 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 =3D new InvokerLocator(locatorURI); + System.out.println("Calling remoting server with locator uri of: " += locatorURI); + + Client remotingClient =3D 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 m= etadata map needs + // to be passed to the invoke() method. + Object response =3D remotingClient.invoke(ne= w ComplexObject(2, "foo", true), null); + + System.out.println("\nResponse from remoting http server when making= http POST request and sending a complex data object:\n" + response); + + + Map metadata =3D new HashMap(); + // set the metadata so remoting client knows to use http GET method = type + metadata.put("TYPE", "GET"); + // not actually sending any data to the remoting server, just want t= o get its response + response =3D remotingClient.invoke((Object) = null, metadata); + + 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 + metadata.put("TYPE", "POST"); + response =3D remotingClient.invoke(WebInvoca= tionHandler.STRING_RETURN_PARAM, metadata); + + 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 in= vocation handler + Integer responseCode =3D (Integer) metadata.= get(HTTPMetadataConstants.RESPONSE_CODE); + String responseMessage =3D (String) metadata.get(HTTPMetadataConstan= ts.RESPONSE_CODE_MESSAGE); + System.out.println("Response code from server: " + responseCode); + System.out.println("Response message from server: " + responseMessag= e); + + } + + + 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 remem= ber + from the WebInvocationHandler above, will expect this invocation to re= turn + a different ComplexObject, which can be seen in the following system + output line. + + 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 nee= ds + 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, ju= st + get data in response) and the metadata map just populated with the GET + type. This invocation request will return a response of html. + + Then, will change back to being a POST type request and will pas= s a + simple String as the payload to the invocation request. This will retu= rn 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. + + 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 th= en + in another console window run the ant target 'run-http-client'. For + example: + + ant run-http-server + + and then: + + ant run-http-client + + The output when running the SimpleClient should look like: + + Response from remoting http server when making http PO= ST request and sending a complex data object: +ComplexObject (i =3D 5, s =3D dub, b =3D false, bytes.length =3D 0) + +Response from remoting http server when making GET request: +<html><head><title>Test HTML page</title></head= ><body><h1>HTTP/Servlet Test HTML page</h1><p>Th= is is a simple page served for test.<p>Should show up in browser or v= ia invoker client</body></html> + +Response from remoting http server when making http POST request and sendi= ng 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 remoti= ng server + + Notice that the first response is the ComplexObject from the sta= tic + variable returned within WebInvocationHandler. The next response is ht= ml + and then simple text from the WebInvocationHandler. Can see the specif= ic + response code and message set in the WebInvocationHandler. + + The output from the SimpleServer should look like: + + Starting remoting server with locator uri of: http://l= ocalhost: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 =3D 2, s =3D foo, b = =3D true, bytes.length =3D 0) +Invocation request from client is: null +Invocation request from client is: return_string + + First the information for the http server invoker is written, wh= ich + 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. + + 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. +
+ +
+ Oneway invocation + + The oneway invocation sample (found in the + org.jboss.remoting.samples.oneway package) is very similar to the simp= le + invocation example, except in this sample, the client will make + asynchronous invocations on the server. + + The OnewayClient class sets up the remoting client as in the sim= ple + invocation sample, but instead of using the invoke() method, it uses t= he + invokeOneway() method on the Client class. There are two basic modes w= hen + making a oneway invocation in remoting. The first is to have the calli= ng + thread to be the one that makes the actual call to the server. This al= lows + the caller to ensure that the invocation request at least made it to t= he + 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 mak= ing + the request on the server, the original caller will be unaware. + + The OnewayServer is exactly the same as the SimpleServer from the + previous example, with the exception that invocation handler returns n= ull + (since even if did return a response, would not be delivered to the + original caller). + + To run this example, can compile both the OnewayClient and + OnewayServer class, then run the OnewayServer and then the OnewayClien= t. + Or can go to the examples directory and run the ant target + 'run-oneway-server' and then in another console window run the ant tar= get + 'run-oneway-client'. For example: + + ant run-oneway-server + + and then: + + ant run-oneway-client + + The output when running the OnewayClient should look like: + + 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.' + + The output when running the OnewayServer should look like: + + Starting remoting server with locator uri of: socket:/= /localhost:5400 +Invocation request is: Oneway call 1. +Invocation request is: Oneway call 2. + + Note: will have to manually shut down the OnewayServer once + started. + + Although this example only demonstrates making one way invocatio= ns, + could include this with callbacks (see further down) to have asynchron= ous + invocations with callbacks to verify was processed. +
+ +
+ Discovery and invocation + + 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 clien= t 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. + + 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 Detecto= rs + 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 be= ing + added or removed). + + In this particular example, the SimpleDetectorClient is register= ed + 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 notificati= on + is for removing a remoting server, the SimpleDetectorClient will simply + print out a message saying which server has been removed. + + 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. + + To run this example, can compile both the SimpleDetectorClient a= nd + 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 ta= rget + 'run-detector-client'. For example: + + ant run-detector-server + + and then: + + ant run-detector-client + + The initial output when running the SimpleDetectorClient should = look + like: + + 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 clie= nt 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 NOTIFICATIO= N: 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 remotin= g 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 t= his response to our welcome message: Received your welcome message. Thank = you! + + The output when running the SimpleDetectorServer should look + like: + + 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: so= cket://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 loca= tor uri of: socket://localhost:5400 +Fri Jan 13 09:36:46 EST 2006: [SERVER]: Added our invocation handler; we a= re 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 ba= ck to the client: Received your welcome message. Thank you! + + 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 availab= le + and will see something like the following appended in the + SimpleDetectorClient console window: + + 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/]= +
+ +
+ Callbacks + + 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. + + Within remoting, there are two approaches in which a callback ca= n 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. + + Looking at the CallbackClient class, will see that the first thi= ng + 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 t= he + InvokerCallbackHandler interface, is what is called upon with a Callba= ck + 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 obj= ect + which can help to identify callback context (similar to the handle obj= ect + 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 liste= ner + (more on this below in the server section). Although the CallbackHandl= er + is not called upon directly when doing pull callbacks, it is needed as= an + identifier for the callbacks. + + Then the client will wait a few seconds, make a simple invocatio= n on + the server, and then call on the remoting Client instance to get any + callbacks that may be available for our CallbackHandler. This will ret= urn + a list of callbacks, if any exist. The list will be iterated and each + callback will be printed to standard output. Finally, the callback han= dler + will be removed as a listener from the remoting Client (which in turns + removes it from the remoting server). + + After performing a pull callback, will perform a push callback. = This + is a little more involved as requires creating a callback server to wh= ich + 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 creat= ing + 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 callb= ack + messages to), and the callback handle object (which will be included in + all the callback messages delivered for this particular callback + listener). + + Then the client will wait a few seconds, to allow the target ser= ver + time to generate and deliver callback messages. After that, we remove = the + callback listener and clean up our callback server. + + The CallbackServer is pretty much the same as the previous sampl= es + in setting up the remoting server, via the Connector. The biggest chan= ge + resides in the ServerInvocationHandler implementation, + SampleInvocationHandler (which is an inner class to CallbackServer). T= he + first thing to notice is now have a variable called listeners, which i= s 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. + + 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 ta= rget + 'run-callback-server' and then in another window run the ant target + 'run-callback-client. For example: + + ant run-callback-server + + and then: + + ant run-callback-client + + The output in the CallbackClient console window should look + like: + + Calling remoting server with locator uri of: socket://= localhost:5400 +Invocation response: This is the return to SampleInvocationHandler invocat= ion +Pull Callback value =3D Callback 1: This is the payload of callback invoca= tion. +Pull Callback value =3D Callback 2: This is the payload of callback invoca= tion. +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 in= vocation. +Received callback handle object of: myCallbackHandleObject +Received callback server invoker of: InvokerLocator [socket://127.0.0.1:54= 00/] +Received push callback. +Received callback value of: Callback 4: This is the payload of callback in= vocation. +Received callback handle object of: myCallbackHandleObject +Received callback server invoker of: InvokerLocator [socket://127.0.0.1:54= 00/] + + This output shows that client first pulled two callbacks generat= ed + from the server. Then, after creating and registering our second callb= ack + handler and a callback server, two callbacks were received from the ta= rget + server. + + The output in the CallbackServer console window should look + like: + + 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. + + This output shows two distinct callback handlers being added and + removed (with an invocation request being received after the first was + added). + + There are a few important points to mention about this example. + First, notice that in the client, the same callback handle object in t= he + push callbacks was received as was registered with the callback listen= er. + 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. +
+ +
+ Streaming + + The streaning sample (found in the org.jboss.remoting.samples.st= ream + package) illustrates how a java.io.InputStream can be sent from a clie= nt + and read on demand from a server. This example is composed of two clas= ses: + StreamingClient and StreamingServer. + + 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. + + Looking at the StreamingClient, the remoting Client is created a= s 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. + + 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, whic= h is + an inner class to the StreamingServer. The handleStream() method within + the TestStreamInvocationHandler will use the stream passed to it to wr= ite + out its contents to a file on disk, as specified by the second paramet= er + 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. + + 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 targ= et + 'run-stream-client'. For example: + + ant run-stream-server + + and then: + + ant run-stream-client + + The output in the StreamingClient console window should look + like: + + 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. + + The output in the StreamingServer console window should look + like: + + 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 + + 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 loca= ted + in the examples\org\jboss\remoting\samples\stream directory. +
+ +
+ JBoss Serialization + + 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 clas= ses: + SerializationClient, SerializationServer, and + NonSerializablePayload. + + This example is exactly like the one from the simple example with + two differences. The first difference is the use of JBoss Serializatio= n 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 receivi= ng a + simple String type for the remote invocation payload, will be sending = and + receiving an instance of the NonSerializablePayload class. + + 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 param= eter + constructor. This is a requirement of JBoss Serialization for object + instances that do not implement the Serializable interface. However, t= his + void parameter constructor can be private, as in the case of + NonSerializablePayload, as to not change the external API of the + class. + + To run this example, can compile both the SerializationClient and + SerializationServer class, then run the SerializationServer and then t= he + SerializationClient. Or can go to the examples directory and run the a= nt + target 'run-serialization-server' and then in another window run the a= nt + target 'run-serialization-client'. For example: + + ant run-serialization-server + + and then: + + ant run-serialization-client + + The output in the SerializationClient console window should look + like: + + Calling remoting server with locator uri of: socket://= localhost:5400/?serializationtype=3Djboss +Invoking server with request of 'NonSerializablePayload - name: foo, id: 1' +Invocation response: NonSerializablePayload - name: bar, id: 2 + + The output in the SerializationServer console window should look + like: + + Starting remoting server with locator uri of: socket:/= /localhost:5400/?serializationtype=3Djboss +Invocation request is: NonSerializablePayload - name: foo, id: 1 +Returning response of: NonSerializablePayload - name: bar, id: 2 + + Note: will have to manually shut down the SerializationServer on= ce + started. +
+ +
+ Transporters + +
+ Transporters - beaming POJOs + + 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 transport= ers + provide the same behavior via a simple API without the need for any = of + the newer technologies. + + When boiled down, transporters take a plain old java object (P= OJO) + 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 PO= JO. + Since JBoss Remoting is used, can select from a number of different + network transports (i.e. rmi, http, socket, multiplex, etc.), includ= ing + support for SSL. Even clustering features can be included. + + How it works + + 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. + + To start, will need to have a plain old java object that + implements one or more interfaces that want to expose for remote met= hod + invocation. Then will need to create a + org.jboss.remoting.transporter.TransporterServer 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 + createTransporterServer() method of the TransporterServ= er + 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 w= ay + 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. + + 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 recei= ves + from clients. By default, the subsystem underwhich the server invoca= tion + handler is registered is the interface class name for which the targ= et + 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 stop() 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). + + On the client side, in order to be able to call on the target = pojo + remotely, will need to use the + org.jboss.remoting.transporter.TransporterClient. 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 createTransporterClient(), where will + pass the locator to find the target pojo (same as one used when crea= ting + the TransporterServer) and the interface for the target pojo that wa= nt + to make remote method invocations on. The return from this create ca= ll + 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 t= he + covers. Note that can have multiple transporter clients to the same + target pojo, each using different interface types for making + calls. + + 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 destroyTransporterClient() + method of the TransporterClient. This is important to remember to do= , as + will otherwise leave network resources active even though not in + use. + + 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 h= ave + 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 t= his + can be done. + + 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 TransporterClie= nt + in clustered mode to create a client proxy that will discover the + location of the target pojos are wanting to call on. Will also provi= de + 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). +
+ + 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). + +
+ Transporters sample - simple + + 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. + + 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 c= ase, + org.jboss.remoting.samples.transporter.simple.DateProcessorImpl, + implements the + org.jboss.remoting.samples.transporter.simple.DateProcessor interfac= es + (as shown below): + + public interface DateProcessor +{ + public String formatDate(Date dateToConvert); +} + + +public class DateProcessorImpl implements DateProcessor +{ + public String formatDate(Date dateToConvert) + { + DateFormat dateFormat =3D DateFormat.getDateInstance(DateFormat.MEDI= UM); + return dateFormat.format(dateToConvert); + } +} + + This is then exposed using the TransporterServer by the + org.jboss.remoting.samples.transporter.simple.Server class. + + public class Server +{ + public static void main(String[] args) throws Exception + { + TransporterServer server =3D TransporterServer.createTransporterServ= er("socket://localhost:5400", new DateProcessorImpl(), DateProcessor.class.= getName()); + Thread.sleep(10000); + server.stop(); + } +} + + The Server class simply creates a TransporterServer by indicat= ing + 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. + + Next need to have client to make the remote invocation. This c= an + be found within + org.jboss.remoting.samples.transporter.simple.Client. + + public class Client +{ + public static void main(String[] args) throws Exception + { + DateProcessor dateProcessor =3D (DateProcessor) TransporterClient.cr= eateTransporterClient("socket://localhost:5400", DateProcessor.class); + String formattedDate =3D dateProcessor.formatDate(new Date()); + System.out.println("Current date: " + formattedDate); + } +} + + In the Client class, create a TransporterClient which can be c= ast + 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 call= ing + on for the target pojo. Once have the DateProcessor variable, will m= ake + the call to formatDate() and pass a newly created Date object. The + return will be a formated String of the date passed. + + 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 a= nt + target 'run-transporter-simple-client'. For example: + + ant run-transporter-simple-server + + and then: + + ant run-transporter-simple-client + + The output from the client window should look similar to: + + Current date: Jul 31, 2006 +
+ +
+ Transporter sample - basic + + The basic transporter example (found in + org.jboss.remoting.samples.transporter.basic package) illustrates ho= w to + build a simple transporter for making remote invocations on plain old + java objects. + + In this basic transporter example, will be using a few domain + objects; Customer and Address, which are just data + objects. + + public class Customer implements Serializable +{ + private String firstName =3D null; + private String lastName =3D null; + private Address addr =3D null; + private int customerId =3D -1; + + public String getFirstName() + { + return firstName; + } + + public void setFirstName(String firstName) + { + this.firstName =3D firstName; + } + + public String getLastName() + { + return lastName; + } + + public void setLastName(String lastName) + { + this.lastName =3D lastName; + } + + public Address getAddr() + { + return addr; + } + + public void setAddr(Address addr) + { + this.addr =3D addr; + } + + public int getCustomerId() + { + return customerId; + } + + public void setCustomerId(int customerId) + { + this.customerId =3D customerId; + } + + public String toString() + { + StringBuffer buffer =3D 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(); + } +} + + public class Address implements Serializable +{ + private String street =3D null; + private String city =3D null; + private String state =3D null; + private int zip =3D -1; + + public String getStreet() + { + return street; + } + + public void setStreet(String street) + { + this.street =3D street; + } + + public String getCity() + { + return city; + } + + public void setCity(String city) + { + this.city =3D city; + } + + public String getState() + { + return state; + } + + public void setState(String state) + { + this.state =3D state; + } + + public int getZip() + { + return zip; + } + + public void setZip(int zip) + { + this.zip =3D zip; + } +} + + Next comes the POJO that we want to expose a remote proxy for, + which is CustomerProcessorImpl class. This implementati= on + has one method to process a Customer object. It also + implements the CustomerProcessor interface. + + public class CustomerProcess= orImpl implements CustomerProcessor +{ + /** + * 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 !=3D null && customer.getCustomerId() < 0) + { + customer.setCustomerId(new Random().nextInt(1000)); + } + System.out.println("processed customer with new id of " + customer.g= etCustomerId()); + return customer; + } +} + + public interface CustomerPro= cessor +{ + /** + * 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); +} + + So far, nothing special, just plain old java objects. Next nee= d to + create the server component that will listen for remote request to + invoke on the target POJO. This is where the transporter comes + in. + + public class Server +{ + private String locatorURI =3D "socket://localhost:5400"; + private TransporterServer server =3D null; + + public void start() throws Exception + { + server =3D TransporterServer.createTransport= erServer(locatorURI, new CustomerProcessorImpl()); + } + + public void stop() + { + if(server !=3D null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server =3D new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +} + + The Server class is a pretty simple one. It calls= the + TransporterServer factory method to create the server + component for the CustomerProcessorImpl instance using = the + specified remoting locator information. + + The TransporterServer returned from the + createTransporterServer() call will be a running instan= ce + of a remoting server using the socket transport t= hat + is bound to localhost and listening for remote + requests on port 5400. The requests that come in = will + be forwarded to the remoting handler which will convert them into di= rect + method calls on the target POJO, CustomerProcessorImpl = in + this case, using reflection. + + The TransporterServer has a start() = and + stop() method exposed to control when to start and stop= the + running of the remoting server. The start() method is + called automatically within the createTransporterServer() + method, so is ready to receive requests upon the return of this meth= od. + The stop() method, however, needs to be called explicit= ly + when no longer wish to receive remote calls on the target POJO. + + Next up is the client side. This is represented by the + Client class. + + public class Client +{ + private String locatorURI =3D "socket://localhost:5400"; + + public void makeClientCall() throws Exception + { + Customer customer =3D createCustomer(); + + CustomerProcessor customerProcessor =3D (Cus= tomerProcessor) TransporterClient.createTransporterClient(locatorURI, Custo= merProcessor.class); + + System.out.println("Customer to be processed: " + customer); + Customer processedCustomer =3D customerProce= ssor.processCustomer(customer); + System.out.println("Customer is now: " + processedCustomer); + + TransporterClient.destroyTransporterClient(c= ustomerProcessor); + } + + private Customer createCustomer() + { + Customer cust =3D new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr =3D 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 =3D new Client(); + try + { + client.makeClientCall(); + } + catch(Exception e) + { + e.printStackTrace(); + } + } +} + + The Client class is also pretty simple. It create= s a + new Customer object instance, creates the remote proxy = to + the CustomerProcessor, and then calls on the + CustomerProcessor to process its new Customer + instance. + + To get the remote proxy for the CustomerProcessor, + all that is required is to call the TransporterClient's + method createTransporterClient() 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 speci= fied + type, CustomerProcessor in this case, which is backed b= y a + remoting client which in turn makes the calls to the remote POJO's + remoting server. Once the call to createTransportClient() + 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). + + When finished making calls on the remote POJO proxy, will need= to + explicitly destroy the client by calling + destroyTransporterClient() and pass the remote proxy + instance. This allows the remoting client to disconnect from the POJ= O's + remoting server and clean up any network resources previously + used. + + 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: + + ant run-transporter-basic-server + + and then: + + ant run-transporter-basic-client + + The output from the Client console should be similar to: + + 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 + + + + and the output from the Server class should be similar to: + + processed customer with new id of 204 + + The output shows that the Customer instance creat= ed + on the client was sent to the server where it was processed (by sett= ing + the customer id to 204) and returned to the client (and printed out + showing that the customer id was set to 204). +
+ +
+ Transporter sample - JBoss serialization + + 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. + + To start, there are a few more domain objects: Order, + OrderProcessor, and OrderProcessorImpl. Th= ese + will use some of the domain objects from the previous example as wel= l, + such as Customer. + + public class Order +{ + private int orderId =3D -1; + private boolean isProcessed =3D false; + private Customer customer =3D null; + private List items =3D null; + + + public int getOrderId() + { + return orderId; + } + + public void setOrderId(int orderId) + { + this.orderId =3D orderId; + } + + public boolean isProcessed() + { + return isProcessed; + } + + public void setProcessed(boolean processed) + { + isProcessed =3D processed; + } + + public Customer getCustomer() + { + return customer; + } + + public void setCustomer(Customer customer) + { + this.customer =3D customer; + } + + public List getItems() + { + return items; + } + + public void setItems(List items) + { + this.items =3D items; + } + + public String toString() + { + StringBuffer buffer =3D 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 =3D items.iterator(); + while(itr.hasNext()) + { + buffer.append("\n" + itr.next().toString()); + } + + return buffer.toString(); + } +} + + public class OrderProcessorI= mpl implements OrderProcessor +{ + private CustomerProcessor customerProcessor =3D null; + + public OrderProcessorImpl() + { + customerProcessor =3D new CustomerProcessorImpl(); + } + + public Order processOrder(Order order) + { + System.out.println("Incoming order to process from customer.\n" + or= der.getCustomer()); + + // has this customer been processed? + if(order.getCustomer().getCustomerId() < 0) + { + order.setCustomer(customerProcessor.processCustomer(order.getCust= omer())); + } + + List items =3D order.getItems(); + System.out.println("Items ordered:"); + Iterator itr =3D 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.getOrd= erId()); + return order; + } +} + + public interface OrderProcessor +{ + public Order processOrder(Order order); +} + + The OrderProcessorImpl will take orders, via the + processOrder() method, check that the customer for the + order has been processed, and if not have the customer processor pro= cess + the new customer. Then will place the order, which means will just s= et + the order id and processed attribute to true. + + The most important point to this example is that the + Order class does NOT implement + java.io.Serializable. + + Now onto the Server class. This is just like the + previous Server class in the basic example with one main + difference: the locatorURI value. + + public class Server +{ + private String locatorURI =3D "socket://localhost:5400/?serializationtype=3Djboss"; + private TransporterServer server =3D null; + + public void start() throws Exception + { + server =3D TransporterServer.createTransporterServer(locatorURI, new= OrderProcessorImpl()); + } + + public void stop() + { + if(server !=3D null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server =3D new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +} + + The addition of serializationtype=3Djboss t= ells + the remoting framework to use JBoss Serialization in place of the + standard java serialization. + + On the client side, there is the Client class, ju= st + as in the previous basic example. + + public class Client +{ + private String locatorURI =3D "socket://localhost:5400/?serializationtype=3Djboss"; + + public void makeClientCall() throws Exception + { + Order order =3D createOrder(); + + OrderProcessor orderProcessor =3D (OrderProcessor) TransporterClient= .createTransporterClient(locatorURI, OrderProcessor.class); + + System.out.println("Order to be processed: " + order); + Order changedOrder =3D orderProcessor.processOrder(order); + System.out.println("Order now processed " + changedOrder); + + TransporterClient.destroyTransporterClient(orderProcessor); + + } + + private Order createOrder() + { + Order order =3D new Order(); + Customer customer =3D createCustomer(); + order.setCustomer(customer); + + List items =3D 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 =3D new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr =3D 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 =3D new Client(); + try + { + client.makeClientCall(); + } + catch(Exception e) + { + e.printStackTrace(); + } + } +} + + Again, the biggest difference to note is that have added + serializationtype=3Djboss to the locator uri. + + Note: Running this example requires JDK 1.5. + + 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: + + ant run-transporter-serialization-server + + and then: + + ant run-transporter-serialization-client + + When the server and client are run the output for the + Client class is: + + 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 + + + The client output shows the printout of the newly created order + before calling the OrderProcessor 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. + + And the output from the Server is: + + 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 + + + The server output shows the printout of the customer before be= ing + processed and then the order while being processed. +
+ +
+ Transporter sample - clustered + + In the previous examples, there has been one and only one targ= et + 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. + + 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 SocketServer class, which is the exact same as the + Server class in the basic example, except for the call = to + the TransportServer's createTransportServer() + method. + + public class SocketServer +{ + public static String locatorURI =3D "socket://localhost:5400"; + private TransporterServer server =3D null; + + public void start() throws Exception + { + server =3D TransporterServer.createTransport= erServer(getLocatorURI(), new CustomerProcessorImpl(), + CustomerProcessor= .class.getName(), true); + } + + protected String getLocatorURI() + { + return locatorURI; + } + + public void stop() + { + if(server !=3D null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + SocketServer server =3D new SocketServer(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +} + + Notice that are now calling on the TransportServer to + create a server with the locator uri and target POJO + (CustomerProcessorImpl) as before, but have also added = the + interface type of the target POJO (CustomerProcessor) a= nd + that want clustering turned on (via the last true + parameter). + + The interface type of the target POJO is needed because this w= ill + be used as the subsystem within the remoting server for the target P= OJO. + The subsystem value will be what the client uses to determine if + discovered remoting server is for the target POJO they are looking + for. + + + The transporter uses the MulticastDetector from JBoss Remoti= ng + for automatic discovery when in clustered mode. The actual detecti= on + of remote servers that come online can take up to a few seconds on= ce + started. There is a JNDI based detector provided within JBoss + Remoting, but has not been integrated within the transporters + yet. + + + The second server class is the RMIServer class. T= he + RMIServer class extends the SocketServer c= lass + and uses a different locator uri to specify rmi a= s the + transport protocol and a different port + (5500). + + public class RMIServer extends SocketServer +{ + private String localLocatorURI =3D "rmi://local= host:5500"; + + protected String getLocatorURI() + { + return localLocatorURI; + } + + public static void main(String[] args) + { + SocketServer server =3D new RMIServer(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +} + + The last server class is the HTTPServer class. The + HTTPServer class also extends the SocketServer + class and specifies http as the transport protocol + and 5600 as the port to listen for requests + on. + + public class HTTPServer extends SocketServer +{ + private String localLocatorURI =3D "http://loca= lhost:5600"; + + protected String getLocatorURI() + { + return localLocatorURI; + } + + public static void main(String[] args) + { + SocketServer server =3D new HTTPServer(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +} + + On the client side, there is only the Client clas= s. + This class is very similar to the one from the basic example. The ma= in + exceptions are (1) the addition of a TransporterClient = call + to create a transporter client and (2) the fact that it continually + loops, making calls on its customerProcessor variable to + process customers. This is done so that when we run the client, we c= an + kill the different servers and see that the client continues to loop + making its calls without any exceptions or errors. + + public class Client +{ + private String locatorURI =3D SocketServer.loca= torURI; + + private CustomerProcessor customerProcessor =3D null; + + public void makeClientCall() throws Exception + { + Customer customer =3D createCustomer(); + + System.out.println("Customer to be processed: " + customer); + Customer processedCustomer =3D customerProce= ssor.processCustomer(customer); + System.out.println("Customer is now: " + processedCustomer); + + //TransporterClient.destroyTransporterClient(customerProcessor); + } + + public void getCustomerProcessor() throws Exception + { + customerProcessor =3D (CustomerProcessor) Tr= ansporterClient.createTransporterClient(locatorURI, CustomerProcessor.class= , true); + } + + private Customer createCustomer() + { + Customer cust =3D new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr =3D 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 =3D new Client(); + try + { + client.getCustomerProcessor(); + while(true) + { + try + { + client.makeClientCall(); + Thread.currentThread().sleep(5000); + } + catch(Exception e) + { + e.printStackTrace(); + } + } + } + catch(Exception e) + { + e.printStackTrace(); + } + } +} + + The first item of note is that the locator uri from the + SocketServer class is being used. Technically, this is = not + required as once the clustered TransporterClient 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 ri= ght + away, it is best to bootstrap with a known target server. + + Can also see that in the main() method, the first + call on the Client instance is to getCustomerProcessor(). + This method will call the TransporterClient's + createTransporterClient() method and passes the locator= uri + for the target POJO server, the type of POJO's remote proxy, and that + clustering should be enabled. + + After getting the customer processor remote proxy, will + continually loop making calls using the remote proxy (via the + processCustomer() method on the + customerProcessor variable). + + To run this example, all the servers need to be started (by + running the SocketServer, RMIServer, and + HTTPServer classes). Then run the Client class. This ca= n be + done via ant targets as well. So for example, could open four console + windows and enter the ant targets as follows: + + ant run-transporter-clustered-socket-server + + ant run-transporter-clustered-http-server + + ant run-transporter-clustered-rmi-server + + ant run-transporter-clustered-client + + Once the client starts running, should start to see output log= ged + to the SocketServer, since this is the one used to + bootstrap. This output would look like: + + processed customer with new id of 378 +processed customer with new id of 487 +processed customer with new id of 980 + + Once the SocketServer 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 serv= er + 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: + + ... +org.jboss.remoting.CannotConnectException: Can not connect http= client invoker. + at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnecti= on(HTTPClientInvoker.java:147) + at org.jboss.remoting.transport.http.HTTPClientInvoker.transport(HTTPClie= ntInvoker.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(TransporterCli= ent.java:219) + at $Proxy0.processCustomer(Unknown Source) + at org.jboss.remoting.samples.transporter3.client.Client.makeClientCall(C= lient.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.j= ava:39) + at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccess= orImpl.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.<init>(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(HttpURLCo= nnection.java:792) + at sun.net.www.protocol.http.HttpURLConnection.plainConnect(HttpURLConnec= tion.java:744) + at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.= java:669) + at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLCon= nection.java:836) + at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnecti= on(HTTPClientInvoker.java:117) + ... 14 more + + since there are no target servers left to make calls on. Notice + that earlier in the client output there were no errors while was fai= ling + over to the different servers as they were being killed. + + 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 serv= ers + 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: + + ... + at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.= java:669) + at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLCon= nection.java:836) + at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnecti= on(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 + +... + + + 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. + + 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 runn= ing + in other processes. + +
+ +
+ Transporters sample - multiple + + The multiple transporter example (found in + org.jboss.remoting.samples.transporter.multiple package) shows how c= an + 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 focu= s on + the server and client code. On the server side, need to create the + TransporterServer so that will included both of the target pojos. + + public class Server +{ + private String locatorURI =3D "socket://localhost:5400"; + private TransporterServer server =3D null; + + public void start() throws Exception + { + server =3D TransporterServer.createTransporterServer(locatorURI, new= CustomerProcessorImpl(), CustomerProcessor.class.getName()); + server.addHandler(new AccountProcessorImpl(), AccountProcessor.class= .getName()); + } + + public void stop() + { + if(server !=3D null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server =3D new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch(Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +} + + The TransporterServer is created with the CustomerProcessorImp= l as + the inital target pojo. Now that have a live TransporterServer, can = add + other pojos as targets. This is done using the addHandler() method w= here + the target pojo instance is passed and then the interface type to be + exposed as. + + Next have the Client that makes the call to both pojos. + + public class Client +{ + private String locatorURI =3D "socket://localhost:5400"; + + public void makeClientCall() throws Exception + { + Customer customer =3D createCustomer(); + + CustomerProcessor customerProcessor =3D (CustomerProcessor) Transpor= terClient.createTransporterClient(locatorURI, CustomerProcessor.class); + + System.out.println("Customer to be processed: " + customer); + Customer processedCustomer =3D customerProcessor.processCustomer(cus= tomer); + System.out.println("Customer is now: " + processedCustomer); + + AccountProcessor accountProcessor =3D (AccountProcessor) Transporter= Client.createTransporterClient(locatorURI, AccountProcessor.class); + + System.out.println("Asking for a new account to be created for custo= mer."); + Account account =3D accountProcessor.createAccount(processedCustomer= ); + System.out.println("New account: " + account); + + TransporterClient.destroyTransporterClient(customerProcessor); + TransporterClient.destroyTransporterClient(accountProcessor); + + } + + private Customer createCustomer() + { + Customer cust =3D new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr =3D 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= =3D new org.jboss.remoting.samples.transporter.multiple.client.Client(); + try + { + client.makeClientCall(); + } + catch (Exception e) + { + e.printStackTrace(); + } + } + + +} + + Notice that TransporterClients are created for each target pojo + want to call upon, they just happen to share the same locator uri. T= hese + are independant instances so need to both be destroyed on their own = when + finished with them. + + 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: + + ant run-transporter-multiple-server + + and then: + + ant run-transporter-multiple-client + + The output for the server should look similar to: + + 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 + + and the output from the client should look similar to: + + 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 + +
+ +
+ Transporters sample - proxy + + 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 re= turn + it as response to a method invocation. + + To start, will look at the initial target pojo, + CustomerProcessorImpl. + + public class CustomerProcessorImpl implements Custom= erProcessor +{ + private String locatorURI =3D "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 !=3D null && customer.getCustomerId() < 0) + { + customer.setCustomerId(new Random().nextInt(1000)); + } + + ICustomer customerProxy =3D null; + try + { + TransporterServer server =3D TransporterServer.createTransporterS= erver(locatorURI, customer, ICustomer.class.getName()); + customerProxy =3D (ICustomer) TransporterClient.createTransporter= Client(locatorURI, ICustomer.class); + } + catch (Exception e) + { + e.printStackTrace(); + } + + System.out.println("processed customer with new id of " + customerPr= oxy.getCustomerId()); + return customerProxy; + } + +} + + 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. + + Next will look at the Customer class. It is a basic data objec= t in + that is really just stores the customer data. + + public class Customer implements Serializable, ICust= omer +{ + private String firstName =3D null; + private String lastName =3D null; + private Address addr =3D null; + private int customerId =3D -1; + + public String getFirstName() + { + return firstName; + } + + public void setFirstName(String firstName) + { + this.firstName =3D firstName; + } + + public String getLastName() + { + return lastName; + } + + public void setLastName(String lastName) + { + this.lastName =3D lastName; + } + + public Address getAddr() + { + return addr; + } + + public void setAddr(Address addr) + { + this.addr =3D addr; + } + + public int getCustomerId() + { + return customerId; + } + + public void setCustomerId(int customerId) + { + this.customerId =3D customerId; + } + + public String toString() + { + System.out.println("Customer.toString() being called."); + StringBuffer buffer =3D 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(); + } + + +} + + + Notice the toString() method and how it prints out to the stan= dard + out when being called. This will be important when the sample is run + later. + + Now if look at the Server class, will see is a standard setup = like + have seen in previous samples. + + public class Server +{ + private String locatorURI =3D "socket://localhost:5400"; + private TransporterServer server =3D null; + + public void start() throws Exception + { + server =3D TransporterServer.createTransporterServer(locatorURI, new= CustomerProcessorImpl(), CustomerProcessor.class.getName()); + } + + public void stop() + { + if (server !=3D null) + { + server.stop(); + } + } + + public static void main(String[] args) + { + Server server =3D new Server(); + try + { + server.start(); + + Thread.currentThread().sleep(60000); + + } + catch (Exception e) + { + e.printStackTrace(); + } + finally + { + server.stop(); + } + } +} + + It is creating a TransporterServer for the CustomerProcessImpl + upon being started and will wait 60 seconds for invocations. + + Next is the Client class. + + public class Client +{ + private String locatorURI =3D "socket://localhost:5400"; + + public void makeClientCall() throws Exception + { + Customer customer =3D createCustomer(); + + CustomerProcessor customerProcessor =3D (CustomerProcessor) Transpor= terClient.createTransporterClient(locatorURI, CustomerProcessor.class); + + System.out.println("Customer to be processed: " + customer); + ICustomer processedCustomer =3D customerProcessor.processCustomer(cu= stomer); + // processedCustomer returned is actually a proxy to the Customer in= stnace + // that lives on the server. So when print it out below, will actua= lly + // be calling back to the server to get the string (vi toString() ca= ll). + // Notice the output of 'Customer.toString() being called.' on the s= erver side. + System.out.println("Customer is now: " + processedCustomer); + + TransporterClient.destroyTransporterClient(customerProcessor); + + + } + + private Customer createCustomer() + { + Customer cust =3D new Customer(); + cust.setFirstName("Bob"); + cust.setLastName("Smith"); + Address addr =3D 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 =3D new Client(); + try + { + client.makeClientCall(); + } + catch (Exception e) + { + e.printStackTrace(); + } + } + + +} + + The client class looks similar to the other example seen in th= at + it creates a TransporterClient for the CustomerProcessor and calls o= n 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). + + To run this example, run the Server class and then the Client + class. This can be done via ant targets 'run-transporter-proxy-serve= r' + and then 'run-transporter-proxy-client'. For example: + + ant run-transporter-proxy-server + + ant then: + + ant run-transporter-proxy-client + + The output for the client should look similar to: + + 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 + + + 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 proces= sed. + Then have the print out of the customer after has been processed. No= tice + that when the ICustomer object instance is printed out the second ti= me, + do not see the 'Customer.toString() being called'. This is because t= hat + 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). + + Now, if look at output from the server will look similar + to: + + processed customer with new id of 418 +Customer.toString() being called. + + Notice that the 'Customer.toString() being called.' printed ou= t 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. + + 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. +
+ +
+ Transporter sample -complex + + 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 match= ing + Doctors and Patients using the ProviderInterface and provides a more + complex sample in which to demonstrate how to use transporters. + + 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: + + ant run-transporter-complex-server + + and then: + + ant run-transporter-complex-client + + The output for the client should look similar to: + + *** Have a new patient that needs a doctor. The pat= ient 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 pr= evious 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(TransporterCli= ent.java:237) + at $Proxy0.findDoctor(Unknown Source) + at org.jboss.remoting.samples.transporter.complex.client.Client.makeClien= tCall(Client.java:72) + at org.jboss.remoting.samples.transporter.complex.client.Client.main(Clie= nt.java:90) + at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) + at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.j= ava:39) + at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccess= orImpl.java:25) + at java.lang.reflect.Method.invoke(Method.java:585) + at com.intellij.rt.execution.application.AppMain.main(AppMain.java:86) + + + 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 availa= ble + 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. +
+
+ +
+ Multiplex invokers + + This section illustrates the construction of multiplex invoker + groups described in the section . The + directory + +
+ examples/org/jboss/remoting/samples/multiplex/invoker +
+ + contains a server class, + MultiplexInvokerServer, which is suitable for u= se + with any of the client classes described below. It may be run in an ID= E or + from the command line using ant target run-multiplex-server + from the build.xml file found in the examples + directory. The server will stay alive, processing invocation requests = as + they are presented, until it has sent two push callbacks to however ma= ny + listeners are registered, at which time it will shut itself down. + + The sample clients are as follows. Each sample client + <client> may be run in an IDE or by using t= he + ant target run-<client> (e.g., + run-Client2Server1). + + + + Client2Server1: A + MultiplexClientInvoker starts according to + client rule 2, after which a + MultiplexServerInvoker is started according= to + server rule 1. Note that the Client and + Connector are passed matching + clientMultiplexId and + serverMultiplexId parameters, + respectively. + + + + Client2Server2: A + MultiplexClientInvoker starts according to + client rule 2, after which a + MultiplexServerInvoker is started according= to + server rule 2. Note that no clientMultiplexId= is + passed to the Client and no + serverMultiplexId parameter is passed to the + Connector in this example. + + + + Client3Server1: A + MultiplexClientInvoker is created, and, lac= king + binding information, finds itself governed by client rule 3. + Subsequently, a MultiplexServerInvoker is + started according to server rule 1, providing the binding informat= ion + which allows the MultiplexClientInvoker to + start. Note that the Client and + Connector are passed matching + clientMultiplexId and + serverMultiplexId parameters, + respectively. + + + + Server2Client1: A + MultiplexServerInvoker starts according to + server rule 2, after which a + MultiplexClientInvoker is started according= to + client rule 1. Note that the Connector and + Client are passed matching + serverMultiplexId and + clientMultiplexId parameters, + respectively. + + + + Server2Client2: A + MultiplexServerInvoker starts according to + server rule 2, after which a + MultiplexClientInvoker is started according= to + client rule 2. Note that no serverMultiplexId= is + passed to the Connector and no + clientMultiplexId parameter is passed to the + Client in this example. + + + + Server3Client1: A + MultiplexServerInvoker is created, and, lac= king + connect information, finds itself governed by server rule 3. + Subsequently, a MultiplexClientInvoker is + started according to client rule 1, providing the connect informat= ion + which allows the MultiplexServerInvoker to + start. Note that the Connector and + Client are passed matching + serverMultiplexId and + clientMultiplexId parameters, + respectively. + + + + For variety, the examples in which the client invoker starts fir= st + use the configuration Map to pass invoker group + parameters, and the examples in which the server invoker starts first = pass + parameters in the InvokerLocator. +
+ \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap13.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - Getting the JBossRemoting source and building + Compatibility and versioning = - 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: - - cvs -d:pserver:anonymous(a)anoncvs.forge.jboss.com:/cv= sroot/jboss checkout JBossRemoting - - To check out the source using a committer user id, use the - following: - - cvs -d:ext:username(a)cvs.forge.jboss.com:/cvsroot/jbo= ss checkout JBossRemoting - - This should checkout the entire remoting project, including doc, - tests, libs, etc. - - See - - http://www.jboss.org/wiki/Wiki.jsp?page=3DCVSRepository for m= ore - information on how to access the JBoss CVS repository. - - The build process for JBossRemoting is based on a standard ant b= uild - file (build.xml). The version of ant that is supported is ant 1.6.2, b= ut - should work with earlier versions as there are no special ant features - being used. - - The main ant build targets are as follows: - - compile - compiles all the co= re - JBossRemoting classes. - - jars - creates the - jboss-remoting.jar file from the compiled classes - - dist.jars - creates the - subsystem jar files (jboss-remoting-core.jar, jboss-remoting-socket.ja= r, etc.) - from the compiled classes - = - javadoc - creates the javadoc= html - files for JBossRemoting - - tests.compile - compiles the - JBossRemoting test files - - tests.jars - creates the - jboss-remoting-tests.jar and jboss-remoting-loading-tests.jar - files. - - tests.quick - runs the functi= onal - unit tests for JBossRemoting. - - tests - runs all the tests for - JBossRemoting, including functional and performance tests for all the - different transports. - - clean - removes all the build - artifacts and directories. - - most - calls clean then jars - targets. - - dist - builds the full - JBossRemoting distribution including running the full test suite. - - dist.quick - builds the full - JBossRemoting distribution, but does not run the test suite. - - The root directory for all build output is the output directory. - Under this directory will be: - - classes - compiled core classes - - - etc - deployment and JMX XMBean xml files - - - lib - all the jars and war file produced by t= he - build - - tests - contains the compiled test classes and - test results - - For most development, the most target can be used. Please run the - tests.quick target before checking anything in to ensure that code cha= nges - did not break any previously functioning test. + As of JBossRemoting 2.0.0 versioning has been added to guarantee + compatibility between different versions. This is accomplished by chan= ging + serialization formats for certain classes and by using wire versioning= . By + wire versioning, mean that the version used by a client and server wil= l 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 betwe= en + 1.4.x release and 2.0.0, which are listed in the release notes. \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap14.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - Known issues + Getting the JBossRemoting source and building = - All of the known issues and road map can be found on our bug - tracking system, Jira, at - - http://jira.jboss.com/jira/secure/BrowseProject.jspa?id=3D10031 - (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 - ( - http://www.jboss.com/index.html?module=3Dbb&op=3Dviewforum&f= =3D222 - ). + 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: + + cvs -d:pserver:anonymous(a)anoncvs.forge.jboss.com:/cv= sroot/jboss checkout JBossRemoting + + To check out the source using a committer user id, use the + following: + + cvs -d:ext:username(a)cvs.forge.jboss.com:/cvsroot/jbo= ss checkout JBossRemoting + + This should checkout the entire remoting project, including doc, + tests, libs, etc. + + See + + http://www.jboss.org/wiki/Wiki.jsp?page=3DCVSRepository for m= ore + information on how to access the JBoss CVS repository. + + The build process for JBossRemoting is based on a standard ant b= uild + file (build.xml). The version of ant that is supported is ant 1.6.2, b= ut + should work with earlier versions as there are no special ant features + being used. + + The main ant build targets are as follows: + + compile - compiles all the co= re + JBossRemoting classes. + + jars - creates the + jboss-remoting.jar file from the compiled classes + + dist.jars - creates the + subsystem jar files (jboss-remoting-core.jar, jboss-remoting-socket.ja= r, etc.) + from the compiled classes + = + javadoc - creates the javadoc= html + files for JBossRemoting + + tests.compile - compiles the + JBossRemoting test files + + tests.jars - creates the + jboss-remoting-tests.jar and jboss-remoting-loading-tests.jar + files. + + tests.quick - runs the functi= onal + unit tests for JBossRemoting. + + tests - runs all the tests for + JBossRemoting, including functional and performance tests for all the + different transports. + + clean - removes all the build + artifacts and directories. + + most - calls clean then jars + targets. + + dist - builds the full + JBossRemoting distribution including running the full test suite. + + dist.quick - builds the full + JBossRemoting distribution, but does not run the test suite. + + The root directory for all build output is the output directory. + Under this directory will be: + + classes - compiled core classes + + + etc - deployment and JMX XMBean xml files + + + lib - all the jars and war file produced by t= he + build + + tests - contains the compiled test classes and + test results + + For most development, the most target can be used. Please run the + tests.quick target before checking anything in to ensure that code cha= nges + did not break any previously functioning test. \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap16.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - - - Release Notes + + Future plans = - Important changes and differences in 2.2.0 release (from 2.0= .0 - release) + Full road map for JBossRemoting can be found at + http://jira.jboss.com/jira/browse/JBREM?report=3Dcom.atlassian.jira.pl= ugin.system.project:roadmap-panel + . = - - Asynchronous method for handling callbacks (JBREM-640) - - - Bidirectional transport (JBREM-650) - - - Local transport (JBREM-660) - - - Marshallers/Unmarshallers construct their preferred streams - (JBREM-692) - - - - Release Notes - JBoss Remoting - Version 2.2.0.GA (Bluto) - - ** Bug * [JBREM-721] - Fix memory leaks in bisocket transport and - LeasePinger - - * [JBREM-722] - BisocketClientInvoker should start pinging on cont= rol - connection without waiting for call to createsocket() - - * [JBREM-725] - NPE in BisocketServeInvoker::createControlConnecti= on - - - * [JBREM-726] - BisocketServerInvoker control connection creation - needs to be in loop - - ** Feature Request - - * [JBREM-705] - Separate the http invoker and web container - dependency - - * [JBREM-727] - Make Client's implicitly created Connectors access= ible - - - ** Task * [JBREM-634] - update doc on callbacks - - * [JBREM-724] - Update build.xml to create bisocket transport jars - - - Release Notes - JBoss Remoting - Version 2.2.0.Beta1 (Bluto) - - ** Bug * [JBREM-581] - can not do connection validation with ssl - transport (only impacts detection) - - * [JBREM-600] - - org.jboss.test.remoting.lease.multiplex.MultiplexLeaseTestCase fails - - * [JBREM-623] - need reset() call added back to - JavaSerializationManager.sendObject() method - - * [JBREM-642] - Socket.setReuseAddress() in MicroSocketClientInvok= er - invocation is ignored - - * [JBREM-648] - Client.disconnect without clearing ConnectionListe= ners - will cause NPEs - - * [JBREM-651] - Array class loading problem under jdk6 - - * [JBREM-654] - a NullPointerException occures and is not handled = in - SocketServerInvoker and MultiplexServerInvoker - - * [JBREM-655] - rename server thread when new socket connection co= mes - in - - * [JBREM-656] - Creating a client inside a ConnectionListener might - lead into Lease reference counting problems - - * [JBREM-658] - bug in oneway thread pool under heavy load - - * [JBREM-659] - Java 6 and ClassLoader.loadClass() - - * [JBREM-670] - Remove equals() and hashCode() from - org.jboss.remoting.transport.rmi.RemotingRMIClientSocketFactory. - - * [JBREM-671] - serlvet invoker no longer supports leasing - - * [JBREM-683] - ByValueInvocationTestCase is broken - - * [JBREM-685] - A server needs redundant information to detect a o= ne - way invocation - - * [JBREM-690] - Once the socket of a callback server timeouts, it - starts to silently discard traffic - - * [JBREM-697] - - Horg.jboss.remoting.transport.rmi.RemotingRMIClientSocketFactory.Compara= bleHolder - should use InetAddress for host. - - * [JBREM-700] - NPE in AbstractDetector - - * [JBREM-704] - BisocketServerInvoker inadvertently logs "got - listener: null" as INFO - - * [JBREM-708] - Correct org.jboss.remoting.Client.readExternal() - - - * [JBREM-711] - ChunkedTestCase and Chuncked2TestCase failing - - * [JBREM-712] - HTTPInvokerProxyTestCase failing - - * [JBREM-723] - BisocketClientInvoker.transport() needs to disting= uish - between push and pull callback connections - - ** Feature Request - - * [JBREM-525] - Automatically set HostnameVerifier in - HTTPSClientInvoker to allow all hosts if authorization is turned off. - - - * [JBREM-598] - add timeout config per client invocation - - * [JBREM-618] - Support CallbackPoller configuration. - - * [JBREM-640] - Implement an asynchronous method for handling - callbacks. - - * [JBREM-650] - Create bidirectional transport - - * [JBREM-657] - Implement versions of Client.removeListener() and - Client.disconnect() which do not write to a broken server. - - * [JBREM-660] - create local transport - - * [JBREM-664] - Fix misleading InvalidConfigurationException - - * [JBREM-692] - Let marshallers/unmarshallers construct their - preferred streams. - - * [JBREM-720] - Need to expose create method for TransporterClient - that passes load balancing policy - - ** Task - - * [JBREM-274] - add callback methods to the Client API - - * [JBREM-369] - For Connectors that support callbacks on SSL - connections, there should be a unified means of configuring SSLServerSoc= ket - and callback Client SSLSocket.s. - - * [JBREM-453] - Send the pre-release jar to the messaging team for - testing - - * [JBREM-614] - Client.invoke() should check isConnected(). - - * [JBREM-631] - Fix - org.jboss.test.remoting.transport.socket.connection.SocketConnectionChec= kTestCase - and SocketConnectionTestCase failures. - - * [JBREM-635] - Remove misleading error message from HTTPUnMarshal= ler. - - - * [JBREM-636] - Remove ServerInvokerCallbackHandler's dependence on - initial InvocationRequest for listerner id. - - * [JBREM-637] - add tomcat jar to component-info.xml for remoting - release - - * [JBREM-644] - Reduce unit test logging output. - - * [JBREM-647] - Initialize Client configuration map to empty HashM= ap. - - - * [JBREM-663] - Put org.jboss.remoting.LeasePinger on separate thr= ead. - - - * [JBREM-669] - Client.removeListener() should catch exception and - continue if invocation to server fails. - - * [JBREM-674] - add test case for client exiting correctly - - * [JBREM-693] - Make sure "bisocket" can fully replace "socket" as - Messaging's default transport - - * [JBREM-695] - RemotingRMIClientSocketFactory.createSocket() shou= ld - return a socket even if a RMIClientInvoker has not been registered. - - * [JBREM-702] - http.basic.password should allow for empty passwor= ds - - - * [JBREM-707] - Fix handling of OPTIONS invocations in CoyoteInvok= er - - - * [JBREM-709] - Fix occasional failures of - org.jboss.test.remoting.lease.socket.multiple.SocketLeaseTestCase - - * [JBREM-719] - Fix spelling of - ServerInvokerCallbackHandler.REMOTING_ACKNOWLEDGES_PUSH_CALLBACKS - - Release Notes - JBoss Remoting - Version 2.2.0.Alpha6 - - ** Bug * [JBREM-662] - Failed ClientInvoker not cleaned up properly - - - * [JBREM-673] - Use of java.util.Timer recently added and not set = to - daemon, so applications not exiting - - * [JBREM-683] - ByValueInvocationTestCase is broken - - ** Feature Request - - * [JBREM-678] - Sending an one-way invocation into a server invoker - that is not started should generate a warning in logs - - * [JBREM-679] - Add the possibility to obtain ConnectionValidator's - ping period from a Client - - * [JBREM-680] - An invocation into a "broken" client should throw a - subclass of IOException - - ** Task - - * [JBREM-676] - TimerTasks run by TimerUtil should have a chance to - clean up if TimerUtil.destroy() is called. - - Release Notes - JBoss Remoting - Version 2.2.0.Alpha5 - - ** Bug - - * [JBREM-666] - Broken or malicious clients can lock up the remoti= ng - server - - * [JBREM-667] - Worker thread names are confusing - - ** Feature Request - - * [JBREM-668] - jrunit should allow TRACE level logging - - Release Notes - JBoss Remoting - Version 2.2.0.Alpha4 - - ** Bug - - * [JBREM-649] - Concurrent exceptions on Lease when - connecting/disconnecting new Clients - - Release Notes - JBoss Remoting - Version 2.2.0.Alpha3 (Bluto) - - ** Bug - - * [JBREM-594] - invoker not torn down upon connector startup error - - - * [JBREM-596] - Lease stops working if the First Client using the = same - Locator is closed - - * [JBREM-602] - If LeasePeriod is not set and if enableLease=3D=3D= true - leasePeriod assumes negative value - - * [JBREM-610] - Prevent org.jboss.remoting.callback.CallbackPoller - from delivering callbacks out of order. - - * [JBREM-611] - Initializing Client.sessionId outside constructor - leads to java.lang.NoClassDefFoundError in certain circumstances - - * [JBREM-615] - If CallbackStore.add() is called twice quickly, - System.currentTimeMillis() might not change, leading to duplicate file - names. - - * [JBREM-616] - Deletion of callback files in getNext() is not - synchronized, allowing callbacks to be returned multiple times. - - * [JBREM-619] - In SocketServerInvoker.run() and - MultiplexServerInvoker().run, guarantee ServerSocketRefresh thread - terminates. - - * [JBREM-622] - InvokerLocator already exists for listener - - * [JBREM-625] - MicroSocketClientInvoker should decrement count of - used sockets when a socket is discarded. - - * [JBREM-629] - NPE in sending notification of lost client - - ** Feature Request - - * [JBREM-419] - Invokers Encryption - - * [JBREM-429] - Create JBossSerialization MarshalledValue more - optimized for RemoteCalls - - * [JBREM-548] - Support one way invocations with no response - - * [JBREM-597] - Allow access to underlying stream in marshaller wi= th - socket transport - - * [JBREM-604] - allow socket server invoker to accept third party - requests - - * [JBREM-605] - Inform a server side listener that a callback has = been - delivered. - - * [JBREM-607] - Add idle timeout setting for invoker threads - - * [JBREM-609] - Support nonserializable callbacks in CallbackStore - - - ** Task - - * [JBREM-562] - publish performance benchmarks - - * [JBREM-601] - Integrate http with messaging - - * [JBREM-612] - Verify push callback connection with multiplex - transport shares client to server connection. - - * [JBREM-613] - ServerInvoker.InvalidStateException should be a st= atic - class. - - * [JBREM-617] - CallbackPoller should have its own thread. - - * [JBREM-620] - If HTTPClientInvoker receives an Exception in an - InvocationRespose, it should throw it instead of creating a new Exceptio= n. - - - * [JBREM-621] - http transport should behave more like other - transports. - - * [JBREM-624] - Add JBoss EULA - - * [JBREM-627] - Fix - org.jboss.test.remoting.transport.multiplex.MultiplexInvokerShutdownTest= Case - failure. - - * [JBREM-630] - Fix client/server race in - org.jboss.test.remoting.transport.multiplex.LateClientShutdownTestCase. - - - * [JBREM-632] - Modify src/etc/log4j.xml to allow DEBUG level logg= ing - for org.jboss.remoting loggers in jrunit test cases. - - - - Release Notes - JBoss Remoting - Version 2.0.0.GA (Boon) - - ** Bug - - * [JBREM-568] - SSLSocketBuilderMBean does not have matching - getter/setter attribute types - - * [JBREM-569] - HTTP(S) proxy broken - - * [JBREM-576] - deadlock with socket invoker - - * [JBREM-579] - transporter does not handle reflection conversion = for - primitive types - - * [JBREM-580] - detection can not be used with ssl based - transports - - * [JBREM-586] - socket client invoker connection pooling not - bounded - - * [JBREM-590] - SSL client socket invoker does not use configurati= on - map for SSLSocketBuilder - - ** Feature Request - - * [JBREM-564] - Default client socket factory configured by a syst= em - property - - * [JBREM-575] - local client invoker should convert itself to remo= te - client invoker when being serialized - - ** Task - - * [JBREM-570] - Change log in ConnectionValidator to be debug inst= ead - of warn when not able to ping server - - * [JBREM-571] - fix/cleanup doc - - * [JBREM-574] - Write SSL info for virtual sockets and server sock= ets - in toString() - - * [JBREM-578] - add spring remoting to performance benchmark - tests - - * [JBREM-582] - remove System.out.println and printStackTrace - calls - - * [JBREM-583] - Fix ConcurrentModificationException in - MultiplexingManager.notifySocketsOfException() - - * [JBREM-584] - Get - org.jboss.test.remoting.performance.spring.rmi.SpringRMIPerformanceTestC= ase - to run with multiple clients and callback handlers - - * [JBREM-587] - - ClientConfigurationCallbackConnectorTestCase(jboss_serialization) - failure. - - * [JBREM-593] - Synchronize client and server in - org.jboss.test.remoting.transport.multiplex.LateClientShutdownTestCase - - - - Release Notes - JBoss Remoting - Version 2.0.0.CR1 (Boon) - - ** Bug - - * [JBREM-303] - - org.jboss.test.remoting.transport.multiplex.BasicSocketTestCase(jboss_se= rialization) - failure - - * [JBREM-387] - classloading problem - using wrong classloader - - * [JBREM-468] - No connection possible after an illegitimate - attempt - - * [JBREM-484] - AbstractDetector.checkInvokerServer() is probably - broken - - * [JBREM-494] - ClientDisconnectedException does not have serial - version UID - - * [JBREM-495] - classes that do not have serial version UID - - * [JBREM-500] - ServerThread never dies - - * [JBREM-502] - not getting REMOVED notification from registry for - intra-VM detection - - * [JBREM-503] - NPE in abstract detector - - * [JBREM-506] - StreamHandler throws index out of bounds - exception - - * [JBREM-508] - serialization exception with mustang - - * [JBREM-519] - StreamServer never shuts down the server - - * [JBREM-526] - TimeUtil not using daemon thread - - * [JBREM-528] - ConcurrentModificationException when checking for = dead - servers (AbstractDetector) - - * [JBREM-530] - Detection heartbeat requires small timeout (for de= ad - server detection) - - * [JBREM-534] - multiplex client cannot re-connect to server after= it - has died and then been re-started - - * [JBREM-537] - - org.jboss.test.remoting.transport.rmi.ssl.handshake.RMIInvokerTestCase(j= ava_serialization) - - failing - - * [JBREM-541] - null pointer when receiving detection message - - * [JBREM-545] - setting of the bind address within MulticastDetect= or - not working - - * [JBREM-546] - InvokerLocator.equals is broken - - * [JBREM-552] - cannot init cause of ClassCastException - - * [JBREM-553] - deadlock when disconnecting - - * [JBREM-556] - versioning tests failing - - * [JBREM-561] - http chuncked test cases failing under jdk 1.5 - - ** Feature Request - - * [JBREM-427] - SSL Connection: load a new keystore at runtime - - * [JBREM-430] - transporter needs to be customizable - - * [JBREM-461] - Better documentation for sslmultiplex - - * [JBREM-491] - need to implement using ssl client mode for push - callbacks for all transports - - * [JBREM-492] - would like an API to indicate if a transport requi= res - SSL configuration - - * [JBREM-499] - need indication if invoker is secured by ssl - - * [JBREM-501] - give descriptive names to threads - - * [JBREM-504] - some synch blocks in AbstractDetector could - change - - * [JBREM-520] - Organize configuring of ServerSocketFactory's and - callback SocketFactory's. - - * [JBREM-527] - Allow user to pass Connector to be used for stream - server - - * [JBREM-532] - need synchronous call from detector client to get = all - remoting servers on network - - * [JBREM-539] - add sslservlet procotol - - * [JBREM-544] - http client invoker (for http, https, servlet, and - sslservlet) needs to handle exceptions in same manner as other transport - implementations - - ** Task - - * [JBREM-21] - Add stress tests - - * [JBREM-218] - investigate why jrunit report on cruisecontrol - inaccurate - - * [JBREM-311] - need required library matrix - - * [JBREM-320] - optimize pass by value within remoting - - * [JBREM-321] - performance tuning - - * [JBREM-368] - Configure SSLSockets and SSLServerSockets used in - callbacks to be in server mode and client mode, respectively. - - * [JBREM-383] - Document new versioning for remoting - - * [JBREM-384] - correct manifest to comply with new standard - - * [JBREM-390] - finish multiplex - - * [JBREM-412] - Remoting Guide lacks left margin - - * [JBREM-423] - document how remoting identity works and how to - configure - - * [JBREM-428] - add the samples/transporter/multiple/ to the - distribution build (think may be there by default) and update the - docs - - * [JBREM-434] - fix configuration data within document (socketTime= out - should be timeout) - - * [JBREM-435] - break out remoting jars (serialization) - - * [JBREM-442] - need full doc on how socket invoker works (connect= ion - pooling, etc.) - - * [JBREM-447] - convert static transporter factory methods into - constructor calls - - * [JBREM-452] - Send the pre-release jar to the messaging team for - testing - - * [JBREM-454] - cache socket wrapper classes - - * [JBREM-477] - remove Client.setInvoker() and Client.getInvoker() - methods - - * [JBREM-487] - Eliminate possible synchronization problem in - InvokerRegistry - - * [JBREM-490] - consolidate the remoting security related - classes - - * [JBREM-493] - Update version of jboss serialization being - used - - * [JBREM-496] - restructure service providers for remoting - - * [JBREM-497] - change InvokerLocator to respect hostname over ip - address - - * [JBREM-498] - change logging on cleaning up failed detection - - * [JBREM-507] - need to make configuration properties - consistent - - * [JBREM-509] - Fix call to super() in ServerInvoker's two argument - constructor. - - * [JBREM-511] - Allow HTTPSClientInvoker to create a HostnameVerif= ier - from classname. - - * [JBREM-513] - Create SSL version of RMI transport. - - * [JBREM-514] - Fix potential NullPointerException in - SSLSocketClientInvoker.createSocket(). - - * [JBREM-516] - add very simple transporter sample - - * [JBREM-517] - HTTPServerInvoker needs to be deprecated - - * [JBREM-523] - connection pool on socket client invoker needs to = be - bound - - * [JBREM-524] - Clean up MicrosocketClientInvoker code - - * [JBREM-529] - Need to be able to reuse socket connections after = move - to TIME_WAIT state - - * [JBREM-533] - remove external http GET test - - * [JBREM-535] - add config to force use of remote invoker instead = of - local - - * [JBREM-536] - turn off host verification when doing push callback - from server using same ssl config as server - - * [JBREM-538] - update remoting dist build to break out transports - into individual jars - - * [JBREM-540] - need to make servlet-invoker.war part of remoting - distribution - - * [JBREM-542] - change how remoting servlet finds servlet - invoker - - * [JBREM-543] - fix servlet invoker error handling to be more like - that of the http invoker - - * [JBREM-547] - need test case for exposing multiple interfaces for - transporter server target pojo - - * [JBREM-551] - - org.jboss.test.remoting.transport.multiplex.MultiplexInvokerTestCase(jav= a_serialization) - failure - - * [JBREM-555] - fix connection validator to not require extra thre= ad - to execute ping every time - - * [JBREM-558] - Break master.xml documentation into chapter - files - - * [JBREM-559] - update doc for 2.0.0.CR1 release - - * [JBREM-560] - InvokerGroupTestCase(java_serialization) - failure - - * [JBREM-563] - Multiplex - ClientConfigurationCallbackConnectorTestCase(jboss_serialization) - failure - - - - Release Notes - JBoss Remoting - Version 2.0.0.Beta2 (Boon) - - ** Bug - - * [JBREM-304] - - org.jboss.test.remoting.transport.multiplex.MultiplexInvokerTestCase(jav= a_serialization) - fails - - * [JBREM-371] - HTTPClientInvoker does not pass an ObjectOutputStr= eam - to the marshaller - - * [JBREM-405] - NPE when calling stop() twice on - MulticastDetector - - * [JBREM-406] - StringIndexOutOfBoundsException in - InvokerLocator - - * [JBREM-408] - client lease updates broken on server side - - * [JBREM-409] - Invocations fail when the pool exhausts and under - heavy load - - * [JBREM-414] - JNDI detection failing - - * [JBREM-418] - ObjectInputStreamWithClassLoader can't handle - primitives - - * [JBREM-426] - keyStorePath and keyStorePassword being printed to - standard out - - * [JBREM-432] - TransporterClient missing serialVersionUID - - * [JBREM-440] - CallbackStore.getNext() won't necessarily get the - oldest one - - * [JBREM-441] - DefaultCallbackErrorHandler.setConfig needs to avo= id - NPE - - * [JBREM-449] - Failure Information lost in - RemotingSSLSocketFactory - - * [JBREM-450] - ClassNotFoundException for class array type during - deserialization - - * [JBREM-464] - ssl socket invoker not using ssl server socket - factory - - * [JBREM-467] - NPE when calling - Client.removeConnectionListener() - - * [JBREM-470] - javax.net.ssl.SSLException: No available certifica= te - corresponds to the SSL cipher suites - - * [JBREM-472] - Misspelled serialization type generates obscure - NPE - - * [JBREM-479] - ClientConfigurationMapTestCase failure - - * [JBREM-482] - client invoker configuration lost after first time - invoker is created - - ** Feature Request - - * [JBREM-312] - make TransporterClient so can be sent over network= as - dynamic proxy - - * [JBREM-363] - make callbacks easier with richer API for register= ing - for callbacks - - * [JBREM-411] - Add chunked streaming support to the HTTP - invoker - - * [JBREM-413] - Transporter server should allow multiple pojo - targets - - * [JBREM-422] - Add plugable load balancing policy to transporter - client - - * [JBREM-425] - Add support for setting the HTTP invoker content - encoding that is accepted - - * [JBREM-431] - transporter server should automatically expose all - interfaces implemented as subsystems - - * [JBREM-439] - StreamInvocationHandler.handleStream should throw - Throwable for consistency - - * [JBREM-469] - Enable HTTP polling - - * [JBREM-471] - need better InvokerLocator.equals() - implementation - - * [JBREM-481] - Changing StringUtilBuffer creation on - JBossSerialization - - ** Task - - * [JBREM-299] - MultiplexInvokerTestCase failure - - * [JBREM-314] - need org.jboss.test.pooled.test.SSLSocketsUnitTest= Case - for remoting - - * [JBREM-328] - change lease ping to be HEAD instead of POST for h= ttp - transport - - * [JBREM-362] - convert Connector to be standard mbean instead of - xmbean - - * [JBREM-365] - set default user agent header in http client - invoker - - * [JBREM-366] - clean up client invoker tracking within - InvokerRegistry - - * [JBREM-367] - set live server socket factory on Connector - - * [JBREM-370] - add changes from 1.4.1 release to master.xml - doc - - * [JBREM-377] - need to convert ConnectionValidator to use - TimerQueue - - * [JBREM-379] - need to update jboss-serialization jar being - used - - * [JBREM-380] - change ConnectionValidator to only notify once of - failure - - * [JBREM-382] - disable lease ping for local invoker - - * [JBREM-415] - sync bug fixes with pooled invoker and socket - invoker - - * [JBREM-420] - JNDI Detector should not need a connector when run= ning - in client mode - - * [JBREM-421] - remote stream handler api inconsistent with regular - handler - - * [JBREM-436] - Extend MultiplexingInputStream with readInt() to a= void - creating a MultiplexingDataInputStream in VirtualSocket.connect() and - elsewhere. - - * [JBREM-437] - Eliminate "verify connect" phase from virtual sock= et - connection protocol. - - * [JBREM-443] - add HandshakeCompletedListener support to ssl - multiplex - - * [JBREM-451] - Send the pre-release jar to the messaging team for - testing - - * [JBREM-455] - checking of socket connection is not really - needed - - * [JBREM-456] - block callback handling when callback store - full - - * [JBREM-460] - createSocket() in SSLSocketClientInvoker and - SSLMultiplexClientInvoker should not assume SocketFactory has been - created. - - * [JBREM-465] - property setting on the client from locator parame= ters - and config map - - * [JBREM-476] - make externalization of Client match original inst= ance - state - - * [JBREM-478] - fix local client invoker handling of disconnected - server invokers - - * [JBREM-483] - remove LocalLeaseTestCase - - * [JBREM-485] - use the ClientInvokerHolder to contain the referen= ce - counting instead of having to use clientInvokerCounter - - * [JBREM-486] - Fix ConcurrentModificationException in - org.jboss.test.remoting.transport.mock.MockServerInvocationHandler - - - - Release Notes - JBoss Remoting - Version 2.0.0.Beta1 - - ** Bug - - * [JBREM-372] - memory leak on server side leasing - - * [JBREM-376] - problem versioning with not using connection - checking - - * [JBREM-378] - client connection checking not working - - ** Feature Request - - * [JBREM-340] - Strong version compatibility guarantee - - ** Task - - * [JBREM-374] - single thread the leasing timer - - - - Release Notes - JBoss Remoting - Version 1.4.4.GA - - ** Bug - - * [JBREM-426] - keyStorePath and keyStorePassword being printed to - standard out - - - - Release Notes - JBoss Remoting - Version 1.4.3.GA - - ** Bug - - * [JBREM-418] - ObjectInputStreamWithClassLoader can't handle - primitives - - - - Release Notes - JBoss Remoting - Version 1.4.2 final - - ** Feature Request - - * [JBREM-429] - Create JBossSerialization MarshalledValue more - optimized for RemoteCalls - - - - Release Notes - JBoss Remoting - Version 1.4.1 final - - ** Feature Request - - * [JBREM-310] - Ability to turn connection checking off - - * [JBREM-325] - move IMarshalledValue from jboss-commons to - jboss-remoting.jar - - ** Bug - - * [JBREM-313] - client lease does not work if client and server in - same VM (using local invoker) - - * [JBREM-317] - HTTPClientInvoker conect sends gratuitous POST - - * [JBREM-341] - Client ping interval must be lease than lease - period - - * [JBREM-343] - Exceptions on connection closing - - * [JBREM-345] - problem using client address and port - - * [JBREM-346] - fix ConcurrentModificationException in cleanup of - MultiplexServerInvoker - - * [JBREM-350] - ConcurrentModificationException in - InvokerRegistry - - * [JBREM-361] - Race condition in invoking on Client - - ** Task - - * [JBREM-2] - sample-bindings.xml does not have entry for - remoting - - * [JBREM-220] - clean up remoting wiki - - * [JBREM-316] - Maintain tomcat originated code under the ASF - license. - - * [JBREM-319] - ability to inject socket factory by classname or - instance in all remoting transports - - * [JBREM-323] - client lease config changes - - * [JBREM-329] - create global transport config for timeout - - * [JBREM-330] - create socket server factory based off of - configuration properties - - * [JBREM-335] - Client.invoke() should pass configuration map to - InvokerRegistry.createClientInvoker(). - - * [JBREM-336] - InvokerRegistry doesn't purge InvokerLocators from - static Set registeredLocators. - - * [JBREM-337] - PortUtil.findFreePort() should return ports only - between 1024 and 65535. - - * [JBREM-342] - Thread usage for timers and lease functionality - - * [JBREM-354] - ServerInvokerCallbackHandler should make its subsy= stem - accessible. - - * [JBREM-356] - ServerInvoker should destroy its callback - handlers. - - * [JBREM-359] - MultiplexInvokerConfigTestCase should execute - MultiplexInvokerConfigTestServer instead of - MultiplexInvokerTestServer. - - - - Release Notes - JBoss Remoting - Version 1.4.0 final - - ** Feature Request - - * [JBREM-91] - UIL2 type transport (duplex calling of same - socket) - - * [JBREM-117] - clean up callback client after several failures - delivering callbacks - - * [JBREM-138] - HTTP/Servlet invokers require content length to be - set - - * [JBREM-229] - Remove dependency on ThreadLocal for - SerializationManagers and pluggable serialization - - * [JBREM-233] - Server side exception listeners for client - connections - - * [JBREM-257] - Append client stack trace to thrown remote - exception - - * [JBREM-261] - Integration with IMarshalledValue from - JBossCommons - - * [JBREM-278] - remoting detection needs ability to accept detecti= on - of server invoker running locally - - * [JBREM-280] - no way to add path to invoker uri when using compl= ex - configuration - - ** Bug - - * [JBREM-41] - problem using localhost/127.0.0.1 - - * [JBREM-115] - http server invoker does not wait to finish proces= sing - on stop - - * [JBREM-223] - Broken Pipe if client don't do any calls before the - timeout value - - * [JBREM-224] - java.net.SocketTimeoutException when socket timeou= t on - the keep alive - - * [JBREM-231] - bug in invoker locator when there are no params - (NPE) - - * [JBREM-234] - StreamCorruptedException in DTM testcase - - * [JBREM-240] - TestUtil does not always give free port for - server - - * [JBREM-243] - socket client invoker sharing pooled - connections - - * [JBREM-250] - InvokerLocator doesn't support URL in IPv6 format = (ex: - socket://3000::117:5400/) - - * [JBREM-251] - transporter passes method signature based on concr= ete - object and not the parameter type - - * [JBREM-256] - NullPointer in MarshallerLoaderHandler.java:69 - - * [JBREM-259] - Unmarshalling of server response is not using call= er's - classloader - - * [JBREM-271] - http client invoker needs to explicitly set the - content type if not provided - - * [JBREM-277] - error shutting down coyote invoker when using APR - protocol - - * [JBREM-281] - getting random port for connectors is not - reliable - - * [JBREM-282] - ServletServerInvoker not working with depployed for - use as ejb invoker - - * [JBREM-286] - Socket server does not clean up server threads on - shutdown - - * [JBREM-289] - PortUtil only checking for free ports on - localhost - - ** Task - - * [JBREM-7] - Add more tests for local invoker - - * [JBREM-121] - improve connection failure callback - - * [JBREM-126] - add tests for client vs. server address - bindings - - * [JBREM-195] - Performance optimization - - * [JBREM-199] - remoting clients required to include - servlet-api.jar - - * [JBREM-207] - clean up build file - - * [JBREM-214] - multiplex performance tests getting out of memory - error - - * [JBREM-215] - re-write http transport/handler documentation - - * [JBREM-216] - Need to add new samples to example build in - distro - - * [JBREM-217] - create samples documentation - - * [JBREM-219] - move remoting site to jboss labs - - * [JBREM-226] - Release JBoss Remoting 1.4.0 final - - * [JBREM-230] - create interface for marshallers to implement for - swapping out serialization impl - - * [JBREM-235] - add new header to source files - - * [JBREM-239] - Update the LGPL headers - - * [JBREM-242] - Subclass multiplex invoker from socket invoker. - - * [JBREM-249] - http invoker (tomcat connector) documentation - - * [JBREM-253] - Convert http server invoker implementation to use - tomcat connector and protocols - - * [JBREM-255] - HTTPClientInvoker not setting response code or - message - - * [JBREM-275] - fix package error in examle-service.xml - - * [JBREM-276] - transporter does not throw original exception from - server implementation - - * [JBREM-279] - socket server invoker spits out error messages on - shutdown when is not needed - - * [JBREM-287] - need to complete javadoc for all user - classes/interfaces - - * [JBREM-288] - update example-service.xml with new - configurations - - ** Reactor Event - - * [JBREM-241] - Refactor SocketServerInvoker so that can be subcla= ssed - by MultiplexServerInvoker - - - - Release Notes - JBoss Remoting - Version 1.4.0 beta - - - - ** Feature Request - - * [JBREM-28] - Marshaller for non serializable objects - - * [JBREM-40] - Compression marshaller/unmarshaller - - * [JBREM-120] - config for using hostname in locator url instead of - ip - - * [JBREM-140] - can not set response headers from invocation - handlers - - * [JBREM-148] - support pluggable object serialization packages - - * [JBREM-175] - Remove Dependencies to Server Classes from - UnifiedInvoker - - * [JBREM-180] - add plugable serialization - - * [JBREM-187] - Better HTTP 1.1 stack support for HTTP invoker - - * [JBREM-201] - Remove dependency from JBossSerialization - - - - ** Bug - - * [JBREM-127] - RMI Invoker will not bind to specified address - - * [JBREM-192] - distro contains samples in src and examples - directory - - * [JBREM-193] - HTTPClientInvoker doesn't call getErrorStream() on - HttpURLConnection when an error response code is returned - - * [JBREM-194] - multiplex performance tests hang - - * [JBREM-202] - getUnmarshaller always calls Class.forName operati= on - for creating Unmarshallers - - * [JBREM-203] - rmi server invoker hangs if custom unmarshaller - - * [JBREM-205] - Spurious java.net.SocketException: Connection reset - error logging - - * [JBREM-210] - InvokerLocator should be insensitive to parameter - order - - - - ** Task - - * [JBREM-9] - Fix performance tests - - * [JBREM-33] - Add GET support within HTTP server invoker - - * [JBREM-145] - convert user guide from MS word doc to docbook - - * [JBREM-182] - Socket timeout too short (and better error - message) - - * [JBREM-183] - keep alive support for http invoker - - * [JBREM-196] - reducde the number of retries for socket client - invoker - - * [JBREM-204] - create complex remoting example using dynamic prox= y to - endpoint - - * [JBREM-212] - create transporter implementation - - * [JBREM-213] - allow config of ignoring https host validation (ss= l) - via metadata - - - - - - ** Patch - - * [JBREM-152] - NullPointerException in SocketServerInvoker.stop()= at - line 185. - - * [JBREM-153] - LocalClientInvoker's outlive their useful lifetime, - causing anomalous behavior - - - - Release Notes - JBoss Remoting - Version 1.2.1 final - - ** Feature Request - - * [JBREM-161] - Upgrade JRunit to Beta 2 - - ** Bug - - * [JBREM-147] - Invalid reuse of target location - - * [JBREM-163] - NPE in Mutlicast Detector - - * [JBREM-164] - HTTP Invoker unable to send large amounts of - data - - * [JBREM-176] - Correct inheritance structure for detectors - - * [JBREM-177] - configuration attribute spelled incorrectly in - ServerInvokerMBean - - * [JBREM-178] - SocketServerInvoker hanging on Linux - - * [JBREM-179] - socket timeout not being set properly - - ** Task - - * [JBREM-156] - Better exception handling within socket server - invoker - - * [JBREM-158] - Clean up test cases - - * [JBREM-162] - add version to the remoting jar - - Release Notes - JBoss Remoting - Version 1.2.0 final - - ** Feature Request - - * [JBREM-8] - Ability to stream files via remoting - - * [JBREM-22] - Manipulation of the client proxy interceptor - stack - - * [JBREM-24] - Allow for specific network interface bindings - - * [JBREM-27] - Support for HTTP/HTTPS proxy - - * [JBREM-35] - Servlet Invoker - counterpart to HTTP Invoker (runs - within web container) - - * [JBREM-43] - custom socket factories - - * [JBREM-46] - Connection failure callback - - * [JBREM-87] - Add handler metadata to detection messages - - * [JBREM-93] - Callback handler returning a generic Object - - * [JBREM-94] - callback server specific implementation - - * [JBREM-109] - Add support for JaasSecurityDomain within SSL - support - - * [JBREM-122] - need log4j.xml in examples - - ** Bug - - * [JBREM-58] - Bug with multiple callback handler registered with = same - server - - * [JBREM-64] - Need MarshalFactory to produce new instance per get - request - - * [JBREM-84] - Duplicate Connector shutdown using same server - invoker - - * [JBREM-92] - in-VM push callbacks don't work - - * [JBREM-97] - Won't compile under JDK 1.5 - - * [JBREM-108] - can not set bind address and port for rmi and - http(s) - - * [JBREM-114] - getting callbacks for a callback handler always - returns null - - * [JBREM-125] - can not configure transport, port, or host for the - stream server - - * [JBREM-131] - invoker registry not update if server invoker chan= ges - locator - - * [JBREM-134] - can not remove callback listeners from multiple - callback servers - - * [JBREM-137] - Invalid RemoteClientInvoker reference maintained by - InvokerRegistry after invoker disconnect() - - * [JBREM-141] - bug connecting client invoker when client detects = that - previously used one is disconnected - - * [JBREM-143] - NetworkRegistry should not be required for detecto= r to - run on server side - - ** Task - - * [JBREM-11] - Create seperate JBoss Remoting module in CVS - - * [JBREM-20] - break out remoting into two seperate projects - - * [JBREM-34] - Need to add configuration properties for HTTP server - invoker - - * [JBREM-39] - start connector on new thread - - * [JBREM-55] - Clean up Callback implementation - - * [JBREM-57] - Remove use of InvokerRequest in favor of Callback - object - - * [JBREM-62] - update UnifiedInvoker to use remote marshall - loading - - * [JBREM-67] - Add ability to set ThreadPool via configuration - - * [JBREM-98] - remove isDebugEnabled() within code as is now - depricated - - * [JBREM-101] - Fix serialization versioning between releases of - remoting - - * [JBREM-104] - Release JBossRemoting 1.1.0 - - * [JBREM-110] - create jboss-remoting-client.jar - - * [JBREM-113] - Convert remote tests to use JRunit instead of - distributed test framework - - * [JBREM-123] - update detection samples - - * [JBREM-128] - standardize address and port binding configuration= for - all transports - - * [JBREM-130] - updated wiki for checkout and build - - * [JBREM-132] - write test case for JBREM-131 - - * [JBREM-133] - Document use of Client (as a session object) - - * [JBREM-135] - Remove ClientInvokerAdapter - - ** Reactor Event - - * [JBREM-65] - move callback specific classes into new callback - package - - * [JBREM-111] - pass socket's output/inputstream directly to - marshaller/unmarshaller - - Release Notes - JBoss Remoting - Version 1.0.2 final - - ** Bug - - * [JBREM-36] - performance tests fail for http transports - - * [JBREM-66] - Race condition on startup - - * [JBREM-82] - Bad warning in Connector. - - * [JBREM-88] - HTTP invoker only binds to localhost - - * [JBREM-89] - HTTPUnMarshaller finishing read early - - * [JBREM-90] - HTTP header values not being picked up on the http - invoker server - - ** Task - - * [JBREM-70] - Clean up build.xml. Fix .classpath and .project for - eclipse - - * [JBREM-83] - Updated Invocation marshalling to support standard - payloads - - Release Notes - JBoss Remoting - Version 1.0.1 final - - ** Feature Request - - * [JBREM-54] - Need access to HTTP response headers - - ** Bug - - * [JBREM-1] - Thread.currentThread().getContextClassLoader() is - wrong - - * [JBREM-31] - Exception handling in http server invoker - - * [JBREM-32] - HTTP Invoker - check for threading issues - - * [JBREM-50] - Need ability to set socket timeout on socket client - invoker - - * [JBREM-59] - Pull callback collection is unbounded - possible Ou= t of - Memory - - * [JBREM-60] - Incorrect usage of debug level logging - - * [JBREM-61] - Possible RMI exception semantic regression - - ** Task - - * [JBREM-15] - merge UnifiedInvoker from remoting branch - - * [JBREM-30] - Better integration for registering invokers with - MBeanServe - - * [JBREM-37] - backport to 4.0 branch before 1.0.1 final - release - - * [JBREM-56] - Add Callback object instead of using - InvokerRequest - - ** Reactor Event - - * [JBREM-51] - defining marshaller on remoting client - - - - Release Notes - JBoss Remoting - Version 1.0.1 beta - - - - ** Bug - - * [JBREM-19] - Try to reconnect on connection failure within socket - invoker - - * [JBREM-25] - Deadlock in InvokerRegistry - - - - ** Feature Request - - * [JBREM-12] - Support for call by value - - * [JBREM-26] - Ability to use MBeans as handlers - - - - ** Task - - * [JBREM-3] - Fix Asyn invokers - currently not operable - - * [JBREM-4] - Added test for throwing exception on server side - - * [JBREM-5] - Socket invokers needs to be fixed - - * [JBREM-16] - Finish HTTP Invoker - - * [JBREM-17] - Add CannotConnectException to all transports - - * [JBREM-18] - Backport remoting from HEAD to 4.0 branch - - - - - - ** Reactor Event - - * [JBREM-23] - Refactor Connector so can configure transports - - * [JBREM-29] - Over load invoke() method in Client so metadata not - required - - - \ No newline at end of file + If you have questions, comments, bugs, fixes, contributions, or + flames, please post them to the JBoss Remoting users forum + ( + http://www.jboss.com/index.html?module=3Dbb&op=3Dviewforum&f= =3D222 + ). You can also find more information about JBoss Remoting on = our + + wiki ( + http://www.jboss.org/wiki/Wiki.jsp?page=3DRemoting ). The wik= i will + usually contain the latest updates to doc and features that did not ma= ke it + into the previous release. + \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap3.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ = new InvokerLocator("http://localhost:1234/services/uri:Test"= ).isSameEndpoint(new InvokerLocator("http://127.0.0.1:1234")) return= s false = + N.B. As of version 2.4, + InvokerLocator uses the class + java.net.URI, rather than its original ad hoc par= sing + 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 configu= re + InvokerLocator to use the original parsing code by + calling the static method + org.jboss.remoting.InvokerLocator.setUseLegacyParsing(). + + = org.jboss.remoting.transport.Connector - is an = MBean that loads a particular ServerInvoker implementation for a given transpo= rt Modified: remoting2/branches/2.x/docs/guide/en/chap4.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ jboss-remoting-rmi.jar - cont= ains all the classes needed for the rmi and sslrmi transports to function a= s a client and a server. - - jboss-remoting-multiplex.jar - - 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. = jboss-remoting-bisocket.jar - contains all the classes needed for the bisocket and sslbisocket trans= ports @@ -131,11 +126,13 @@ = HTTP server: jboss-remoting-http.jar, tomcat-coyote.jar, tomcat-util.jar, - commons-logging-api.jar, tomcat-http.jar + tomcat-http.jar, commons-logging-api.jar; alternatively, the tomcat = jars + can be replaced by jbossweb.jar = - Note: need tomcat-apr.jar and tcnative-1.dll/tcnative-1.so on - system path if want to use APR based tomcat connector - + 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 + = HTTP client: jboss-remoting-http-client.jar = @@ -149,9 +146,6 @@ RMI server and client: jboss-remoting-rmi.jar = - Multiplex server and client: - jboss-remoting-socket.jar, jboss-remoting-multiplex.jar - JBoss serialization: jboss-serialization.jar, trove.jar Modified: remoting2/branches/2.x/docs/guide/en/chap5.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ Configuration = - 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 servi= ce - 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. - + This covers the configuration for JBoss Remoting discovery, connec= tors, + 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 distributio= n that + shows full examples of all the remoting configurations. In the presence = of the + JBoss Microcontainer, Remoting servers may be configured by the injectio= n of + an org.jboss.remoting.ServerConfiguration object + specified in an *-beans.xml file. + =
General transport configuration @@ -48,7 +50,8 @@ file and use it to configure MBeans such as Connectors. = -
+
+ = Programmatic configuration. = The simplest way to configure a Connector @@ -184,14 +187,54 @@ = An example of this option in use can be found in org.jboss.test.remoting.configuration.SocketClientConfi= gurationTestCase. -
= + A fifth option, which exists primarily to support the inject= ion of + POJOs in the presence of the JBoss Microcontainer, is to pass an + org.jboss.remoting.ServerConfiguration obje= ct to + the Connector.setServerConfiguration() me= thod. + The following fragment duplicates the behavior of the first and se= cond + examples above. + = + + HashMap config =3D new HashMap(); + config.put(ServerInvoker.TIMEOUT, 120000); + Connector connector =3D new Connector(config); + = + // Create ServerConfiguration object for socket transport + ServerConfiguration serverConfig =3D new ServerConfiguration(= "socket"); + = + // Add invokerLocatorParameters (applicable to client and ser= ver) + Map locatorConfig =3D new HashMap(); + locatorConfig.put("serverBindAddress", "test.somedomain.com"); + locatorConfig.put("serverBindPort", "8084"); + serverConfig.setInvokerLocatorParameters(locatorConfig); + = + // Add serverParameters (applicable to server) + Map serverParameters =3D new HashMap(); + locatorConfig.put("clientLeasePeriod", "10000"); + serverConfig.setServerParameters(serverParameters); + = + // Add invocation handlers + Map handlers =3D new HashMap(); + handlers.put("mock", "org.jboss.remoting.transport.mock.Sampl= eInvocationHandler"); + serverConfig.setInvocationHandlers(handlers); + + connector.setServerConfiguration(serverConfig); + connector.create(); + connector.start(); + + = + For more information about ServerConfiguration, + see the section "Declarative configuration: POJOs". + = +
+ =
- Declarative configuration + Declarative configuration: MBeans = - The configuration option discussed at the end of the previous - section, passing an XML document to the - Connector, works in conjunction with the + One configuration option discussed in Section , passing an XML = document + to the Connector, 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 invoker 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 wit= h a name attribute specifying the configuration property name and then= the value. An isParam attribute can also be added to indi= cate @@ -314,6 +357,96 @@
=
+ Declarative configuration: POJOs + + The last configuration option discussed in Section , passing an + org.jboss.remoting.ServerConfiguration obje= ct to + the Connector.setServerConfiguration() me= thod, + 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 th= e form + "*-beans.xml". + = + A ServerConfiguration object holds fo= ur components: + + + + transport (supplied by constructor) + + + invokerLocatorParameters: this is a map of all parameter= names + and values that will go into the + org.jboss.remoting.InvokerLocator + + + serverParameters: this is a map of parameter names and v= alues + that will be used by the server but will not go into the + InvokerLocator + + + invocationHandlers: this is a map of invocation handlers= . The key + is the subsystem, or comma separated list of subsystems. + + + = + An sample remoting-beans.xml file which duplicates the examp= le in the + previous sections is: + = + + <?xml version=3D"1.0" encoding=3D"UTF-8"?> + <deployment xmlns=3D"urn:jboss:bean-deployer:2.0"> + = + <bean name=3D"remoting:invocationHandler" class=3D"org.jbo= ss.remoting.transport.mock.SampleInvocationHandler"/> + = + <bean name=3D"remoting:serverConfiguration" class=3D"org.j= boss.remoting.ServerConfiguration"> + <constructor> + <parameter>socket</parameter> + </constructor> + <property name=3D"invokerLocatorParameters"> + <map keyClass=3D"java.lang.String" valueClass=3D"jav= a.lang.String"> + <entry> + <key>serverBindAddress</key> + <value>test.somedomain.com</value> + </entry> + <entry> + <key>serverBindPort</key> + <value>8084</value> + </entry> + </map> + </property> + <property name=3D"serverParameters"> + <map keyClass=3D"java.lang.String" valueClass=3D"jav= a.lang.String"> + <entry> + <key>clientLeasePeriod</key> + <value>10000</value> + </entry> + </map> + </property> + <property name=3D"invocationHandlers"> + <map keyClass=3D"java.lang.String" valueClass=3D"org= .jboss.remoting.ServerInvocationHandler"> + <entry> + <key>mock</key> + <value><inject bean=3D"remoting:invocati= onHandler"/></value> + </entry> + </map> + </property> + </bean> + = + <bean name=3D"remoting:connector" class=3D"org.jboss.remot= ing.transport.Connector"> + <property name=3D"serverConfiguration"><inject be= an=3D"remoting:serverConfiguration"/></property> + </bean> + = + </deployment> + + = + For more information about using the JBoss Microcontainer, s= ee + + http://www.jboss.org/jbossmc/. + +
+ = +
Callback client configuration = @@ -392,7 +525,7 @@ is covered in . = 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 Client and a SocketFactory is passed to it by way of a set= ter @@ -418,7 +551,7 @@ after that method has been called.
- + =
Handlers = @@ -807,14 +940,268 @@
=
- Transports (Invokers) + Transports (Invokers) = - This section covers configuration issues for each of the transpo= rts, - beginning with a set of properties that apply to all transports. The - material in a later section in this chapter, , also applies to all - transports. + This section covers configuration issues for each of the transp= orts, + beginning with material that applies to all transports. The + material in a later section in this chapter, , also applies to all + transports. + = +
+ Features introduced in Remoting version 2.4 = + A number of transport independent features are introduced in Re= moting + version 2.4. + = +
+ Multihome servers + = + Before version 2.4, a Remoting server could bind either to a= specific IP address, e.g., = + + = + socket://192.168.0.2:6500 + = + or to all IP addresses on a given host,= e.g., + = + socket://0.0.0.0:6500 + = + 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 e= xample, + 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. + = + It would be convenient to be able to create an In= vokerLocator + that looks something like: + = + socket://10.32.4.2&192.168.4.2:6500 + = + but, unfortunately, that violates the URI syntax. Instead, a= special + placeholder, "multihome", is used in the host position, and the ac= tual host + addresses are given in the query component, e.g., + = + socket://multihome/?homes=3D10.32.4.2:6500!192.168= .4.2:6500 + = + An abbreviated syntax allows factoring out the bind port: + = + socket://multihome:6500/?homes=3D10.32.4.2!192.168= .4.2 + = + The value in the port position is treated as a default value= which can be + overriden in the "homes" parameter: + = + socket://multihome:6500/?homes=3D10.32.4.2!192.168= .4.2:6501 + = + binds to 10.32.4.2:6500 and 192.168.4.2:6501. + = + 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: + = + socket://multihome/?homes=3D10.32.4.2:6500!192.168= .4.2:6501&connecthomes=3D10.32.42.2:7500!192.168.42.2:7501 + = + 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. + = + 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: + = + = + <mbean code=3D"org.jboss.remoting.transport.Connector" + name=3D"jboss.remoting:service=3DConnector,transport=3DSock= et" + display-name=3D"Socket transport Connector"> + = + <attribute name=3D"Configuration"> + <config> + <invoker transport=3D"socket"> + + <attribute name=3D"homes"> + <home>10.32.4.2:6500</home> + <home>192.168.4.2:6501</home> + </attribute> + <attribute name=3D"connecthomes"> + <connecthome>10.32.42.2:7500</connectho= me> + <connecthome>192.168.42.2:7501</connect= home> + </attribute> + + </invoker> + <handlers> + ... + </handlers> + </config> + </attribute> + </mbean> + + = + The "serverBindPort" and "clientConnectPort" attributes may = be used to + give default values for bind ports and connect ports, respectively= . + = + The same server may be configured with the + org.jboss.remoting.ServerInvocation object = as well. + For example, = + + Connector connector =3D new Connector(); + = + // Create ServerConfiguration object for socket transport + ServerConfiguration serverConfig =3D new ServerConfiguration(= "socket"); + = + // Add invokerLocatorParameters (applicable to client and ser= ver) + Map locatorConfig =3D new HashMap(); + + 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"); + + serverConfig.setInvokerLocatorParameters(locatorConfig); + = + // Add invocation handlers + ... + = + connector.setServerConfiguration(serverConfig); + connector.create(); + connector.start(); + + = + is equivalent to the preceding MBean definition. + = + Note. The Strings "homes"= and + "connecthomes" are available as constants in the + InvokerLocator class: + InvokerLocator.HOMES_KEY and + InvokerLocator.CONNECT_HOMES_KEY. +
+ = +
+ Socket creation listeners + = + Sometimes it is useful to be able to grab a socket right af= ter it + has been created to either apply some additional configuration or + retrieve some information. It is possible to configure Remoting w= ith + instantions of the interface + org.jboss.remoting.socketfactory.SocketCreationListene= r + + = + + 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 IOE= xception; + } + + = + Socket creation listeners can be configured through the use= of + the keys + org.jboss.remoting.Remoting.SOCKET_CREATION_CLIENT_LISTENER= + (actual value "socketCreationClientListener") and + org.jboss.remoting.Remoting.SOCKET_CREATION_SERVER_LISTENER= + (actual value "socketCreationServerListener"), which install list= eners + for javax.net.SocketFactorys and + java.net.ServerSockets, respectively. The value asso= ciated + with these keys may be (1) an object that implements + SocketCreationListener or (2) a string that + names a class that implements + SocketCreationListener. In the latter case= , the + default constructor will be used to create an object of the desig= nated + class. +
+ = +
+ Making client IP address available to application + = + 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 ser= ver + and make it available to application code on both the client side= and + server side. On the client side, the method + org.jboss.remoting.Client.getAddressSeenByServer(), + with signature + = + + public InetAddress getAddressSeenByServer() throws Throwable + + = + 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 pay= load + map held by the + org.jboss.remoting.InvocationRequest. It m= ay be + retrieved by the + org.jboss.remoting.ServerInvocationHandler= as + follows: + = + + public Object invoke(InvocationRequest invocation throws Throw= able + { + ... + InetAddress address =3D invocation.getRequestPayload().get(= Remoting.CLIENT_ADDRESS); + ... + } + +
+ = + = +
+ Support for IPv6 IP addresses + = + org.jboss.remoting.InvokerLocator wi= ll now + accept IPv6 IP addresses. For example, + = + + socket://[::1]:3333/?timeout=3D10000 + socket://[::]:4444/?timeout=3D10000 + socket://[::ffff:127.0.0.1]:5555/?timeout=3D10000 + socket://[fe80::205:9aff:fe3c:7800%7]:6666/?timeout=3D10000 + socket://multihome/?homes=3D[fe80::205:9aff:fe3c:7800%7]:7777!= [fe80::214:22ff:feef:68bb%4]:8888 + +
+ = +
+ Delayed destruction of client invokers + = + Multiple clients may share a single client invoker. For ex= ample, in the code + = + + InvokerLocator locator =3D new InvokerLocator("socket://127.0.= 0.1:5555"); + Client client1 =3D new Client(locator); + Client client2 =3D new Client(locator); + + = + client1 and client2 will both + communicate with the server through a single + org.jboss.remoting.transport.socket.MicroSocketClientI= nvoker. + The number of Clients using a single client + invoker is tracked, and the invoker is destroyed when the count g= oes to + zero. It may be useful to delay the destruction of the invoker wh= en it + is known that another Client will want to = use it + in the near future. The delayed destruction of a client invoker m= ay be + achieved through the use of the key + Client.INVOKER_DESTRUCTION_DELAY (actual value + "invokerDestructionDelay"). For example, + = + + InvokerLocator locator =3D new InvokerLocator("socket://127.0.= 0.1:5555/?invokerDestructionDelay=3D5000"); + Client client =3D new Client(locator); + client.connect(); + ... + client.disconnect(); + + = + will cause client to delay the destruction of = its + client invoker (assuming client is the only user), b= y 5000 + milliseconds. Of course, "invokerDestructionDelay" may be passed = to the + Client by way of a configuration map, as + well. + = +
+
+ =
Server Invokers = @@ -944,161 +1331,52 @@
=
- Socket Invoker + Socket transport = - 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. - - timeout - 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). - - backlog - The preferred num= ber 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 v= alue - 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. - - numAcceptThreads - The numb= er of - threads that exist for accepting client connections. The default is - 1. - - maxPoolSize - The number of - server threads for processing client. The default is 300. - - serverSocketClass - specifi= es the - fully qualified class name for the custom SocketWrapper implementati= on - to use on the server. - - socket.check_connection - - 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 ser= ver - and then back from the server. This config needs to be set on both - client and server to work. This if false by default. - - idleTimeout - indicates the - number of seconds a pooled server thread can be idle (meaning time s= ince - last invocations request processed) before it should be cleaned up a= nd - 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 t= he - case was previously enabled. The default value for this property is - -1. - - Configurations affecting the Socket invoker - client - - There are some configurations which will impact the socket inv= oker - client. These will be communicated to the client invoker via paramet= ers - in the Locator URI. These configurations can not be changed during - runtime, so can only be set up upon initial configuration of the soc= ket - invoker on the server side. The following is a list of these and the= ir - effects. - - enableTcpNoDelay - can be e= ither - true or false and will indicate if client socket should have TCP_NOD= ELAY - turned on or off. TCP_NODELAY is for a specific purpose; to disable = the - Nagle buffering algorithm. It should only be set for applications th= at - send frequent small bursts of information without getting an immedia= te - response; where timely delivery of data is required (the canonical - example is mouse movements). The default is false. - - timeout - The socket timeout - value passed to the Socket.setSoTimeout() method. The default on the - client side is 1800000 (or 30 minutes). - - clientMaxPoolSize - the cli= ent - side maximum number of active socket connections. This basically equ= ates - to the maximum number of concurrent client calls that can be made fr= om - the socket client invoker. The default is 50. - - numberOfRetries - number of - retries to get a socket from the pool. This basically equates to num= ber - 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 SocketExcep= tion - saying how long it waited for socket connection from pool). The defa= ult - is 30 (MAX_RETRIES) - - numberOfCallRetries - numbe= r of - retries for making invocation. This is unrelated to numberOfRetries = in - that when this comes into play is after it has already received a cl= ient - 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 (wh= ich - defaults to 3) is. However, when reaches numberOfCallsRetries - 2, w= ill - 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. - - clientSocketClass - specifi= es the - fully qualified class name for the custom SocketWrapper implementati= on - 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. - - socket.check_connection - - 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 ser= ver - and then back from the server. This config needs to be set on both - client and server to work. This if false by default. - - 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: - - - socket://test.somedomain.com:8084/?enableTcpNoDelay=3Dfalse&maxP= oolSize=3D30 - - - To reiterate, these client configurations can only be set with= in - the server side configuration and will not change during runtime. - + 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. + =
- How the Socket Invoker works + How the Socket transport works = - The Socket Invoker is one of the more complicated invokers - mainly because allows the highest degree of configuration. To bett= er - 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. + Server = - server - - When the socket server invoker is started, it will create on= e, - and only one, instance of java.net.ServerSocket. Upon being starte= d, + When the socket server invoker is started, it will create on= e, and + only one, instance of java.net.ServerSocket= for + each configured bind address. Typically there would exactly one + ServerSocket, but there would be more than = one + for a mltihome server with multiple bind addresses. Upon being sta= rted, it will also create and start a number of threads to be used for accepting incoming requests from the ServerSocket. These threads a= re called the accept threads and the number of them created is contro= lled - by the 'numAcceptThreads' property. When these accept threads are - started, they will call accept() on the ServerSocket and block unt= il - 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. - + by the "numAcceptThreads" property. If "numAcceptThreads" is set t= o "n" + (it defaults to 1), there will be "n" accept threads per + ServerSocket. When these accept threads are + started, they will call accept() on the ServerSocket and block unt= il the + ServerSocket receives a request from a client, where it will retur= n a + Socket back to the accept thread who called the accept() method. A= s soon + as this happens, the accept thread will try to pass off the Socket= to + another thread for processing. + = The threads that actually process the incoming request, refe= rred - 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 ha= nd - off the Socket for processing. If the pool does not contain any - available server threads and the max pool size has not been reache= d, a - new server thread will be created for processing. Otherwise, if the - max pool size has been reached, the accept thread will wait for on= e 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 t= he - Socket to a server thread for processing, it will loop back to - ServerSocket and call accept() on it again. This will continue unt= il - the socket server invoker is stopped. + to as server threads + (org.jboss.remoting.transport.socket.ServerThread), + are stored in a pool. The accept thread will try to retrieve the f= irst + available server thread from the pool and hand off the Socket for + processing. If the pool does not contain any available server thre= ads + and the max pool size has not been reached, a new server thread wi= ll 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 t= he + accept thread has been able to hand off the Socket to a server thr= ead + for processing, it will loop back to ServerSocket and call accept(= ) on + it again. This will continue until the socket server invoker is + stopped. = The server thread processing the request will be the thread = of execution through the unmarshalling of the data, calling on the se= rver @@ -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. = 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. + = + Note. As of Remoting vers= ion 2.4, + some changes have been made to + ServerThread. + = + + + Once a server thread has completed an invocation, it wi= ll 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 t= hread + pool does not necessarily indicate that it is busy: it might = just + be blocked in a InputStream.read(). + Therefore, when an accept thread needs a server thread and the + thread pool is empty, it will try to appropriate server threa= ds + 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 avail= able + 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 thr= eads + from bouncing around like that, the parameter + ServerThread.EVICTABILITY_TIMEOUT (actual value + "evictabilityTimeout) has been introduced. If less than that = period + has elapsed since the server thread has started waiting for t= he + next invocation, it will not allow itself to be pre-empted. <= /para> + + = + + Prior to version 2.4, if a server thread experienced a + java.net.SocketTimeoutException, it wo= uld + return itself to the thread pool and could not be reused unti= l a + new socket connection was created for it to use. In principle= , it + would be more efficient for the server thread simply to try a= gain + to read the next invocation. Unfortunately, + java.io.ObjectInputStream ceases to fu= nction + once it experiences a + SocketTimeoutException. The good news = is + that + org.jboss.serial.io.JBossObjectInputStream, + made available by the JBossSerialization project, does not su= ffer + from that problem. Therefore, when it experiences a + SocketTimeoutException, a server threa= d will + check whether it is using a + JBossObjectInputStream or not and act + accordingly. Just to allow for the possibility that an applic= ation + is using yet another version of + ObjectInputStream, the parameter + ServerThread.CONTINUE_AFTER_TIMEOUT (actual value + "continueAfterTimeout") allows the behavior following a + SocketTimeoutException to be configured + explicitly. + + = - client + Client = - 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 cr= eate - a new socket connection and use it for making the invocation. Then - when finished making invocation, will return the still active sock= et - 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 tryin= g to - get an available connection from the pool, waiting 1 second in bet= ween - 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. + When the socket client invoker makes its first invocation, i= t will + check to see if there is an available socket connection in its poo= l. + 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 po= ssible + for the number of socket connections to reach the maximum allowed = (which + is controlled by 'clientMaxPoolSize' property). At this point, whe= n the + next client invocation is made, it will wait up to 30 seconds, at = which + point it will throw an + org.jboss.remoting.InvocationFailureException. = Once the socket client invoker goes get an available socket connection from the pool, are not out of the woods yet. There is s= till @@ -1179,10 +1508,165 @@ occur is when have had a burst of client invocations and then a lo= ng period of inactivity.
+ = +
+ Configuration + = + The following configuration properties can be set at any tim= e, but + will not take effect until the socket invoker, on the server side,= is + stopped and restarted. + = + timeout - The socket time= out + value passed to the Socket.setSoTimeout() method. The default on t= he + server side is 60000 (one minute). If the timeout parameter is set= , its + value will also be passed to the client side (see below). + = + backlog - The preferred n= umber 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. + = + numAcceptThreads - The nu= mber of + threads that exist for accepting client connections. The default is + 1. + = + maxPoolSize - The number = of + server threads for processing client. The default is 300. + = + serverSocketClass - speci= fies the + fully qualified class name for the custom SocketWrapper implementa= tion + to use on the server. + = + socket.check_connection - + 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 s= erver + and then back from the server. This config needs to be set on both + client and server to work. This if false by default. + = + idleTimeout - indicates t= he + 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 les= s 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. + = + evictabilityTimeout - ind= icates + the number of milliseconds during which a server thread waiting fo= r the + next invocation will not be interruptible. + = + continueAfterTimeout - in= dicates + what a server thread should do after experiencing a + java.net.SocketTimeoutException. If set to + "true", the server thread will continue to wait for an invocation; + otherwise, it will return itself to the thread pool. + = + Configurations affecting the Socket invoker + client + = + There are some configurations which will impact the socket i= nvoker + client. They can be set in the InvokerLocator, an + MBean or bean XML configuration file, or can be passed in the + configuration map when the Client is + created. + = + enableTcpNoDelay - can be= either + true or false and will indicate if client socket should have TCP_N= ODELAY + turned on or off. TCP_NODELAY is for a specific purpose; to disabl= e the + Nagle buffering algorithm. It should only be set for applications = that + send frequent small bursts of information without getting an immed= iate + response; where timely delivery of data is required (the canonical + example is mouse movements). The default is false. + = + timeout - The socket time= out + value passed to the Socket.setSoTimeout() method. The default on t= he + client side is 1800000 (or 30 minutes). + = + clientMaxPoolSize - the c= lient + side maximum number of active socket connections. This basically e= quates + to the maximum number of concurrent client calls that can be made = from + the socket client invoker. The default is 50. + = + numberOfCallRetries - num= ber of + retries for making invocation. This is unrelated to numberOfRetrie= s 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 soc= ket + connection timed out while waiting within the pool. Since not doin= g a + connection check by default, will throw away the connection and tr= y 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 st= art + over by creating a new connection. If still fails, will throw + MarshalException with the cause being the original + SocketException. + = + clientSocketClass - speci= fies the + fully qualified class name for the custom SocketWrapper implementa= tion + to use on the client. Note, will need to make sure this is marked = as a + client parameter (using the 'isParam' attribute). Making this chan= ge + will not affect the marshaller/unmarshaller that is used, which ma= y also + be a requirement. + = + socket.check_connection - + 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 s= erver + and then back from the server. This config needs to be set on both + client and server to work. This if false by default. + = + 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: + = + + socket://test.somedomain.com:8084/?enableTcpNoDelay=3Dfalse&ma= xPoolSize=3D30 + + = + Note. As of Remoting vers= ion 2.4, + the following socket parameters, in addition to SO_TIMEOUT and + TCP_NODELAY, can be configured on the client client side: SO_KEEPA= LIVE, + OOBINLINE, SO_RCVBUF, SO_REUSEADDR, SO_SNDBUF, SO_LINGER, and "tra= ffic + class". They are configured by the following parameter keys: + = + keepAlive - sets socket p= arameter + SO_KEEPALIVE + = + oOBInline - sets socket p= arameter + OOBINLINE = + = + receiveBufferSize - sets = socket + parameter SO_RCVBUF = + = + reuseAddress - sets socket + parameter SO_REUSEADDR + = + sendBufferSize - sets soc= ket + parameter SO_SNDBUF + = + soLinger - sets socket pa= rameter + SO_LINGER + = + soLingerDuration - when s= ocket + parameter SO_LINGER is set to "true", sets linger duration + = + trafficClass - sets socket + traffic class + = + For more information about these parameters, see the + java.net.Socket javadoc ( + http://java.sun.com/j2se/1.4.2/docs/api/java/net/Socket.html) or + a book about the TCP protocol. +
+ =
=
- SSL Socket Invoker + SSL Socket transport = Supports all the configuration attributes as the Socket Invoke= r. The main difference is that the SSL Socket Invoker uses an @@ -1192,7 +1676,7 @@
=
- RMI Invoker + RMI transport = registryPort - 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 , then the user is responsibl= e for supplying a serializable socket factory. + = + Note. Prior to Remoting ver= sion + 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 marshal= ler + and unmarshaller in the server to client direction, as well. Moreove= r, + 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 ori= ginal + marshalling behavior by setting the parameter + org.jboss.remoting.transport.rmi.RMIServerInvoker.RMI_ONEWAY_M= ARSHALLING + (actual value "rmiOnewayMarshalling") to "true".
=
@@ -1227,50 +1723,57 @@
=
- HTTP Invoker + HTTP transport = - 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 availa= ble - for the Tomcat connectors, please refer to 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, a= nd + 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 informatio= n on + the configuration attributes available for the Tomcat connectors, pl= ease + refer to htt= p://tomcat.apache.org/tomcat-5.5-doc/config/http.html. - http://tomcat.apache.org/tomcat-5.5-doc/config/http.html - - 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). - + http://tomcat.apache.org/tomcat-5.5-doc/config/http.html + So for example, if wanted to set the maximum number of threads to be= used + to accept incoming http requests, would use the 'maxThreads' attribu= te. + The only exception when should use remoting configuration over the T= omcat + configuration is for attribute 'address' (use serverBindAddress inst= ead) + and attribute 'port' (use serverBindPort instead). + = Note: The http invoker no longer has the configuration attribu= tes 'maxNumThreadsHTTP' or 'HTTPThreadPool' as thread pooling is now han= dled within the Tomcat connectors, which does not expose external API for setting these. - + = + A feature introduced in Remoting version 2.4 is the ability to + configure HTTPClientInvoker to make multiple + attempts to complete an invocation. The feature is invoked by setting + parameter HTTPClientInvoker.NUMBER_OF_CALL_ATTEMPTS (ac= tual + value "numberOfCallAttempts") to the desired integer. The parameter = can be + configured in the InvokerLocator or in the + configuration map passed to the Client. The d= efault + value is 1. + = 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 org.apache.coyote.http11.Http11Protocol. However, it is possible to switch to use the - org.apache.coyote.http11.Http11AprProtocol protocol, wh= ich - is based on the Apache Portable Runtime (see org.apache.coyote.http11.Http11AprProtocol protocol, wh= ich is + based on the Apache Portable Runtime (see http://tomc= at.apache.org/tomcat-5.5-doc/apr.html - and http://apr.apache.org/ - 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 loade= d. - The APR native binaries can be found at http://tomcat.heanet.ie. - - Note: There is a bug with release 1.1.1 of APR where get an er= ror - upon shutting down (see JBREM-277 for more information). This does n= ot - impact anything while running, but is still an issue when shutting d= own - (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 versio= n of - tcnative-1.dll with the new one. - + and http://apr.apache.org/ 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 loade= d. The + JBossWeb native libraries, which include tcnative-1.dll/tcnative-1.s= o, may + be downloaded from http://www.jboss.org/jbossweb= /. + The Apache versions of the APR native binaries can be found at http://www.gtlib.gate= ch.edu/pub/apache. + = Client request headers = The HTTP Invoker allows for some of the properties to be passe= d as @@ -1293,10 +1796,48 @@ These request headers are set automatically when using a remot= ing client, but if using another client to send request to the HTTP serv= er invoker, may want to add these headers. + = + Response headers + = + If a request on the HTTP transport is made with the + org.jboss.remoting.Client method + = + + public Object invoke(Object param, Map metadata) throws Throwable + + = + then + org.jboss.remoting.transport.http.HTTPClientInvoker + returns the HTTP response headers in a map in metadata, associated w= ith + the key + org.jboss.remoting.transport.http.HTTPMetadataConstants.RESPON= SE_HEADERS + (actual value "ResponseHeaders"). For example, the response header "= Date" + can be retrieved as follows: + = + + Object payload =3D ... ; + HashMap metadata =3D new HashMap(); + client.invoke(payload, metadata); + Map responseHeaders =3D (Map) metadata.get(HTTPMetadataConstants.R= ESPONSE_HEADERS); + String date =3D (String) responseHeaders.get("Date"); + + = + CR/LF in HTTP transport + = + By default, the HTTP transport uses + org.jboss.remoting.marshal.http.HTTPMarshaller and + org.jboss.remoting.marshal.http.HTTPUnMarshaller to + marshal and unmarshal invocations and responses. Prior to Remoting v= ersion + 2.4, HTTPUnMarshaller stripped CR/LF characte= rs. As + of version 2.4, the default behavior remains the same, but it is pos= sible + to change the behavior, on the client and the server, by setting the + parameter HTTPUnMarshaller.PRESERVE_LINES (actual value + "preserveLines") to "true". + =
- + =
- HTTPS Invoker + HTTPS transport = Supports all the configuration attributes as the HTTP Invoker, plus the following: @@ -1436,7 +1977,7 @@
=
- Servlet Invoker + Servlet transport = The servlet invoker is a server invoker implementation that us= es 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 ma= ps to is changed, will need to change the value for the InvokerLocator = in the Connector configuration mentioned above. - - Issues - - One of the issues of using Servlet invoker is that the invocat= ion - handlers (those that implement ServerInvocationHandler) can not retu= rn - very much detail in regards to a web context. For example, the conte= nt - type used for the response is the same as that of the request. + = + Note. Prior to Remoting ver= sion + 2.4, + org.jboss.remoting.transport.servlet.ServletServerInvoker= + generated a single MBean ObjectName for representing + ServletServerInvokers as MBeans, which meant = that + an MBeanServer could be aware of only a single + ServletServerInvoker MBean. As of version 2.4= , that + restriction has been eliminated. + = + Note. Prior to Remoting ver= sion + 2.4, when + org.jboss.remoting.transport.servlet.web.ServerInvokerSer= vlet + retrieved an MBeanServer, it looked only for an MBeanServer whose de= fault + 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, ServerInvokerServlet will + retrieve the platform MBeanServer by calling + java.lang.management.ManagementFactory.getPlatformMBeanS= erver(). + In the absence of a configured default domain, + ServerInvokerServlet will still use "jboss" a= s the + default domain. + =
=
- SSL Servlet Invoker + SSL Servlet transport = The SSL Servlet Invoker is exactly the same as its parent, Ser= vlet 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 excepti= on 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 se= rver - 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. JBos= sAS, + Tomcat, Apache Web Server, etc.), the exception thrown will be org.jboss.test.remoting.transport.http.WebServerError. = 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 pass= ed - to the Client.invoke() method where they key is + server. Throwing an exception may be turned off with the parameter HTTPMetadataConstants.NO_THROW_ON_ERROR (actual text va= lue - 'NoThrowOnError') and a value of of type java.lang.String set to 'tr= ue'. - This will cause the http client invoker to not throw an exception, b= ut - 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. -
+ "NoThrowOnError") set to "true". This parameter may be passed in the + InvokerLocator or configuration map when the + org.jboss.remoting.Client is created, or it m= ay be + included in the metadata map passed to + = + + public Object invoke(Object param, Map metadata) throws Throwable; + + . + This will cause the http client invoker to not throw an except= ion, + 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.S= tring + (i.e. is error html), it will be wrapped in a WebServerError and ret= urned + as this type. The raw data from the web server can the be retrieved = by + getting the WebServerError's message. + = + Note. Prior to Remoting ver= sion + 2.4, the servlet transport returned a simple error message in the ev= ent 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 req= uested + by configuring the server with the parameter + org.jboss.remoting.transport.http.HTTPMetadataConstants.DONT_R= ETURN_EXCEPTION + (actual value "dont-return-exception") set to "true". + = +
= = =
- Multiplex Invoker + Multiplex transport = - The multiplex invoker is intended to replicate the functionali= ty - of the socket invoker with the added feature that it supports multip= le - 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 servi= ce - is made possible by the Multiplex subproject, which provides "virtua= l" - sockets and "virtual" server sockets. Please refer to the Multiplex - documentation at - -
- - http://labs.jboss.com/portal/jbossremoting/docs/index.html= -
- - for further details. - - In a typical multiplexed scenario a Client - on a client host, through a - MultiplexClientInvoker C, - could make synchronous method invocations to a - MultiplexServerInvoker on a server host, and = at - the same time (and over the same TCP connection) asynchronous push - callbacks could be made to a - MultiplexServerInvoker S= on - the client host. In this, the Prime - Scenario, which motivated the creation of the multiplex - invoker, C and S use two - different virtual sockets but share the same port and same actual - socket. We say that C and S - belong to the same invoker - group. - - 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: - - - - Establishing on the server an environment prerequisite for - creating multiplex connections - - - - Configuring the client for multiplexed method invocations = and - callbacks - - - - Shutting down invoker groups. - - - -
- Setting up the server - - There are two kinds of - MultiplexServerInvokers, master and virtual, corresponding to the two kinds of - virtual server sockets: MasterServerSocket = and - VirtualServerSocket. Briefly, the difference - between the two virtual server socket classes is that a - MasterServerSocket is derived from - java.net.ServerSocket and its - accept() method is implemented by way of = the - inherited method super.accept(). A - MasterServerSocket can accept connect reque= sts - from multiple machines. A VirtualServerSocket, - on the other hand, is based on an actual socket connected to anoth= er - actual socket on some host H, and consequentl= y a - VirtualServerSocket can accept connect requ= ests - only from H. - - Each multiplex connection depends on a pair of connected real - sockets, one on the client host and one on the server host, and th= is - connection is created when an actual socket contacts an actual ser= ver - socket. It follows that a multiplex connection begins with a - connection request to a MasterServerSocket. - Once the connection is established, it is possible to build up - virtual socket groups, consisti= ng of - virtual sockets (and at most one - VirtualServerSocket) revolving around the - actual socket at each end of the connection. Each virtual socket i= n a - socket group at one end is connected to a virtual socket in the so= cket - group at the other end. - - Master and virtual - MultiplexServerInvokers assume the - characteristics of their server sockets: - MasterServerSocket and - VirtualServerSocket, respectively. That is,= a - master MultiplexServerInvoker can accept - requests from any host, while a virtual - MultiplexServerInvoker can accept requests = only - from the particular host to which it has a multiplex connection. S= ince - a multiplex connection begins with a connection request to a - MasterServerSocket, it follows that the use= of - the multiplex invoker must begin with a connection request from the - client (made by either a MultiplexClientInvoker - or a virtual MultiplexServerInvoker: see be= low) - to a master MultiplexServerInvoker on the - server. The master MultiplexServerInvoker - responds by "cloning" itself (metaphorically, not necessarily thro= ugh - the use of clone()) into a virtual - MultiplexServerInvoker with the same parame= ters - and same set of invocation handlers but with a - VirtualServerSocket belonging to a new sock= et - group. In so doing the master - MultiplexServerInvoker builds up a server invoker farm of virtual - MultiplexServerInvokers, each in contact wi= th a - different MultiplexClientInvoker over a - distinct multiplex connection. The virtual - MultiplexServerInvokers do the actual work = of - responding to method invocation requests, sent by their correspond= ing - MultiplexClientInvokers through virtual soc= kets - in a socket group at the client end of a multiplex connection to - virtual sockets created by the - VirtualServerSocket in the socket group at = the - server end of the connection. Note that virtual - MultiplexServerInvokers share data structur= es - with the master, so that registering invocation handlers with the - master makes them available to the members of the farm. The member= s of - a master MultiplexServerInvoker's invoker f= arm - are accessible by way of the methods - -
- - - MultiplexServerInvoker.getServerInvokers()= - and - - - - MultiplexServerInvoker.getServerInvoker(In= etSocketAddress) - - -
- - the latter of which returns a virtual - MultiplexServerInvoker keyed on the address= to - which its VirtualServerSocket is connected. - When the master MultiplexServerInvoker shuts - down, its farm of virtual invokers shuts down as well - - There are two ways of constructing a virtual - MultiplexServerInvoker, one being the cloni= ng - method just discussed. It is also possible to construct one direct= ly. - Once a multiplex connection is established, a virtual - MultiplexServerInvoker can be created with a - VirtualServerSocket belonging to a socket g= roup - at one end of the connection. The - MultiplexServerInvoker constructor determin= es - whether to create a virtual or master invoker according to the - presence or absence of certain parameters, discussed below, that m= ay - be added to its InvokerLocator. Server rule= s 1 - through 3 described below result in the construction of a virtual - MultiplexServerInvoker, and server rule 4 (= the - absence of these parameters) results in the construction of a mast= er - MultiplexServerInvoker. - - Setting up the server, then, is simply a matter of starting a - master MultiplexServerInvoker with a simple - InvokerLocator, unadorned with any paramete= rs - specific to the multiplex invoker. As always, the server invoker is - not created directly but by way of a Connector, - as in the following: - -
- - Connector connector =3D new Connector(); - Connector.setInvokerLocator("multiplex://demo.jboss.com:8080"); - Connector.create() - Connector.start() - -
-
- -
- Setting up the client - - Before multiplex connections can be established, a master - MultiplexServerInvoker must be created as - described in the previous section. For example, the Prime Scenario - would begin with starting a master - MultiplexServerInvoker on the server host, - followed by starting, on the client host, a - MultiplexClientInvoker C - and a virtual MultiplexServerInvoker - S (in either order). The first to start initi= ates - a multiplex connection to the master - MultiplexServerInvoker and requests the - creation of a virtual MultiplexServerInvoker. - Note that it is crucial for C and - S to know that they are meant to share a - multiplex connection, i.e., that they are meant to belong to the s= ame - invoker group. Consider the following attempt to set up a shared - connection between hosts bluemonkey.acme.com and demo.jboss.com. - First, C is initialized on host - bluemonkey.acme.com with the InvokerLocator - 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 S is initialized with - InvokerLocator - multiplex://bluemonkey.acme.com:4444, but since it needs to bind to - port 4444, it is unable to share the existing connection. [Actuall= y, - the example is slightly deceptive, since - multiplex://bluemonkey.acme.com:4040 would result in the creation = of a - master MultiplexServerInvoker. But if it we= re - suitably extended with the parameters discussed below so that a - virtual MultiplexServerInvoker were created, - the virtual invoker would be unable to share the existing - connection.] - - So C and S 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 MultiplexClientInvoker - uses virtual sockets in its underlying virtual socket group, and a - MultiplexServerInvoker in an invoker group = has - a VirtualServerSocket that creates virtual - sockets in the underlying virtual socket group. - - C and S each get h= alf - of the information necessary to identify their invoker group direc= tly - from their respective InvokerLocators. In - particular, C gets the remote address and por= t, - and S gets the binding address and port. The - additional information may be provided through the use of invoker group parameters, which may be - communicated to C and S = in - one of two ways: - - - - they may be appended to the - InvokerLocator passed to the - Client which creates C - and/or to the InvokerLocator passed to = the - Connector which creates - S - - - - they may be stored in a configuration - Map which is passed to the - Client and/or - Connector. - - - - In either case, there are two ways in which the missing - information can be supplied to C and - S: - - - - The information can be provided explicitly by way of inv= oker - group parameters: - - - - multiplexBindHost and - multiplexBindPort parameters can be - passed to C, and - - - - multiplexConnectHost and - multiplexConnectPort parameters can be - passed to S. - - - - - - C and S can be - tied together by giving them the same multiplexId, supplied by invoker group - parameters: - - - - clientMultiplexId, for the - MultiplexClientInvoker, and - - - - serverMultiplexId, for the - MultiplexServerInvoker. - - - - Giving them matching multiplexIds tells them that they a= re - meant to belong to the same invoker group and that they should - provide the missing information to each other. - - - - The behavior of a starting - MultiplexClientInvoker C - is governed by the following four client - rules: - - - - If C has a - clientMultiplexId parameter, it will use = it - to attempt to find a MultiplexServerInvoker - S with a - serverMultiplexId 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 S was una= ble - to start because of insufficient information (server rule 3), = then - C will supply the missing information and - S will start. Note that in this situation - C will ignore any - multiplexBindHost and - multiplexBindPort parameters passed to - it. - - - - If C does not find a - MultiplexServerInvoker through a - multiplexId (either because it did not get a - clientMultiplexId parameter or because th= ere - is no MultiplexServerInvoker with a - matching multiplexId), but it does have - multiplexBindHost and - multiplexBindPort 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 MultiplexServerInvoker - that may come along later (see server rule 1). - - - - If C has a multiplexId and neither - finds a MultiplexServerInvoker with a - matching multiplexId nor has - multiplexBindHost and - multiplexBindPort parameters, then it will - not start, but it will advertise itself so that it may be found - later by a MultiplexServerInvoker (see - server rule 1). - - - - If C has neither - clientMultiplexId nor - multiplexBindHost and - multiplexBindPort parameters, it will cre= ate - or reuse a multiplex connection from an arbitrary local port to - the host and port given in its - InvokerLocator, and start. - - - - Similarly, the behavior of a starting - MultiplexServerInvoker S - is governed by the following four server - rules: - - - - If S has a - serverMultiplexId parameter, it will use = it - to attempt to find a MultiplexClientInvoker - C with a matching - clientMultiplexId. If it succeeds, it will - retrieve server host and port values, create a - VirtualServerSocket, create or reuse a - suitable multiplex connection to the server, and start. Moreov= er, - if C was unable to start due to insuffici= ent - information (client rule 3), then S will - supply the missing information and C will - start. Note that in this situation S will - ignore multiplexConnectHost and - multiplexConnectPort parameters, if any, = in - its InvokerLocator. - - - - If S does not find a - MultiplexClientInvoker through a - multiplexId (either because it did not get a - serverMultiplexId parameter or because th= ere - is no MultiplexClientInvoker with a - matching multiplexId), but it does have - multiplexConnectHost and - multiplexConnectPort parameters, then it = will - create a VirtualServerSocket, 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 MultiplexClientInvoker that - may come along later (see client rule 1). - - - - If S has a multiplexId and neither - finds a MultiplexClientInvoker with a - matching multiplexId nor has - multiplexConnectHost and - multiplexConnectPort parameters, then it = will - not start, but it will advertise itself so that it may be found - later by a MultiplexClientInvoker (see - client rule 1). - - - - If S has neither - serverMultiplexId nor - multiplexConnectHost and - multiplexConnectPort parameters, it will - create a MasterServerSocket bound to the - host and port in its InvokerLocator and - start. - - - -
- Notes - - - - Like server invokers, client invokers are not started - directly but are started indirectly through calls to - Client(InvokerLocator locator), such - as: - - - Client client =3D new Client("multiplex://demo.jboss.com:8080/= ?clientMultiplexId=3Did0"); - client.connect(); - - - N.B. For the multip= lex - invoker, it is important to call - Client.connect(). Otherwise, the la= st - MultiplexClientInvoker that leaves an - invoker group will not get a chance to shut the group - down. - - - - It should not be inferred that - MultiplexClientInvokers and - MultiplexServerInvokers belong to the - same invoker group only if they are - required to do so by invoker group parameters. In fact, if t= wo - Clients are created with the - InvokerLocator - 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 - force - MultiplexClientInvokers and - MultiplexServerInvokers to share a - connection. - - - - There are situations in which the method of passing - parameters by way of the configuration map is preferable to - appending them to an InvokerLocator. = One - of the functions of an InvokerLocator= is - to identify a server, and modifying the content of its - InvokerLocator may interfere with the - ability to locate the server. For example, one of the featur= es - of JBoss Remoting is the substitution of method calls for re= mote - invocations when it discovers that a server runs in the same= JVM - as the client. However, appending multiplex parameters to the - InvokerLocator 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. - - - - It is possible, and convenient, to set up a multiplexi= ng - scenario using no parameters other than - clientMultiplexId and - serverMultiplexId. Note, however, that = in - this case neither the Clients nor the - Connector will be fully initialized u= ntil - after both have been started. If the - Clients and the - Connector are to be started - independently, then the other parameters must be used. N.B. If a Client - depends on Connector in the same invo= ker - group to supply binding information, it is an error to call - methods such as Client.connect() and - Client.invoke() until the - Connector has been started. - - - - Clients and the optional - Connector may be created (and the - Connector started) in any order. - - -
-
- -
- Shutting down invoker groups. - - A virtual socket group will shut down, releasing a real sock= et - 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 agr= ees - to the proposed shut down. The second condition prevents a situati= on - in which a new virtual socket tries to join what it thinks is a vi= able - socket group at the same time that the peer socket group is shutti= ng - down. So for a virtual socket group to shut down, all members at b= oth - ends of the connection must be closed. - - The implication of this negotiated shutdown mechanism is tha= t as - long as the VirtualServerSocket used by a - virtual MultiplexServerInvoker 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 - MultiplexServerInvokers. - - There are three ways in which a virtual - MultiplexServerInvoker that belongs to a ma= ster - MultiplexServerInvoker's invoker farm can s= hut - down. - - When a master - MultiplexServerInvoker is closed, it - closes all of the virtual - MultiplexServerInvokers it - created. - - - - A virtual MultiplexServerInvoker - can be retrieved by calling either - MultiplexServerInvoker.getServerInvokers() - or - MultiplexServerInvoker.getServerInvoker(InetSock= etAddress) - on its master MultiplexServerInvoker = and - then closed directly. - - - - When the accept() method of i= ts - VirtualServerSocket times out, and wh= en - it detects that all multiplex invokers in the invoker group = at - the client end of the connection have shut down, a virtual - MultiplexServerInvoker will shut itse= lf - down. Note that when all members leave an invoker group, it = is - guaranteed not to be revived, i.e., no new members may - join. - - The third method insures that without any explic= it - intervention, closing all multiplex invokers on the client (by way= of - calling Client.disconnect() and - Connector.stop()) is guaranteed to result= in - the eventual release of resources. The timeout period may be adjus= ted - by setting the timeout parameter (see below). - Alternatively, the second method, in conjunction with the use of - MultiplexServerInvoker.isSafeToShutdown(), - which returns true on - MultiplexServerInvoker M if and - only if (1) M is not virtual, or (2) all of the multi= plex - invokers in the invoker group at the client end of M's - connection have shut down. For example, a thread could be dedicate= d to - looking for useless MultiplexServerInvokers= and - terminating them before their natural expiration through timing - out. -
- -
- Examples - - The following are examples of setting up a client for - multiplexed synchronous and asynchronous communication. They each - assume the existence of a master - MultiplexServerInvoker running on - demo.jboss.com:8080. - - For complete examples see the section . - - - - A MultiplexClientInvoker - C starts first: - - - String parameters =3D "multiplexBindHost=3Dlocalhost&multi= plexBindPort=3D7070&clientMultiplexId=3DdemoId1"; - String locatorURI =3D "multiplex://demo.jboss.com:8080/?" + pa= rameters; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - Client client =3D new Client(locator); - client.connect(); - - - and then it is found by a - MultiplexServerInvoker with a matching - multiplexId, which joins C's invoker group - and starts: - - - Connector connector =3D new Connector(); - String parameters =3D "serverMultiplexId=3DdemoId1"; - String locatorURI =3D "multiplex://localhost:7070/?" + paramet= ers; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - - - - - A MultiplexClientInvoker - C starts: - - - String parameters =3D "multiplexBindHost=3Dlocalhost&multi= plexBindPort=3D7070"; - String locatorURI =3D "multiplex://demo.jboss.com:8080/?" + pa= rameters; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - Client client =3D new Client(locator); - client.connect(); - - - and a MultiplexServerInvoker - S starts independently, joining - C's invoker group by virtue of having - matching local and remote addresses and ports: - - - Connector connector =3D new Connector(); - String parameters =3D "multiplexConnectHost=3Ddemo.jboss.com&a= mp;multiplexConnectPort=3D8080"; - String locatorURI =3D "multiplex://localhost:7070/?" + paramet= ers; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - - - - - A MultiplexClientInvoker - C is created but does not start: - - - String parameters =3D "clientMultiplexId=3DdemoId2"; - String locatorURI =3D "multiplex://demo.jboss.com:8080/?" + pa= rameters; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - Client client =3D new Client(locator); - - - and then a MultiplexServerInvoker - S is created with a matching multiplexId, - allowing both C and S to - start: - - - Connector connector =3D new Connector(); - String parameters =3D "serverMultiplexId=3DdemoId2"; - String locatorURI =3D "multiplex://localhost:7070/?" + paramet= ers; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - client.connect(); - - - Note the call to Client.connect() - after the call to - Connector.start(). - - - - A MultiplexClientInvoker - C starts in an invoker group based on a r= eal - socket bound to an arbitrary local port: - - - String locatorURI =3D "multiplex://demo.jboss.com:8080"; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - Client client =3D new Client(locator); - client.connect(); - - - and then a MultiplexServerInvoker - S starts independently: - - - Connector connector =3D new Connector(); - String locatorURI =3D "multiplex://localhost:7070"; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - connector.setInvokerLocator(locator.getLocatorURI()); - connector.create(); - connector.start(); - - - Note that S creates a - MasterServerSocket rather than a - VirtualServerSocket in this case and so - does not share a multiplex connection and does not belong to an - invoker group. - - - - This is example 1, rewritten so that the invoker group - parameters are passed by way of a configuration - Map instead of - InvokerLocators. A - MultiplexClientInvoker - C starts first: - - - String locatorURI =3D "multiplex://demo.jboss.com:8080"; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - Map configuration =3D new HashMap(); - configuration.put(MultiplexInvokerConstants.MULTIPLEX_BIND_HOS= T_KEY, "localhost"); - configuration.put(MultiplexInvokerConstants.MULTIPLEX_BIND_POR= T_KEY, "7070"); - configuration.put(MultiplexInvokerConstants.CLIENT_MULTIPLEX_I= D_KEY, "demoId1"); - Client client =3D new Client(locator, configuration); - client.connect(); - - - and then it is found by a - MultiplexServerInvoker with a matching - multiplexId, which joins C's invoker group - and starts: - - - String locatorURI =3D "multiplex://localhost:7070"; - InvokerLocator locator =3D new InvokerLocator(locatorURI); - Map configuration =3D new HashMap(); - configuration.put(MultiplexInvokerConstants.SERVER_MULTIPLEX_I= D_KEY, "demoId1"); - Connector connector =3D new Connector(locator.getLocatorURI(),= configuration); - connector.create(); - connector.start(); - - - -
- -
- Configuration properties - - There are four categories of configuration properties suppor= ted - by the multiplex invoker, the last three of which are specific to = the - multiplex invoker. Properties in categories 2 and 3 may be configu= red - by appending them to the server's locator URI. Properties in - categories 2, 3, and 4 may be configured by putting their values i= n a - configuration HashMap and passing the map t= o a - MultiplexServerInvoker and/or - MultiplexClientInvoker constructor, accordi= ng - to the category. Constants for the property names in categories 2,= 3, - and 4 are found in - org.jboss.remoting.transport.multiplex.Multiplex. - Note that some of them are also found in the older - org.jboss.remoting.transport.multiplex.MultiplexInvoker= Constants, - but the use of that class is now deprecated. - - - - The following properties are managed by ancestor classes= of - MultiplexServerInvoker. See the discuss= ion - under SocketServerInvoker for more - information. - - socketTimeout - The s= ocket - timeout value passed to the - Socket.setSoTimeout() method and the - ServerSocket.setSoTimeout() method. T= he - default is 60000 (or 1 minute). - - numAcceptThreads - The - number of threads that exist for accepting client connections.= The - default is 1. - - - - The following properties are intended to be passed to a - virtual MultiplexServerInvoker to confi= gure - its multiplex connection. These properties are specific to the - multiplex invoker. - - multiplexConnectHost = - the - name or address of the host to which the multiplex connection - should be made. - - multiplexConnectPort = - the - port to which the multiplex connection should be made. - - serverMultiplexId - a - string that associates a - MultiplexServerInvoker with a - MultiplexClientInvoker with which it sh= ould - share a multiplex connection. - - multiplex.maxAcceptErrors - - Master and virtual MultiplexServerInvokers - keep a counter of errors experienced by their server socket, a= nd - they terminate when this maximum is exceeded. Note that - SSLHandshakeExceptions are excluded from - the count, since they could indicate a client rather than serv= er - error. - - - - The following properties are intended to be passed to a - virtual MultiplexClientInvoker to confi= gure - its multiplex connection. These properties are specific to the - multiplex invoker. - - multiplexBindHost - t= he - host name or address to which the local end of the multiplex - connection should be bound. - - multiplexBindPort - t= he - port to which the local end of the multiplex connection should= be - bound - - clientMultiplexId - a - string that associates a - MultiplexClientInvoker with a - MultiplexServerInvoker with which it sh= ould - share a multiplex connection. - - - - There is also a set of properties which are specific to = the - Multiplex subsystem internal classes. See the Multiplex - documentation at - -
- - http://labs.jboss.com/portal/jbossremoting/docs/index.html -
- - for more information. - - -
+ As of Remoting version 2.4, the multiplex transport is depreca= ted + and will no longer be supported.
=
- SSL Multiplex Invoker + SSL Multiplex transport = - This transport is essentially identical to the Multiplex - transport, except that it will create SSL socket factories and server - socket factories by default. - - The twist to be found with the multiplex transport is that vir= tual - MultiplexServerInvokers use a - VirtualServerSocket, which is based on a clie= nt - rather than a server socket, and consequently they act like a client= in - some ways. In particular, a virtual - MultiplexServerInvoker will, in some cases, - attempt to connect to a remote master - MultiplexServerInvoker, for which it will nee= d an - actual client socket. All of the rules for configuring socket factor= ies - apply to the MultiplexServerInvoker, which ca= lls - the same method that client invokers use to get a socket factory. - Moreover, if necessary, it will look for a - ServerSocketFactoryMBean to get SSL informati= on - when configuring a socket factory. See section for more information. + As of Remoting version 2.4, the sslmultiplex transport is depr= ecated + and will no longer be supported.
=
- Bisocket invoker + Bisocket transport = The bisocket transport, like the @@ -2647,6 +2348,32 @@ BisocketServerInvoker uses it to govern t= he number of attempts it should make to create both ordinary and co= ntrol sockets. The default value is 10. + = + + SECONDARY_BIND_PORT (actual v= alue is + "secondaryBindPort"): The server side uses this parameter to det= ermine + the bind port for the secondary + ServerSocket. + = + + SECONDARY_BIND_PORTS (actual = value is + "secondaryBindPorts"): The server side uses this parameter to + determine the bind ports for the secondary + ServerSockets in a multihome server. + = + + SECONDARY_CONNECT_PORT (actua= l value + is "secondaryConnectPort"): The server side uses this parameter = to + determine the connect port used by the client side to connect to= the + secondary ServerSocket. + = + + SECONDARY_CONNECT_PORTS (actu= al value + is "secondaryConnectPorts"): The server side uses this parameter= to + determine the connect ports used by the client side to connect t= o the + secondary ServerSockets in a multihome + server. + =
=
@@ -2866,7 +2593,7 @@
=
- SSL Bisocket invoker + SSL Bisocket transport = The SSL bisocket transport has the same relation to the bisocket @@ -3034,21 +2761,23 @@ Callback overview = - Although this section covers callback configuration, it will be us= eful to begin - with a little general information about callbacks within Remoting.= In addition - to the ordinary remote method invocation model, in which invocatio= n 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 us= eful + to begin with a little general information about callbacks within + Remoting. In addition to the ordinary remote method invocation mod= el, 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. = There are two models for callbacks, push - callbacks and pull callbacks. - In the push model, the client registers a client side callback ser= ver with - the target server. When the target server has a callback to delive= r, it - will call on the callback server directly and send the callback me= ssage. - The other model, pull callbacks, allows the client to call on the = target - server to collect the callback messages waiting for it. + callbacks and pull + callbacks. In the push model, the client registers a cl= ient + side callback server with the target server. When the target serve= r has + a callback to deliver, it will call on the callback server directl= y and + send the callback message. The other model, pull callbacks, allows= the + client to call on the target server to collect the callback messag= es + waiting for it. =
@@ -3069,18 +2798,18 @@ = method of the application's - org.jboss.remoting.ServerInvocationHandler= . The - org.jboss.remoting.callback.InvokerCallbackHandler - parameter (actual type - org.jboss.remoting.callback.ServerInvokerCallbackHandl= er) - is the server side representation of the callback connection, - essentially a proxy for the client side - InvokerCallbackHandler passed to the - addListener() method. The - ServerInvocationHandler is free to do what= ever - it wants with the InvokerCallbackHandler, = but a - typical practice would be to keep a list of them and transmit each - generated callback to some or all of them. + org.jboss.remoting.ServerInvocationHandler. The + org.jboss.remoting.callback.InvokerCallbackHandler + parameter (actual type + org.jboss.remoting.callback.ServerInvokerCallbackHand= ler) + is the server side representation of the callback connection, + essentially a proxy for the client side + InvokerCallbackHandler passed to the + addListener() method. The + ServerInvocationHandler is free to do wha= tever + it wants with the InvokerCallbackHandler,= but a + typical practice would be to keep a list of them and transmit ea= ch + generated callback to some or all of them. = @@ -3422,10 +3151,10 @@ Registering callback handlers. = There are several ways in which callback handlers can be confi= gured. - The main distinction in type of callback setup is whether the callba= cks will - be push (asynchronous) or pull (synchronous) callbacks. + The main distinction in type of callback setup is whether the callba= cks + will be push (asynchronous) or pull (synchronous) callbacks. = -
+
Pull callbacks. = @@ -3468,6 +3197,43 @@ InvokerCallbackHandler, the two objects together identify a particular callback connection. + = + Note. As of Remoting vers= ion 2.4 + there are two versions of pull callbacks: non-blocking (original) = and + blocking (new). [The new version has been ported to Remoting relea= se + 2.2.2.GA, so it exists in later versions of the 2.2 family]. In the + original, non-blocking mode, a call to + Client.getCallbacks() will return more or l= ess + 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 blo= cking + mode eliminates the overhead of busy polling. Blocking and non-blo= cking + mode are configured on a per-invocation basis by setting + org.jboss.remoting.ServerInvoker.BLOCKING_MODE (actual + value "blockingMode") to either + ServerInvoker.BLOCKING (actual value "block= ing") + or ServerInvoker.NONBLOCKING (actual value + "nonblocking") in the metadata map passed to + = + + public List getCallbacks(InvokerCallbackHandler callbackHandler,= Map metadata) throws Throwable; + + = + in org.jboss.remoting.Client. The def= ault + value is ServerInvoker.NONBLOCKING. The blocking time= out value + may be configured in two ways: + = + + the Connector can be + configured with a default value; and + + a per-invocation timeout value can be configure= d with + the key ServerInvoker.BLOCKING_TIMEOUT in the meta= data + map passed to Client.getCallbacks(). + + + = + In the absence of any configured timeout, the default value = is 5000 ms. =
= @@ -3589,9 +3355,9 @@ Socket to a ServerSocket. There are currently three bidirectional transports: local (i.e., the client and server res= ide in - the same JVM), bisocket, and multiplex. When one of the second s= et of - addListener() 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 addListener() methods is + invoked for a bidirectional transport, it will create a callback Connector, even if serverToClient is set to false. The other option is to use any of the unidirectional transports (socket, http= , rmi) @@ -3664,17 +3430,30 @@ with only one callback connection. = + Note. As of Remoting vers= ion 2.4, + there are two versions of pull callbacks: non-blocking (original) = and + blocking (new). For more information, see . Since the + CallbackPoller uses pull callbacks, this + distinction is relevant to polled callbacks as well. The default + behavior of CallbackPoller is to use non-bl= ocking + mode, but blocking mode can be requested by using the key + ServerInvoker.BLOCKING_MODE set to + ServerInvoker.BLOCKING in the metadata map passed to + Client.addListener(). + = - There are six parameters that can be passed to - addListener() in the metadata - 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 a= re - defined as constants in the + There are nine parameters that can be passed to + Client.addListener() in the + metadata map which are specific to push callback + configuration. The first three apply to push callbacks and the l= atter + six apply to polled callbacks. For convenience, the keys related= to + push callbacks are defined as constants in the org.jboss.remoting.Client class, and the = keys related to polled callbacks are defined in the org.jboss.remoting.callback.CallbackPoller - class. + class (with the exception of + ServerInvoker.BLOCKING_MODE and ServerInvoker= .BLOCKING_TIMEOUT). = @@ -3727,12 +3506,58 @@ CallbackPoller to print statistics that= might be useful for configuring the other parameters.. + = + + MAX_ERROR_COUNT (actual val= ue is + "maxErrorCount"): determines the maximum number of errors that= may + be experienced during polling before + CallbackPoller will shut itself down. T= he + default value is "5". + = = + + SYNCHRONIZED_SHUTDOWN (actu= al value + is "doSynchronizedShutdown"): if set to "true", + CallbackPoller.stop() will wait for + Client.getCallbacks() 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". + + = + + BLOCKING_MODE (actual value= is + "blockingMode"): if set to ServerInvoker.BLOCKING + (actual value "blocking"), CallbackPoller + will do blocking polled callbacks, and if set to + ServerInvoker.NONBLOCKING (actual value "nonblock= ing"), + CallbackPoller will do non-blocking pol= led + callbacks. + + = + + BLOCKING_TIMEOUT (actual va= lue is + "blockingTimeout"): the value is used as the per-invocation ti= meout + + = Note that all of the elements in metadata will be p= assed to the callback Connector and appended to = its InvokerLocator. + = + Note. As of Remoting vers= ion 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 serve= r. + [This feature has been ported to Remoting release 2.2.2.GA, so it e= xists + in later versions of the 2.2 family]. The parameter is + org.jboss.remoting.callback.ServerInvokerCallbackHandler.CALL= BACK_TIMEOUT + (actual value "callbackTimeout"), and it should be used to configur= e the + Connector. In the absence of + ServerInvokerCallbackHandler.CALLBACK_TIMEOUT, the tim= eout + value configured for the Connector will be + used. + =
=
@@ -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. + = + Note. As of Remoting versio= n 2.4, + an + 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 t= he + connection for that particular client, then the + ServerInvokerCallbackHandler can be registere= d as a + org.jboss.remoting.ConnectionListener for that + lease. The default behavior is to do the registration, but the param= eter + org.jboss.remoting.ServerInvoker.REGISTER_CALLBACK_LISTENER + (actual value "registerCallbackListener") may be set to "false" to p= revent + registration. If leasing is enabled and registration is turned on, a + ServerInvokerCallbackHandler will shut itself= down upon being informed of a connection + failure. For more information about leasing, see .
= @@ -4078,7 +3920,7 @@ = 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 SSLServerSocketFactory, as determined by the transport. @@ -4225,7 +4067,7 @@ = 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 SSLSocketFactory, as determined by the transport. @@ -4349,7 +4191,7 @@ = 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 SSLServerSocketFactory, as determined by the transport. @@ -4426,7 +4268,7 @@ = 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 SSLSocketFactory, as determined by the transport. @@ -4465,21 +4307,6 @@ = - sslmultiplex: Whiche= ver of - SSLMultiplexClientInvoker or - SSLMultiplexServerInvoker first gets - sufficient bind and connect information to create a priming so= cket - (see the section on the multiplex invoker for a discussion of - priming sockets) passes the current - SocketFactory to be used to create the - actual socket that supports the multiplexed connection. This - happens during the call to either - Client.connect() or - Connector.create(). Once the actual - socket is created, no further configuration is possible - - - sslrmi: A SocketFactory is either created or configured for future creation during @@ -4702,7 +4529,7 @@ = The creation listener facility currently is supported by the follo= wing - transports: bisocket, sslbisocket, https, multiplex, sslmultiplex,= rmi, + transports: bisocket, sslbisocket, https, rmi, sslrmi, socket, and sslsocket. It is not supported by http because HttpURLConnection does not expose its socket factory (though HttpsURLConnection does). I= t is @@ -4716,7 +4543,7 @@ SSL transports = 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 for more informati= on on using the APR based transport. = - sslmultiplex - - The sslmultiplex server invoker inherits from the socket server - invoker a method with signature - - - public void setNewServerSocketFactory(ServerSocketFactory serv= erSocketFactory) - - - which supports dynamic replacement of server socket factories.= The - principal motivation for this facility is to be able to swap in a new - SSLServerSocketFactory configured with an upd= ated - keystore. - sslrmi = @@ -5437,7 +5250,7 @@ = -
+
Timeouts = @@ -5476,7 +5289,7 @@ Per invocation timeouts = - 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 previ= ously configured timeout value. The per invocation timeout is set by pas= sing @@ -5533,7 +5346,7 @@
=
- HTTP transport + HTTP and HTTPS transports = 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. T= he threads are drawn from a thread pool, which is configurable. A c= ustom thread pool may be set by calling the - HTTPClientInvoker method + HTTPClientInvoker method = @@ -5603,6 +5416,42 @@
=
+ RMI and SSLRMI transports + = + Connection timeouts are handled on the server side by passin= g the + configured timeout value to the + org.jboss.remoting.transport.rmi.RemotingRMIClientSocke= tFactory + and + org.jboss.remoting.transport.rmi.RemotingRMIServerSocke= tFactory + objects passed when the + org.jboss.remoting.transport.RMIServerInvoker is + exported by the + java.rmi.server.UnicastRemoteObject.exportObject() + method. + = + org.jboss.remoting.transport.rmi.RMIClientInvoker= + 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 + org.jboss.util.threadpool.BasicThreadPool, = which + may be configured with the following parameters, defined as consta= nts in + org.jboss.remoting.transport.rmi.RMIClientInvoker: + + = + + MAX_NUM_TIMEOUT_THREADS (actual= value + "maxNumTimeoutThreads"): the number of threads in the threadpool. = The + default value is 10. + = + + MAX_TIMEOUT_QUEUE_SIZE (actual = value + "maxTimeoutQueueSize"): the size of the thread pool queue, which h= olds + execution requests when all of the threads are in use. The default + value is 1024. + +
+ = +
Quick client disconnect = @@ -5638,6 +5487,231 @@ =
= + = +
+ Running with a security manager + = + As of version 2.4, Remoting is prepared to run in the presence = of an + installed java.lang.SecurityManager. In Java, + certain security sensitive system calls, e.g., + java.io.File.exists(), + java.lang.Class.getClassLoader(), and + java.lang.System.getProperty(), consult a + SecurityManager, if one has been installed, to + determine if the calling code has permission to execute the action + performed by the method. + = + 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 u= sing + trusted code for its own nefarious purposes. However, the same strate= gy + could prevent trusted code from accomplishing security sensitive acti= vities + without granting suitable permissions to any code that calls the trus= ted + code. The loophole that gets around this problem is the ability to wr= ap + security sensitive method calls in a "privileged block" which prevent= s the + JVM from proceeding up the stack. In other words, the code in the pri= vileged + block can employ its granted permissions even if the calling code doe= s not + have those same permissions. + = + More precisely, a privileged block consists of an + java.security.PrivilegedAction or + java.security.PrivilegedExceptionAction object + passed to a = + java.security.AccessController.doPrivileged() + call. As of version 2.4, Remoting wraps all security sensitive method= calls + appropriately. For example, the call + java.net.ServerSocket.accept() has been replaced by + org.jboss.remoting.utility.SecurityUtility.accept(): + = + + static public Socket accept(final ServerSocket ss) throws IOExcepti= on + { + if (skipAccessControl) + { + return ss.accept(); + } + = + try + { + return (Socket)AccessController.doPrivileged( new Privileged= ExceptionAction() + { + public Object run() throws Exception + { + return ss.accept(); + } + }); + } + catch (PrivilegedActionException e) + { + throw (IOException) e.getCause(); + } + } + + = + Note that the + AccessController.doPrivileged() call, with i= ts + creation of a PrivilegedExceptionAction object= , is + made only if the static variable + SecurityUtility.skipAccessControl is set to false, which= is + the case if + = + + + no SecurityManager is installed, o= r + + + the system property org.jboss.remoting.Remoting.SKI= P_ACCESS_CONTROL + is set to "false". + + + = + The Remoting code needs quite a few permissions since it intera= cts + extensively with the network, file system, etc., and there are a coup= le of + strategies for granting these permissions. The standard + java.lang.SecurityManager can read permission + information from an XML file, as described in + http://java.sun.com/j2se/1.5.0/docs/guide/security/PolicyFiles.html, + and one straightforward strategy is to treat Remoting as highly trust= ed + code and to give it all possible permissions in a file that looks + like + = + + grant codeBase "file:${remoting.dir}/jboss-remoting.jar" + { + permission java.security.AllPermission; + }; + + = + 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 distribu= tion + 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: + = + + + It may be necessary to change the java.io.FilePermission + permissions, according to the configuration of certain files. + + If Remoting is configured to operate with one or more MBe= ans in + place of POJOs, it might be necessary to grant additional + MBeanPermissions. + + + Some facilities always use MBeans. The MBean permissions = given + in remoting.security.policy.core may be restricted to particular + ObjectNames. + + + Some permission may be eliminated, according to which Rem= oting + facilities are used. + + + + Other than changes made according to items 1 and 2, it should n= ot be + necessary to grant any additional permissions. + = + The etc directory also contains the policy files + remoting.security.policy.tests, remoting.security.policy.tests.marsha= l, 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. + = +
+ = +
+ Wire version + = + Remoting has, on occasion, changed the format of communications= over + the network, which could make it difficult for one version of Remotin= g to + communcate with another version. However, it is possible to configure= newer + versions to communicate with older versions. + = + There are currently three wire versions: + = + + + org.jboss.remoting.Version.VERSION_1 (actual value 1= ), + used by Remoting versions 1.2 and 1.4; + + = + + org.jboss.remoting.Version.VERSION_2 (actual value 2= ), + used by Remoting version 2.0; and + + = + + org.jboss.remoting.Version.VERSION_22 (actual value = 22), + used by Remoting versions 2.2 and 2.4. + + + = + 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: + = + + + set system property + org.jboss.remoting.Version.PRE_2_0_COMPATIBLE (act= ual + value "jboss.remoting.pre_2_0_compatible") to "true"; + + = + + set system property + org.jboss.remoting.Version.REMOTING_VERSION_TO_USE + (actual value "jboss.remoting.version") to + org.jboss.remoting.Version.VERSION_1 (actual versi= on + "1"); + + = + + configure the org.jboss.remoting.Client + or org.jboss.remoting.transport.Connector with + the parameter + org.jboss.remoting.Remoting.REMOTING_VERSION (actu= al + value "remotingVersion") set to + org.jboss.remoting.Version.VERSION_1 (actual versi= on + "1"). + + + = + Similarly, versions 2.2 and 2.4 can be configured to communicat= e with + version 2.0: + = + + + set system property + org.jboss.remoting.Version.REMOTING_VERSION_TO_USE + (actual value "jboss.remoting.version") to + org.jboss.remoting.Version.VERSION_2 (actual versi= on + "2"); + + = + + configure the org.jboss.remoting.Client + or org.jboss.remoting.transport.Connector with + the parameter + org.jboss.remoting.Remoting.REMOTING_VERSION (actu= al + value "remotingVersion") set to + org.jboss.remoting.Version.VERSION_2 (actual versi= on + "2"). + + + = + Versions 2.2. and 2.4 use the same wire format, so there's no n= eed to + configure version 2.4 to communicate with version 2.2. + = + Note. Setting these version= s is not + necessary in all circumstances. For example, it is not necessary when= using + JBossSerialization. But, upon encountering a problem when using misma= tched + clients and servers, be sure that the versions are set properly. + = +
+ = + =
Configuration by properties = @@ -5646,7 +5720,8 @@ configuration properties already covered and is just another view to s= ome of the same information. = - org.jboss.remoting.InvokerLocator +
+ org.jboss.remoting.InvokerLocator = SERVER_BIND_ADDRESS (actual v= alue 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. = - +
= - org.jboss.remoting.Client +
+ org.jboss.remoting.Client = RAW (actual value is 'rawPayl= oad') - 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.). + etc.). = CALLBACK_SERVER_HOST (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). = - +
= - org.jboss.remoting.Remoting +
+ org.jboss.remoting.Remoting = CUSTOM_SERVER_SOCKET_FACTORY (actual value is 'customServerSocketFactory') - key for the configurat= ion @@ -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. = - + SOCKET_CREATION_CLIENT_LISTENER + (actual value is "socketCreationClientListener") - key for the configu= ration + map passed to a Client or Connector to indicate a socket creation list= ener + for sockets created by a SocketFactory. + = + SOCKET_CREATION_SERVER_LISTENER + (actual value is "socketCreationServerListener") - key for the configu= ration + map passed to a Client or Connector to indicate a socket creation list= ener + for sockets created by a ServerSocket. + = + CLIENT_ADDRESS (actual value = is + "clientAddress") - key with which host address of client will be assoc= iated + in InvocationRequest request payload. = - org.jboss.remoting.ServerInvoker + REMOTING_VERSION (actual valu= e is + "remotingVersion") - key for configuring Remoting wire version. + = + SKIP_ACCESS_CONTROL (actual v= alue is + "skipAccessControl") - key for telling Remoting to execute security + sensitive code outside of + java.security.AccessController.doPrivileged() + calls.. = = +
+ +
+ org.jboss.remoting.ServerInvoker + MAX_NUM_ONEWAY_THREADS_KEY (a= ctual value is 'maxNumThreadsOneway') - key for the maximum number of thread= s 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. = + + BLOCKING_MODE (actual value is + "blockingMode"): if set to ServerInvoker.BLOCKING (actu= al + value "blocking"), + org.jboss.remoting.Client.getCallbacks() wi= ll do + blocking pull callbacks and CallbackPoller wi= ll do + blocking polled callbacks; if set to + ServerInvoker.NONBLOCKING (actual value "nonblocking"), + Client.getCallbacks() will do non-blocking = pull + callbacks and CallbackPoller will do non-bloc= king + polled callbacks. + + = + + BLOCKING_TIMEOUT (actual value is + "blockingTimeout"): the timeout value used for blocking callback. + + = + + REGISTER_CALLBACK_LISTENER (actua= l value + is "registerCallbackListener"): determines if + org.jboss.remoting.callback.ServerInvokerCallbackHandler<= /classname>s + should register as + org.jboss.remoting.ConnectionListeners with l= eases. + The default value is "true". + + = = Bean properties (meaning have @@ -5988,9 +6116,10 @@ OnewayThreadPool - the oneway thread pool to use. = - +
= - org.jboss.remoting.callback.CallbackPoller +
+ org.jboss.remoting.callback.CallbackPoller = CALLBACK_POLL_PERIOD (actual = value is 'callbackPollPeriod') - key for setting the frequency (in milliseco= nds) @@ -5998,12 +6127,45 @@ callbacks. The default value is five seconds. = - CALLBACK_SCHEDULE_MODE (actual va= lue is "scheduleMode"): may be set to either CallbackPoller.SCHEDULE= _FIXED_RATE (actual value "scheduleFixedRate") or CallbackPoll= er.SCHEDULE_FIXED_DELAY (actual value "scheduleFixedDelay"). In eit= her case, polling will take place at approximately regular intervals, but i= n 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 avera= ge interval will be approximately CALLBACK_POLL_PERIOD milliseco= nds. CallbackPoller.SCHEDULE_FIXED_RATE is the default. + CALLBACK_SCHEDULE_MODE (actual va= lue is + "scheduleMode"): may be set to either + CallbackPoller.SCHEDULE_FIXED_RATE (actual value + "scheduleFixedRate") or CallbackPoller.SCHEDULE_FIXED_DELAY + (actual value "scheduleFixedDelay"). In either case, polling will ta= ke + 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 + average interval will be approximately + CALLBACK_POLL_PERIOD milliseconds. + CallbackPoller.SCHEDULE_FIXED_RATE is the default. = - REPORT_STATISTICS (actual value i= s "reportStatistics"): The presence of this key in metadata, r= egardless of its value, will cause the CallbackPoller to print statistics that might be useful for configuring the other parame= ters.. + REPORT_STATISTICS (actual value is + "reportStatistics"): The presence of this key in metadata, + regardless of its value, will cause the + CallbackPoller to print statistics that might= be + useful for configuring the other parameters.. + = + + SYNCHRONIZED_SHUTDOWN (actual val= ue is + "doSynchronizedShutdown"): if set to "true", + CallbackPoller.stop() will wait for + Client.getCallbacks() 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". + + = + + MAX_ERROR_COUNT (actual value is + "maxErrorCount"): determines the maximum number of errors that may + be experienced during polling before + CallbackPoller will shut itself down. The + default value is "5". + = = CallbackPoller 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 p= oll. = - +
= - org.jboss.remoting.callback.CallbackStore +
+ org.jboss.remoting.callback.CallbackStore = FILE_PATH_KEY (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'. = - +
= - org.jboss.remoting.callback.DefaultCallbackErrorHandler +
+ org.jboss.remoting.callback.DefaultCallbackErrorHandler = CALLBACK_ERRORS_ALLOWED (actu= al value is 'callbackErrorsAllowed') - key for setting the number of call= back @@ -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. = - +
= - org.jboss.remoting.callback.ServerInvokerCallbackHandler +
+ org.jboss.remoting.callback.ServerInvokerCallbackHandler = CALLBACK_STORE_KEY (actual va= lue 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. + = + CALLBACK_TIMEOUT (actual valu= e is + 'callbackTimeout') - key for specifying the timeout to be used for doi= ng + push callbacks. In the absence of + ServerInvokerCallbackHandler.CALLBACK_TIMEOUT, the timeout + value configured for the Connector will be + used. = - +
+ = +
+ org.jboss.remoting.detection.jndi.JNDIDetector = - org.jboss.remoting.detection.jndi.JNDIDetector - Bean properties (meaning have getter/setter): = SubContextName - sub context = name under which detection messages will be bound and looked up. = - +
+ = +
+ org.jboss.remoting.marshal.http.HTTPUnMarshaller + = + PRESERVE_LINES (actual value = is + "preserveLines"): the key used to turn on or off + HTTPUnMarshaller's behavior of stripping CR/LF + characters. + = +
+ = +
+ org.jboss.remoting.transport.bisocket.Bisocket + + IS_CALLBACK_SERVER (actual va= lue is + "isCallbackServer"): when a bisocket server invoker receives this + parameter with a value of true, it avoids the creation of a + ServerSocket. Therefore, IS_CALLBACK_SERV= ER + should be used on the client side for the creation of a callback + server. The default value is false. + + = + + PING_FREQUENCY (actual + value is "pingFrequency"): The server side uses this value + to determine the interval, in milliseconds, between pings that i= t will + send on the control connection. The client side uses this value= to + calculate the window in which it must receive pings on the contr= ol + connection. In particular, the window is ping frequency * ping = window factor. + See also the definition of PING_WINDOW_FACTOR. The default value= is 5000. + + = + + PING_WINDOW_FACTOR (actual + value is "pingWindowFactor"): The client side uses this value to + calculate the window in which it must receive pings on the contr= ol + connection. In particular, the window is ping frequency * ping = window factor. + See also the definition of PING_FREQUENCY. The default value is = 2. + + = + + MAX_RETRIES (actual value is + "maxRetries"): This parameter is relevant only on the client sid= e, + where the BisocketClientInvoker uses it + to govern the number of attempts it should make to get the addre= ss and + port of the secondary ServerSocket, and t= he + BisocketServerInvoker uses it to govern t= he + number of attempts it should make to create both ordinary and co= ntrol + sockets. The default value is 10. + = + + SECONDARY_BIND_PORT (actual v= alue is + "secondaryBindPort"): The server side uses this parameter to det= ermine + the bind port for the secondary + ServerSocket. + = + + SECONDARY_BIND_PORTS (actual = value is + "secondaryBindPorts"): The server side uses this parameter to + determine the bind ports for the secondary + ServerSockets in a multihome server. + = + + SECONDARY_CONNECT_PORT (actua= l value + is "secondaryConnectPort"): The server side uses this parameter = to + determine the connect port used by the client side to connect to= the + secondary ServerSocket. + = + + SECONDARY_CONNECT_PORTS (actu= al value + is "secondaryConnectPorts"): The server side uses this parameter= to + determine the connect ports used by the client side to connect t= o the + secondary ServerSockets in a multihome + server. + = +
= - org.jboss.remoting.transport.http.HTTPMetadataConstants +
+ org.jboss.remoting.transport.http.HTTPClientInvoker = + NUMBER_OF_CALL_ATTEMPTS = (actual + value is "numberOfCallAttempts"): This parameter is relevant only = on the + client side, where it determines the maximum number of attempts th= at + will be made to complete an invocation. The default value is 1. + = +
+ = +
+ org.jboss.remoting.transport.http.HTTPMetadataConstants + The following are keys to use to get corresponding values from t= he Map returned from call to org.jboss.remoting.InvocationRequest.getRequestPayload() within a @@ -6114,7 +6374,7 @@ { if(methodType.equals("GET")) ... - + = PATH (actual value is 'Path')= - key for getting the path from the url request from the calling client. This @@ -6128,7 +6388,7 @@ Map headers =3D invocation.getRequestPayload(); String path =3D (String) headers.get(HTTPMetadataConstants.PATH); ... - + = HTTPVERSION (actual value is 'HttpVersion') - key for getting the HTTP version from the calling cli= ent @@ -6147,7 +6407,7 @@ Map metadata =3D new HashMap(); Object response =3D remotingClient.invoke(myPayloadObject, metadata); Integer responseCode =3D (Integer) metadata.get(HTTPMetadataConstants.RESP= ONSE_CODE); - + = Will be used as key to put the response code in the return paylo= ad map from invocation handler. For example: @@ -6156,7 +6416,7 @@ { Map responseHeaders =3D invocation.getReturnPayload(); responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE, new Intege= r(202)); - + = RESPONSE_CODE_MESSAGE (actual= value is 'ResponseCodeMessage') - key for getting and setting the HTTP respo= nse @@ -6176,8 +6436,21 @@ { Map responseHeaders =3D invocation.getReturnPayload(); responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, "Cu= stom response code and message from remoting server"); - + = + RESPONSE_HEADERS (actual valu= e is + 'ResponseHeaders') - key for returning the value of + java.net.URLConnection.getHeaderFields(). In = other + words, a map containing all of the response headers is stored in the + metadata map. For example, + = + + Object payload =3D ... ; + HashMap metadata =3D new HashMap(); + client.invoke(payload, metadata); + Map responseHeaders =3D (Map) metadata.get(HTTPMetadataConstants.R= ESPONSE_HEADERS); + + = NO_THROW_ON_ERROR (actual val= ue is 'NoThrowOnError') - key indicating if http client invoker (for transpo= rts 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. = - + DONT_RETURN_EXCEPTION (actual= value + is 'dont-return-exception') - key indicating if + org.jboss.remoting.transport.servlet.ServletServerInvoker + should revert to the orginal error handling behavior of returning an e= rror + message. = For every http client request made from remoting client, a remot= ing 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'. = - +
+ = +
+ org.jboss.remoting.transport.http.ssl.HTTPSClientInvoker = - org.jboss.remoting.transport.http.ssl.HTTPSClientInvoker - IGNORE_HTTPS_HOST (actual val= ue is 'org.jboss.security.ignoreHttpsHost') - key indicating if the http cli= ent 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. = - +
= - org.jboss.remoting.transport.rmi.RMIServerInvoker +
+ org.jboss.remoting.transport.rmi.RMIServerInvoker = REGISTRY_PORT_KEY (actual val= ue 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. = - + RMI_ONEWAY_MARSHALLING (actua= l value + is 'rmiOnewayMarshalling') - if set to "true" will cause the RMI trans= port + to use the original client to server marshalling behavior. = - org.jboss.remoting.transport.socket.MicroSocketClientInvok= er +
= +
+ org.jboss.remoting.transport.socket.MicroSocketClientInvoker</t= itle> + <para><emphasis role=3D"bold">TCP_NODELAY_FLAG</emphasis> (actual valu= e 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 + = + evictabilityTimeout - indic= ates the + number of milliseconds during which a server thread waiting for the = next + invocation will not be preemptible. + = + continueAfterTimeout - indi= cates + what a server thread should do after experiencing a + java.net.SocketTimeoutException. If set to "tr= ue", + the server thread will continue to wait for an invocation; otherwise,= it + will return itself to the thread pool. + = +
= = + = +
+ org.jboss.remoting.transport.socket.SocketServerInvoker = - org.jboss.remoting.transport.socket.SocketServerInvoker - CHECK_CONNECTION_KEY (actual = value is 'socket.check_connection') - key for indicating if socket invoker should continue to keep socket connection between client and server op= en @@ -6261,5 +6561,7 @@ SERVER_SOCKET_CLASS_FLAG (act= ual value is 'serverSocketClass') - specifies the fully qualified class na= me for the custom SocketWrapper implementation to use on the server. +
+ =
\ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap6.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - - Sending streams + + + Adding a New Transport + = + It is quite straightforward to extend Remoting with a new transpor= t (other than the part about writing the new transport!). There are only t= hree requirements. Suppose the new transport is to be called "nio", which = would then be used by an InvokerLocator such as "nio= ://bluemonkey.com:5555/?timeout=3D10000". + = + + + There needs to be a class org.jboss.remoting.trans= port.nio.TransportServerFactory which implements the interface = org.jboss.remoting.transport.ServerFactory: + = + + public interface ServerFactory + { + public ServerInvoker createServerInvoker(InvokerLocator locat= or, Map config) throws IOException; + = + public boolean supportsSSL(); + } + + + = + + There needs to be a class org.jboss.remoting.trans= port.nio.TransportClientFactory which implements the interface = org.jboss.remoting.transport.ClientFactory: + = + + public interface ClientFactory + { + public ClientInvoker createClientInvoker(InvokerLocator locat= or, Map config) throws IOException; + = + public boolean supportsSSL(); + } + + + = + + The factory classes must be loadable when the first "nio" InvokerLocator is encountered. + + = + + = + The factories can be quite simple. The + createServerInvoker() method must return an ins= tance + of an appropriate subclass of + org.jboss.remoting.ServerInvoker, the + createClientInvoker() method must return an + appropriate implementation of the interface + org.jboss.remoting.transport.ClientInvoker, and t= he + supportsSSL() methods indicate if the transport + supports SSL. + = + The factories for the "socket" transport, for example, are + = + + 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; = - 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 try= ing - to copy a 3 Gig file into memory and getting out of memory errors). + public class TransportServerFactory implements ServerFactory + { + public ServerInvoker createServerInvoker(InvokerLocator locator, Ma= p config) + { + return new SocketServerInvoker(locator, config); + } + = + public boolean supportsSSL() + { + return false; + } + } + + = + and + = + + 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, Ma= p config) + throws IOException + { + return new SocketClientInvoker(locator, config); + } + = + public boolean supportsSSL() + { + return false; + } + } + + = + Similarly, the server invoker factory for the "sslsocket" transpor= t is + = + + 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; = - Use of this new feature is simple. From the client side, there i= s a - method in org.jboss.remoting.Client with the signature: - - public Object invoke(InputStream inputStream, Object p= aram) throws Throwable - - - So from the client side, would just call invoke as done in the p= ast, - 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): - - - String param =3D "foobar"; - File testFile =3D new File(fileURL.getFile()); - ... - Object ret =3D remotingClient.invoke(fileInput, param); - - - From the server side, will need to implement - org.jboss.remoting.stream.StreamInvocationHandler instead= of - org.jboss.remoting.ServerInvocationHandler . - StreamInvocationHandler extends ServerInvocationHandler, with the addi= tion - of one new method: - - public Object handleStream(InputStream stream, Object = param) - - The stream passed to this method can be called on just as any - regular local stream. Under the covers, the InputStream passed is real= ly - proxy to the real input stream that exists in the client's VM. Subsequ= ent - 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 hand= ler - does not implement StreamInvocationhandler, an exception will be throw= n to - the client caller. - - If want to have more control over the stream server being create= d 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 st= ream - server and pass it when making Client invocation. - - public Object invoke(InputStream inputStream, Object p= aram, Connector streamConnector) throws Throwable - - 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). - - Can also call invoke() method on client= and - pass the invoker locator - would like to use and allow remoting to create the stream server using= the - specified locator. - - public Object invoke(InputStream inputStream, Object p= aram, InvokerLocator streamServerLocator) throws Throwable - - In this case, the Connector created internally by remoting will = be - stopped when the stream is closed by the server's stream proxy. - - It is VERY IMPORTANT that the StreamInvocationHandler implementa= tion - close the InputStream when it finishes reading, as will close the real - stream that lives within the client VM. - -
- Configuration - - By default, the stream server which runs within the client JVM - uses the following values for its locator uri: - - transport - socket - - host - tries to first get local host name and if that fails, t= he - local ip (if that fails, localhost). - - port - 5405 - - Currently, the only way to override these settings is to set t= he - following system properties (either via JVM arguments or via - System.setProperty() method): - - remoting.stream.transport - sets the transport type (rmi, http, - socket, etc.) - - remoting.stream.host - host name or ip address to use - - remoting.stream.port - the port to listen on - - These properties are important because currently the only way = for - a target server to get the stream data from the stream server (runni= ng - within the client JVM) is to have the server invoker make the invoca= tion - on a new connection back to the client (see issues below). -
- -
- Issues - - 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 h= ave - 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 establis= hed - by the client to the server (JBREM-91). This will make communications - back to client much simpler from this standpoint. -
- \ No newline at end of file + public class TransportServerFactory implements ServerFactory + { + public ServerInvoker createServerInvoker(InvokerLocator locator, Ma= p config) + { + return new SSLSocketServerInvoker(locator, config); + } + = + public boolean supportsSSL() + { + return true; + } + } + + Modified: remoting2/branches/2.x/docs/guide/en/chap8.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - - - Connection Exception Listeners and Leasing + + Serialization = - Client side + Serialization - how it works within remoting: In general, remoti= ng + will rely on a factory to provide the serialization implementation, or + org.jboss.remoting.serialization.SerializationManager, to= be + used when doing object serialization. This factory is + org.jboss.remoting.serialization.SerializationStreamFactory + and is a (as defined by its javadoc): = - 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. + factory is for defining the Object stream implemenation= s to be used along with creating those implemenations for use. +The main function will be to return instance of ObjectOutput and ObjectInp= ut. By default, the implementations will be = +java.io.ObjectOutputStream and java.io.ObjectInputStream. + = - The only requirement is to implement the - org.jboss.remoting.ConnectionListener interface, which has = only - one method: + Currently there are only two different types of serialization + implementations; 'java' and 'jboss'. The 'java' type uses + org.jboss.remoting.serialization.impl.java.JavaSerializationMana= ger + as the SerializationManager implementation and is backed by standard J= ava + serialization provide by the JVM, which is the default. The 'jboss' ty= pe + uses + org.jboss.remoting.serialization.impl.jboss.JBossSerializationMa= nager + as the SerializationManager implementation and is backed by JBoss + Serialization. = - public void handleConnectionException(Throwable throwabl= e, Client client) + JBoss Serialization is a project intended to provide a + more performant implementation of object serialization. It complies wi= th + java serialization standard with three exceptions: = - Then call the addConnectionListener(ConnectionListener - listener) method on the Client class and pass your listener insta= nce. - Can also call addConnectionListener(ConnectionListener listener, i= nt - pingPeriod) if want to specify how frequently wish to ping - server. + - SerialUID not needed = - Currently, the Client will use the - org.jboss.remoting.ConnectionValidator 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. + - java.io.Serializable is not required = - Server side + - different protocol = - 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. + JBoss Serialization requires JDK 1.5 = - To turn on server side connection failure detection of remoting cl= ients, - will need to satisfy two criteria. The first is that the client lease pe= riod - 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 c= alling - the:public void setLeasePeriod(long - leasePeriodValue)method within Connector. The second - criterion is that an implementation of the - org.jboss.remoting.ConnectionListener interface is added as= a - connection listener to the Connector, via the method:pub= lic - void addConnectionListener(ConnectionListener listener)= Note, - there is no way to set the connection listener via xml based configurati= on for - the Connector. Once both criteria are met, the remoting server will turn= on - client leasing. + = - The ConnectionListener will be notified of both client failures and - client disconnects via the handleConnectionException() method. If the cl= ient - 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. - - 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 d= oes - not have a lease update duration that is longer than 75% of the lease wi= ndow - (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 windo= w will - be reset to the lease duration X 2 (meaning if set lease period to 10 se= conds - 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 take= s two - consecutive timeouts before a lease will expire and a notification for c= lient - connection failure is fired. This essentially means that the time it wil= l take - before a connection listener is notified of a client connection failure = will - be at least 4 X lease period (no exceptions). - - 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 inv= oker - locator parameter of 'leasing' to true or include configuration entry wi= th key - of 'enableLease' and value of true to the map passed when creating a Cli= ent - 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 l= easing - 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 w= orth - noting is that if the client and server are local, meaning running withi= n the - jvm, leasing (and thus connection notification) will not be activated, e= ven if - is configured to do so. - - If leasing is turned on within the client side, there is no API or - configuration changes needed, unless want to override as mentioned previ= ously. - 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 monit= oring - lease for this client. Therefore, it is IMPORTANT that disconnect is called on the clie= nt when - done using it. Otherwise, the client will continue to make its ping call= on - the server to keep its lease current. - - The client can also provide extra metadata the will be communicate= d to - the connection listener in case of failure by supplying a metadata Map t= o the - Client constructor. This map will be included in the Client instance pas= sed to - the connection listener (via the handleConnectionException() method) via= the - Client's getConfiguration() method. - - From the server side, there are two ways in which to disable leasi= ng - (i.e. turn leasing off). The first is to call: - - public void removeConnectionListener(ConnectionListener = listener) - - and remove all the registered ConnectionListeners. Once the last o= ne - has been removed, leasing will be disabled and all the current leasing - sessions will be terminated. The other way is to call: - - public void setLeasePeriod(long leasePeriodValue) - - and pass a value less than zero. This will disable leasing, preven= ting - any new leases to be established but will allow current leasing sessions= to - continue. - - For examples of how to use server side connection listeners, refer= ence - org.jboss.test.remoting.lease.LeaseTestServer and - org.jboss.test.remoting.lease.LeaseTestClient. - \ No newline at end of file + It is possible to override the default SerializationManger + implementation to be used by setting the system property 'SERIALIZATIO= N' + to the fully qualified name of the class to use (which will need to + provide a void constructor). + \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/chap9.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - - Transporters - beaming POJOs + + + Network Connection Monitoring + = + Remoting has two mechanisms for monitoring the health of estabilis= hed + connections, which inform listeners on the client and server sides when a + possible connection failure has been detected. + = +
+ Client side monitoring = - There are many ways in which to expose a remote interface to a j= ava - object. Some require a complex framework API based on a standard - specification and some require new technologies like annotations and A= OP. - Each of these have their own benefits. JBoss Remoting transporters pro= vide - the same behavior via a simple API without the need for any of the new= er - technologies. + On the client side, an + org.jboss.remoting.ConnectionValidator periodic= ally + sends a PING message to the server and reports a failure if the respon= se + 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. + = + The creation of the ConnectionValidator i= s the + responsibility of the org.jboss.remoting.Client + class. All the application code needs to do is to register an implemen= tation + of the org.jboss.remoting.ConnectionListener interface, w= hich + has only one method: + = + public void handleConnectionException(Throwable throwa= ble, Client client); + = + What actions the ConnectionListener choos= es to + take are up to the application, but disconnecting the + Client might be a reasonable strategy. + = + The Client class has three methods for + registering a ConnectionListener: + = + + public void addConnectionListener(ConnectionListener listener); + public void addConnectionListener(ConnectionListener listener, int = pingPeriod); + public void addConnectionListener(ConnectionListener listener, Map = metadata); + = - When boiled down, transporters take a plain old java object (POJ= O) - 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. - \ No newline at end of file + The second method supports configuring the frequency of PING mes= sages, + and the third method supports more general configuration of the + ConnectionValidator. Note that a given + Client maintains a single + ConnectionValidator, so the parameters in the + metadata map are applied only on the first call to + Client.addConnectionListener(). The following + parameters are supported by ConnectionValidator, + which is where the parameter names are defined: + = + VALIDATOR_PING_PERIOD (actual= value + "validatorPingPeriod") - specifies the time, in milliseconds, that ela= pses + between the sending of PING messages to the server. The default value = is + 2000. + = + VALIDATOR_PING_TIMEOUT (actua= l value + "validatorPingTimeout") - specifies the time, in milliseconds, allowed= for + arrival of a response to a PING message. The default value is 1000. = + = + For more configuration parameters, see . + = + Note, also, that ConnectionValidator crea= tes a + client invoker to sends the PING messages, and it passes the metadata = map to + configure the client invoker. + = +
+ +
+ Server side monitoring + = + A remoting server also has the capability to detect when a clien= t is + no longer available. This is done by estabilishing a lease with the re= moting + clients that connect to a server. On the client side, an + org.jboss.remoting.LeasePinger periodically sen= ds + PING messages to the server, and on the server side an + org.jboss.remoting.Lease informs registered lis= teners + if the PING doesn't arrive withing the specified timeout period. + = + Server side activation. To tu= rn 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 Connector method + = + public void setLeasePeriod(long leasePeriodValue); + = + The second + criterion is that an implementation of the + org.jboss.remoting.ConnectionListener interface is added = as a + connection listener to the Connector, via the method + = + public void addConnectionListener(ConnectionListener l= istener) + = + Once both criteria are met, the remoting server will turn on cl= ient + leasing. + = + Note that there is no way to register a + ConnectionListener via xml based configuration = for + the Connector. + = + 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 perio= d, 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). No= te, + 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. + = + The actual lease window established on the server side is dynamic + based the rate at which the client updates its lease. In particular, t= he + 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 leas= e 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 p= eriod + 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 wi= ndow). + 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). + = + Client side activation. By de= fault, + the client is not configured to do client leasing. To allow a client t= o do + leasing, either set the parameter "leasing" to "true" in the + InvokerLocator or set the parameter + Client.ENABLE_LEASE (actual value "enableLease") to true = in the + InvokerLocator or in the + Client configuration map. [The use of + Client.ENABLE_LEASE is recommended.] This does not mean t= hat + client will lease for sure, but will indicate the client should call o= n 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 + org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PERIOD (ac= tual + value "lease_period") to a value greater than 0 and less than the value + suggested by the server. Note. If t= he + client and server are local, meaning running within the JVM, leasing (= and + thus connection notification) will not be activated, even if is config= ured + to do so. + = + 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 le= ase. + When the client disconnects, it will internally send message to the se= rver + to stop monitoring lease for this client. Therefore, it is IMPORTANT that disconnect is called on the cl= ient + when done using it. Otherwise, the client will continue to make its pi= ng + call on the server to keep its lease current. + = + The client can also provide extra metadata the will be communica= ted 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 instan= ce + passed to the connection listener (via the handleConnectionException() + method) via the Client's getConfiguration() method. + = + From the server side, there are two ways in which to disable lea= sing + (i.e. turn leasing off). The first is to call: + = + public void removeConnectionListener(ConnectionListene= r listener) + = + 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: + = + public void setLeasePeriod(long leasePeriodValue) + = + and pass a value less than zero. This will disable leasing, prev= enting + any new leases to be established but will allow current leasing sessio= ns to + continue. + = + The following parameter is relevant to leasing configuration on = the server side: + = + org.jboss.remoting.ServerInvoker.CLIENT_LEASE_PERI= OD + (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 + org.jboss.remoting.ConnectionListener is regist= ered + with the server. This is also the suggested lease period returned by t= he + server when the client inquires if leasing is activated. + = + The following parameters are relevant to leasing configuration o= n the client side: + = + org.jboss.remoting.Client.ENABLE_LEASE + (actual value "enableLease") - if set to "true", will lead + org.jboss.remoting.Client to attempt to set up a + lease with the server, if leasing is activated on the server. + = + org.jboss.remoting.InvokerLocator.CLIENT_LEASE + (actual value "leasing") - if set to "true" in the + InvokerLocator, will lead + org.jboss.remoting.Client 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 + Client.ENABLE_LEASE. + = + org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PER= IOD + (actual value "lease_period") - if set to a value greater than 0 and l= ess + than the suggested lease period returned by the server, will be used to + determine the time between PING messages sent by + LeasePinger. + = + org.jboss.remoting.LeasePinger.LEASE_PINGER_TIMEOU= T + (actual value "leasePingerTimeout") - specifies the per invocation tim= eout + value use by LeasePinger when it sends PING mes= sages. + In the absence of a configured value, the timeout value used by the + Client that created the + LeasePinger will be used. + = + For examples of how to use server side connection listeners, ref= erence + org.jboss.test.remoting.lease.LeaseTestServer and + org.jboss.test.remoting.lease.LeaseTestClient. + = +
+ = +
+ = + Interactions between client side and server side connection mon= itoring + = + As of Remoting version 2.4, the client side and server side conn= ection + monitoring mechanisms can be, and by default are, more closely related= , in + two ways. + = + + If the parameter + org.jboss.remoting.ConnectionValidator.TIE_TO_LEASE (a= ctual + value "tieToLease") is set to true, then, when the server receives = a PING + message from an + org.jboss.remoting.ConnectionValidator, it w= ill + return a boolean value that indicates whether a lease currently exi= sts + for the connection being monitored. If leasing is activated on the = client + and server side, then a value of "false" indicates that the lease h= as + failed, and the ConnectionValidator will tre= at a + returned value of "false" the same as a timeout; that is, it will n= otifiy + listeners of a connection failure. The default value of this parame= ter is + "true". Note. If leasing is not + activated on the client side, then this parameter has no + effect. + = + If the parameter + org.jboss.remoting.ConnectionValidator.STOP_LEASE_ON_FAILURE<= /code> + (actual value "stopLeaseOnFailure") is set to true, then, upon dete= cting + a connection failure, ConnectionValidator wi= ll + stop the LeasePinger, if any, pinging a leas= e on + the same connection. The default value is "true". + = + + = + TIE_TO_LEASE (actual value + "tieToLease") - specifies whether ConnectionValidator + should treat the failure of a related lease on the server side as a + connection failure. The default value is "true". + = + STOP_LEASE_ON_FAILURE (actual= value + "stopLeaseOnFailure") - specifies whether, when a + ConnectionValidator detects a connection failur= e, it + should stop the associated + org.jboss.remoting.LeasePinger, if any. The def= ault + value is "true". + = +
+ \ No newline at end of file Modified: remoting2/branches/2.x/docs/guide/en/master.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ + ]> JBoss Remoting Guide = - JBoss Remoting version 2.2.0.GA + JBoss Remoting version 2.4.0.GA = - March 19, 2007 + May 28, 2008 = @@ -33,7 +34,7 @@ = - 2007 JBoss, a division of Red Hat + 2008 JBoss, a division of Red Hat = . @@ -70,4 +71,6 @@ &chap15; = &chap16; + = + &chap17; \ No newline at end of file --===============6643954121660855825==--