Repository: camel Updated Branches: refs/heads/master 57758538f -> 3c3c03852
CAMEL-10392: Add overall documentation Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/3c3c0385 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/3c3c0385 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/3c3c0385 Branch: refs/heads/master Commit: 3c3c03852d717ce85d128affa874f39a3731b835 Parents: 5775853 Author: Stephan Siano <stephan.si...@sap.com> Authored: Fri Oct 21 10:07:51 2016 +0200 Committer: Stephan Siano <stephan.si...@sap.com> Committed: Fri Oct 21 10:11:10 2016 +0200 ---------------------------------------------------------------------- docs/user-manual/en/SUMMARY.md | 1 + docs/user-manual/en/http-session.adoc | 139 +++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/3c3c0385/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 758ab74..0af8dc9 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -34,6 +34,7 @@ * [Exchange](exchange.adoc) * [Exchange Pattern](exchange-pattern.adoc) * [Expression](expression.adoc) + * [HTTPSession](http-session.adoc) * [Injector](injector.adoc) * [Intercept](intercept.adoc) * [Inversion Of Control With Smart Defaults](inversion-of-control-with-smart-defaults.adoc) http://git-wip-us.apache.org/repos/asf/camel/blob/3c3c0385/docs/user-manual/en/http-session.adoc ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/http-session.adoc b/docs/user-manual/en/http-session.adoc new file mode 100644 index 0000000..e61e65a --- /dev/null +++ b/docs/user-manual/en/http-session.adoc @@ -0,0 +1,139 @@ +[[HTTPSession-HTTPSession]] +HTTP-Session Handling +~~~~~~~~~~~~~~~~~~~~~ + +Several Camel components can use HTTP as the underlying transport protocol. +In general HTTP calls are stateless in nature, however some servers allow +to maintain state via cookies. Cookies are often used to maintain a server +session (e.g. via a session cookie called "JSESSIONID" with servers implementing +the JEE Servlet specification). + +[[HTTPSession-SessionScope]] +Session Scope +^^^^^^^^^^^^^ + +If a Camel route intends to implement some kind of HTTP session handling +the scope of this session should be considered. + +Independently of the session scope the implementation must honor the domain of +the handled cookies. + +[[HTTPSession-ContextScope]] +Route/Context Scope ++++++++++++++++++++ + +It might be desirable to have a single session for a route or a +link:camelcontext.html[CamelContext]. This essentially means that all calls to +a server issued from a route or CamelContext share a single HTTP session. + +[[HTTPSession-EndpointScope]] +Endpoint Scope +++++++++++++++ + +It is also possible to have a session on an +link:endpoint.html[Endpoint] entity. This would mean that all invocations of +an HTTP call issued by a single Endpoint share a session, whereas different +Endpoints never share sessions, even if the call is sent to the same server. + +Some components like camel-http, and camel-http4 support endpoint scoped sessions +even prior to version 2.19. + +[[HTTPSession-ExchangeScope]] +Exchange Scope +++++++++++++++ + +The third option to define a session scope is on +link:exchange.html[Exchange] level. This is particularly useful for scenarios +where the server session is really maintaining state. + +In this case the route could e.g. first do a login call, then some update calls +and finally a logout call. If the session handling would be defined on route or +CamelContext scopes this would seem to run, however under load parallel invocations +of the route would share a *single* session, which could cause issues. If the session +is defined on exchange scope, each invocation of the route will get a separate session +and the server can maintain a separate state for the different parallel invocations. + +[[HTTPSession-Usage]] +Usage +^^^^^ + +If you are a Camel user, you see that several Camel components support the cookieHandler +parameter on endpoint level. All you need to do is to instantiate a cookie handler +appropriate for your use case and reference it in the cookieHandler parameter for +all endpoints that are supposed to participate in the HTTP session. + +There are two pre-implemented cookie handlers: +`org.apache.camel.http.common.cookie.InstanceCookieHandler` and +`org.apache.camel.http.common.cookie.ExchangeCookieHandler`. + +The InstanceCookieHandler stores cookies in an instance of itself. You can compare that +to a Browser instance that is shared between all the endpoints that use it (and will +be used for all invocations of these endpoints). If you want to maintain separate sessions +for different endpoints or groups of endpoints you may have multiple instances of the +InstanceCookieHandler. + +The ExchangeCookieHandler stores the session in the exchange. With the browser analogy +this means that each Exchange will get its own browser instance (so sessions are separated). +As the ExchangeCookieHandler does not store any state it is generally not useful to have +multiple ExchangeCookieHandler instances (as they would access the same data, anyway). + +Example ++++++++ + +The following three routes will each do two invocations of an echo REST service. In the first +route (without a cookie handler) each invocation will get a new session. For the second route +all invocations will share a session. For the third route the first and the second invocation +within the route share a session, but different (even parallel) invocations of the route will +not share a session. + +[source,xml] +----------------------------------------------------------- + <cxf:rsClient id="rsClientProxy" address="http://127.0.0.1:8080/CxfRsProducerSessionTest/"; + serviceClass="org.apache.camel.component.cxf.jaxrs.testbean.EchoService" + loggingFeatureEnabled="true" /> + + <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> + <route> + <from uri="direct://proxy"/> + <to uri="cxfrs://bean://rsClientProxy"/> + <convertBodyTo type="java.lang.String"/> + <to uri="cxfrs://bean://rsClientProxy"/> + </route> + <route> + <from uri="direct://proxyinstance"/> + <to uri="cxfrs://bean://rsClientProxy?cookieHandler=#instanceCookieHandler"/> + <convertBodyTo type="java.lang.String"/> + <to uri="cxfrs://bean://rsClientProxy?cookieHandler=#instanceCookieHandler"/> + </route> + <route> + <from uri="direct://proxyexchange"/> + <to uri="cxfrs://bean://rsClientProxy?cookieHandler=#exchangeCookieHandler"/> + <convertBodyTo type="java.lang.String"/> + <to uri="cxfrs://bean://rsClientProxy?cookieHandler=#exchangeCookieHandler"/> + </route> + </camelContext> + + <bean id="instanceCookieHandler" class="org.apache.camel.http.common.cookie.InstanceCookieHandler"/> + <bean id="exchangeCookieHandler" class="org.apache.camel.http.common.cookie.ExchangeCookieHandler"/> +----------------------------------------------------------- + +[[HTTPSession-ComponentDevelopers]] +Component Developers +^^^^^^^^^^^^^^^^^^^^ + +If you want to develop a HTTP based component that is supposed to participate in a session +you have to add the following parts to your code: + +. Include a build reference to camel-http-common (if it is not already there) +. Add a cookieHandler parameter to the endpoint class (together with getter and setter) +. Before your code does the HTTP call, if a cookie handler is set on the endpoint +perform a `cookieHandler.loadCookies(exchange, uri)` call. It will return a +`Map<String, List<String>>` containing the headers that need to be sent to the server. +The details how you need to send these headers to the server depend on the underlying HTTP +API you are using. +. After your code does receive the HTTP response if a cookie handler is set on the endpoint +perform a `cookieHandler.storeCookies(exchange, uri, m)` call. `m` is a `Map<String, List<String>>`. + +Note: some APIs provide more direct support for cookie handling. In this case it might be easier +to get the underlying `java.net.CookieStore` with a `cookeManager.getCookieStore(exchange)` call +and handle the cookies using the cookie interface provided by the underlying library. \ No newline at end of file
