[Ws Wiki] Update of "FrontPage/Axis/SessionSupport" by CyrilleLeClerc

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Ws Wiki" for change notification.

The following page has been changed by CyrilleLeClerc:
http://wiki.apache.org/ws/FrontPage/Axis/SessionSupport

The comment on the change is:
Add client side session sample and detail multi client side sessions

------------------------------------------------------------------------------
  
  A: Any time after the session context has been established, calling getSession() on the current messageContext will obtain you a reference to a Session object. You may use this object like a Hashtable to store arbitrary data associated with this Session. For instance, on one request you might extract the caller's name and address from a database (an expensive operation), and then cache them in the Session object for fast access on subsequent invocations from the same caller. This functionality can be used either by custom Handlers or by your backend service object itself. 
  
+ 
+ '''Sample of client side sessions'''
+ 
+ To enable stateful invocations on the client, you have to call {{{setMaintainSession(true)}}} on the {{{Stub}}}
+ 
+ Sample :
+ {{{
+ HelloWorldServiceLocator helloWorldServiceLocator = new HelloWorldServiceLocator();
+ HelloWorldBindingStub bindingStubForJohnDoe = (HelloWorldBindingStub) helloWorldServiceLocator
+       .gethelloWorldBinding();
+ 
+ bindingStubForJohnDoe.setMaintainSession(true);
+ 
+ // Say hello will create a server side session 
+ String helloJohnDoe = bindingStubForJohnDoe.sayHello("JohnDoe");
+ System.out.println("helloJohnDoe : " + helloJohnDoe);
+ 
+ // Say good bye will use the same server side session
+ String goodByeJohnDoe = bindingStubForJohnDoe.sayGoodBye("JohnDoe");
+ System.out.println("goodByeJohnDoe : " + goodByeJohnDoe);
+ }}}
+ 
+ 
+ (!) Client side session support relies on http cookies, all the cookies created by the server ({{{Set-Cookie}}} header in the http response) are kept by the client and re-sent for each following invocation.
+ 
+  That is to say not only the JSESSIONID cookie is propagated but also any other cookie (e.g. : created by an SSO layer, ...)
+ 
+ (!) The internal behavior of client side session support is to store the cookies as an instance variable of the {{{Stub}}}
+ 
+ '''Sample of multi client side sessions'''
+ 
+ A SOAP client may have to open several sessions at the same time. To do this, you have to instantiate one {{{Stub}}} per session. 
+ 
+ Axis supports multi client side sessions with no restriction : sessions are not associated with threads but only with the {{{Stub}}} instance.
+ 
+ Sample of mixed invocations :
+ {{{
+ HelloWorldServiceLocator helloWorldServiceLocator = new HelloWorldServiceLocator();
+ HelloWorldBindingStub bindingStubForJohnDoe = (HelloWorldBindingStub) helloWorldServiceLocator
+       .gethelloWorldBinding();
+ HelloWorldBindingStub bindingStubForJohnSmith = (HelloWorldBindingStub) helloWorldServiceLocator
+       .gethelloWorldBinding();
+ 
+ bindingStubForJohnDoe.setMaintainSession(true);
+ bindingStubForJohnSmith.setMaintainSession(true);
+ 
+ 
+ // Open the JohnDoe session
+ String helloJohnDoe = bindingStubForJohnDoe.sayHello("JohnDoe");
+ System.out.println("helloJohnDoe : " + helloJohnDoe);
+ 
+ // Open the JohnSmith session
+ String helloJohnSmith = bindingStubForJohnSmith.sayHello("JohnSmith");
+ System.out.println("helloJohnSmith : " + helloJohnSmith);
+ 
+ 
+ // Reuse the JohnDoe session
+ String goodByeJohnDoe = bindingStubForJohnDoe.sayGoodBye("JohnDoe");
+ System.out.println("goodByeJohnDoe : " + goodByeJohnDoe);
+ 
+ // Reuse the JohnSmith session
+ String goodByeJohnSmith = bindingStubForJohnSmith.sayGoodBye("JohnSmith");
+ System.out.println("goodByeJohnSmith : " + goodByeJohnSmith);
+ }}}
+ 
+ /!\ you should use the same {{{ServiceLocator}}} to instantiate the different stubs. The {{{ServiceLocator}}} is a heavyweight object that holds the HTTPSender, single instantiation it is particularly important if you use CommonsHTTPSender (otherwise, each Stub would use a diferent {{{MultiThreadedHttpConnectionManager}}}).
+ 
+ '''Q: Is it possible to maintain a session for a long duration ?'''
+ 
+ It can be necessary to maintain a web service session between two user interactions for example.
+ 
+ Maintaining the session between SOAP invocations requires to keep a reference on the client Stub. The Stub is a lightweight component that can be kept alive for a long time.
+ 
+ 
+ (!) Note that the Stub is lightweight in the sense that :
+  * It has small memory footprint. It only holds headers and attachments. 
+  Attachments are automatically removed calling {{{Stub.getAttachments()}}} and thus should never live for a long duration on the Stub
+  * It does not hold critical resources (socket, ...). It is the {{{ServiceLocator}}} and not the {{{Stub}}} that may hold opened http connections (see Self:FrontPage/Axis/AxisCommonsHTTP )
+ 
+ /!\ It is possible to keep references on an important number of stubs instances (for a short or for a long duration) as long as '''all the stubs are instanciated by the same {{{ServiceLocator}}}'''. Keep in mind that the {{{ServiceLocator}}} is a heavyweight object.
+