You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/05/24 08:06:44 UTC
camel git commit: Added camel-servlet docs to Gitbook
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 <an...@gmail.com>
Authored: Tue May 24 10:06:12 2016 +0200
Committer: Andrea Cosentino <an...@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)