Repository: camel Updated Branches: refs/heads/master 5b5cf32bb -> 6f404e73c
Added camel-servlet docs to Gitbook Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/6f404e73 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/6f404e73 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/6f404e73 Branch: refs/heads/master Commit: 6f404e73cae77996afe03a2128ae53f218b14169 Parents: 5b5cf32 Author: Andrea Cosentino <anco...@gmail.com> Authored: Tue May 24 10:06:12 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Tue May 24 10:06:12 2016 +0200 ---------------------------------------------------------------------- .../camel-servlet/src/main/docs/servlet.adoc | 248 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 249 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/6f404e73/components/camel-servlet/src/main/docs/servlet.adoc ---------------------------------------------------------------------- diff --git a/components/camel-servlet/src/main/docs/servlet.adoc b/components/camel-servlet/src/main/docs/servlet.adoc new file mode 100644 index 0000000..42efe67 --- /dev/null +++ b/components/camel-servlet/src/main/docs/servlet.adoc @@ -0,0 +1,248 @@ +[[SERVLET-ServletComponent]] +Servlet Component +~~~~~~~~~~~~~~~~~ + +The *servlet:* component provides HTTP based +link:endpoint.html[endpoints] for consuming HTTP requests that arrive at +a HTTP endpoint that is bound to a published Servlet. + +Maven users will need to add the following dependency to their `pom.xml` +for this component: + +[source,xml] +--------------------------------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-servlet</artifactId> + <version>x.x.x</version> + <\!-\- use the same version as your Camel core version \--> +</dependency> +--------------------------------------------------------------- + + +INFO: *Stream*. +Servlet is stream based, which means the input it receives is submitted +to Camel as a stream. That means you will only be able to read the +content of the stream *once*. If you find a situation where the message +body appears to be empty or you need to access the data multiple times +(eg: doing multicasting, or redelivery error handling) you should use +link:stream-caching.html[Stream caching] or convert the message body to +a `String` which is safe to be read multiple times. + +[[SERVLET-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +--------------------------------- +servlet://relative_path[?options] +--------------------------------- + +You can append query options to the URI in the following format, +`?option=value&option=value&...` + +[[SERVLET-Options]] +Options +^^^^^^^ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Name |Default Value |Description + +|`httpBindingRef` |`null` |Reference to an `org.apache.camel.component.http.HttpBinding` in the +link:registry.html[Registry]. A `HttpBinding` implementation can be used +to customize how to write a response. + +|`httpBinding` |`null` |*Camel 2.16:* Reference to an +`org.apache.camel.component.http.HttpBinding` in the +link:registry.html[Registry]. A `HttpBinding` implementation can be used +to customize how to write a response. + +|`matchOnUriPrefix` |`false` |Whether or not the `CamelServlet` should try to find a target consumer +by matching the URI prefix, if no exact match is found. + +|`servletName` |`CamelServlet` |Specifies the servlet name that the servlet endpoint will bind to. This +name should match the name you define in `web.xml` file. + +|`httpMethodRestrict` |`null` |*Camel 2.11:* *Consumer only*: Used to only allow consuming if the +HttpMethod matches, such as GET/POST/PUT etc. From *Camel 2.15*onwards +multiple methods can be specified separated by comma. +|======================================================================= + +[[SERVLET-MessageHeaders]] +Message Headers +^^^^^^^^^^^^^^^ + +Camel will apply the same Message Headers as the link:http.html[HTTP] +component. + +Camel will also populate *all* `request.parameter` and +`request.headers`. For example, if a client request has the URL, +`http://myserver/myserver?orderid=123`, the exchange will contain a +header named `orderid` with the value 123. + +[[SERVLET-Usage]] +Usage +^^^^^ + +You can consume only from endpoints generated by the Servlet component. +Therefore, it should be used only as input into your Camel routes. To +issue HTTP requests against other HTTP endpoints, use the +link:http.html[HTTP Component] + +[[SERVLET-PuttingCamelJARsintheappserverbootclasspath]] +Putting Camel JARs in the app server boot classpath +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you put the Camel JARs such as `camel-core`, `camel-servlet`, etc. in +the boot classpath of your application server (eg usually in its lib +directory), then mind that the servlet mapping list is now shared +between multiple deployed Camel application in the app server. + +Mind that putting Camel JARs in the boot classpath of the application +server is generally not best practice! + +So in those situations you *must* define a custom and unique servlet +name in each of your Camel application, eg in the `web.xml` define: + +[source,xml] +--------------------------------------------------------------------------------------------- +<servlet> + <servlet-name>MyServlet</servlet-name> + <servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class> + <load-on-startup>1</load-on-startup> +</servlet> + +<servlet-mapping> + <servlet-name>MyServlet</servlet-name> + <url-pattern>/*</url-pattern> +</servlet-mapping> +--------------------------------------------------------------------------------------------- + +And in your Camel endpoints then include the servlet name as well + +[source,xml] +--------------------------------------------------- +<route> + <from uri="servlet://foo?servletName=MyServlet"/> + ... +</route> +--------------------------------------------------- + +From *Camel 2.11* onwards Camel will detect this duplicate and fail to +start the application. You can control to ignore this duplicate by +setting the servlet init-parameter ignoreDuplicateServletName to true as +follows: + +[source,xml] +----------------------------------------------------------------------------------------------- + <servlet> + <servlet-name>CamelServlet</servlet-name> + <display-name>Camel Http Transport Servlet</display-name> + <servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class> + <init-param> + <param-name>ignoreDuplicateServletName</param-name> + <param-value>true</param-value> + </init-param> + </servlet> +----------------------------------------------------------------------------------------------- + +But its *strongly advised* to use unique servlet-name for each Camel +application to avoid this duplication clash, as well any unforeseen +side-effects. + +[[SERVLET-Sample]] +Sample +^^^^^^ + +INFO: From Camel 2.7 onwards it's easier to use link:servlet.html[Servlet] in +Spring web applications. See link:servlet-tomcat-example.html[Servlet +Tomcat Example] for details. + +In this sample, we define a route that exposes a HTTP service at +`http://localhost:8080/camel/services/hello`. + + First, you need to publish the +http://svn.apache.org/repos/asf/camel/trunk/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/CamelHttpTransportServlet.java[CamelHttpTransportServlet] +through the normal Web Container, or OSGi Service. + + Use the `Web.xml` file to publish the +http://svn.apache.org/repos/asf/camel/trunk/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/CamelHttpTransportServlet.java[CamelHttpTransportServlet] +as follows: + +Then you can define your route as follows: + +NOTE: *Specify the relative path for camel-servlet endpoint* +Since we are binding the Http transport with a published servlet, and we +don't know the servlet's application context path, the `camel-servlet` +endpoint uses the relative path to specify the endpoint's URL. A client +can access the `camel-servlet` endpoint through the servlet publish +address: `("http://localhost:8080/camel/services";) + RELATIVE_PATH("/hello")`. + +[[SERVLET-SamplewhenusingSpring3.x]] +Sample when using Spring 3.x +++++++++++++++++++++++++++++ + +See link:servlet-tomcat-example.html[Servlet Tomcat Example] + +[[SERVLET-SamplewhenusingSpring2.x]] +Sample when using Spring 2.x +++++++++++++++++++++++++++++ + +When using the Servlet component in a Camel/Spring application it's +often required to load the Spring ApplicationContext _after_ the Servlet +component has started. This can be accomplished by using Spring's +`ContextLoaderServlet` instead of `ContextLoaderListener`. In that case +you'll need to start `ContextLoaderServlet` after +http://svn.apache.org/repos/asf/camel/trunk/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/CamelHttpTransportServlet.java[CamelHttpTransportServlet] +like this: + +[source,xml] +------------------------------------------------------------------------- + +<web-app> + <servlet> + <servlet-name>CamelServlet</servlet-name> + <servlet-class> + org.apache.camel.component.servlet.CamelHttpTransportServlet + </servlet-class> + <load-on-startup>1</load-on-startup> + </servlet> + <servlet> + <servlet-name>SpringApplicationContext</servlet-name> + <servlet-class> + org.springframework.web.context.ContextLoaderServlet + </servlet-class> + <load-on-startup>2</load-on-startup> + </servlet> +<web-app> +------------------------------------------------------------------------- + +[[SERVLET-SamplewhenusingOSGi]] +Sample when using OSGi +++++++++++++++++++++++ + +From *Camel 2.6.0*, you can publish the +http://svn.apache.org/repos/asf/camel/trunk/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/CamelHttpTransportServlet.java[CamelHttpTransportServlet] +as an OSGi service with help of SpringDM like this. + +Then use this service in your camel route like this: + +For versions prior to Camel 2.6 you can use an `Activator` to publish +the +http://svn.apache.org/repos/asf/camel/trunk/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/CamelHttpTransportServlet.java[CamelHttpTransportServlet] +on the OSGi platform + +[[SERVLET-SeeAlso]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + +* link:servlet-tomcat-example.html[Servlet Tomcat Example] +* link:servlet-tomcat-no-spring-example.html[Servlet Tomcat No Spring +Example] +* link:http.html[HTTP] +* link:jetty.html[Jetty] + http://git-wip-us.apache.org/repos/asf/camel/blob/6f404e73/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 998a0a2..d8a638c 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -232,6 +232,7 @@ * [SCR](camel-and-scr.adoc) * [Script](script.adoc) * [Servicenow](servicenow.adoc) + * [Servlet](servlet.adoc) * [SJMS](sjms.adoc) * [SJMS Batch](sjms-batch.adoc) * [Telegram](telegram.adoc)
