Author: dobri
Date: Wed Jun 3 15:16:51 2009
New Revision: 781427
URL: http://svn.apache.org/viewvc?rev=781427&view=rev
Log:
This is the documentation related to JIRA AXIS2-4288. Documentation about "Setting the cached
httpstate object" and the motivation to use this configuration.
Modified:
webservices/axis2/trunk/java/modules/documentation/xdocs/@axis2_version_dir@/http-transport.xml
Modified: webservices/axis2/trunk/java/modules/documentation/xdocs/@axis2_version_dir@/http-transport.xml
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/modules/documentation/xdocs/%40axis2_version_dir%40/http-transport.xml?rev=781427&r1=781426&r2=781427&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/documentation/xdocs/@axis2_version_dir@/http-transport.xml
(original)
+++ webservices/axis2/trunk/java/modules/documentation/xdocs/@axis2_version_dir@/http-transport.xml
Wed Jun 3 15:16:51 2009
@@ -313,6 +313,41 @@
configurationContext.setProperty(HTTPConstants.CACHED_HTTP_CLIENT, client);
</pre>
</source>
+
+ <a name="setting_cached_httpstate_object"></a>
+<h2>Setting the cached httpstate object</h2>
+
+HttpState object can be set as property to the options of a given Axis2 client.
+HttpState keeps HTTP attributes that may persist from request to request, such
+ as cookies and authentication credentials. So, it is possible to re-use one and
+ the same HttpState object if appropriate.
+
+The idea is to provide the capability to specify/associate a separate HttpState
+with every client and still reuse one and the same HttpClient. So, this make
+sense only when CACHED_HTTP_CLIENT is re-used between different clients
+from different threads which may invoke different hosts with different credentials
+and cookies. This is really complicated scenario, but is absolutely possible one.
+ If you re-use a common HttpClient between different clients then the clients will
+ re-use, the internal for the HttpClient, HttpState object. Doing so authentication
+ credentials are exposed to all clients sharing one and the same HttpClient.
+ This is definitely not a good idea. The problem with Cookies is different. The
+ problem here is that if two distinct clients invoke one and the same service
+ at a specific host then the session established with a given cookie by one of
+ the clients can wrongly be shared among them, too, if it has not expired. This
+ will cause problems since the two client may need different sessions, which is
+ the more probable scenario.
+
+Sample configuration:
+
+ <source>
+ <pre>
+HttpState myHttpState = new HttpState();
+options.setProperty(WSClientConstants.CACHED_HTTP_STATE, myHttpState);
+</pre>
+ </source>
+
+Doing so the HttpState is attached to the client. Respectively this is automatically propagated
to all MessageContext objects used by the client.
+Underneath this just instructs Axis2 that the CACHED_HTTP_STATE set should be passed as a
parameter when HttpClient#executeMethod is invoked.
</body>
</html>
|