Chapter 5. Deploying an Apache Camel Servlet Endpoint

Abstract

This tutorial describes how to deploy a Camel application, which is implemented using the Camel servlet component. The Camel application gets installed into the Web server as a servlet, receiving messages through the servlet endpoint which are then processed in a Camel route.

5.1. Apache Camel Servlet Example

Overview

Important
For deploying Apache Camel applications in JBoss EAP, consider using the Camel on EAP subsystem instead. The Camel on EAP subsystem is easier to use and provides tighter integration with the JBoss EAP container. For details, see Chapter 2, Apache Camel on Red Hat JBoss EAP.
Figure 5.1, “Camel Servlet Example Deployed in a Web Server” gives an overview of the Camel servlet example deployed in a Web server, which lets you see how the servlet's URL is constructed from settings at different configuration layers. The Web server's host and port, the WAR file name, the url-pattern setting from web.xml, and the endpoint URI of the Camel servlet endpoint are combined to give the URL, http://localhost:8080/camel-example-servlet-tomcat-2.15.1.redhat-621084/camel/hello.

Figure 5.1. Camel Servlet Example Deployed in a Web Server

camel-example-servlet-tomcat example

The code for this example is available from the standard Apache Camel distribution, under the examples/camel-example-servlet-tomcat directory. For details of how to install the Apache Camel distribution, see the section called “Install Apache Camel”.

Camel servlet component

The Camel servlet component is used to process incoming HTTP requests, where the HTTP endpoint is bound to a published servlet. The servlet component is implemented by the following servlet class: 
org.apache.camel.component.servlet.CamelHttpTransportServlet
To create a Camel servlet endpoint in a Camel route, define a servlet endpoint URI with the following syntax: 
servlet://RelativePath[?Options]
Where RelativePath specifies the tail segment of the HTTP URL path for this servlet.

web.xml file

To deploy the Apache Camel servlet example, you must provide a properly configured web.xml file. In the camel-example-servlet-tomcat project, the web.xml file is stored at the following location: 
camel-example-servlet-tomcat/src/main/webapp/WEB-INF/web.xml
Example 5.1, “web.xml File for the camel-example-servlet-tomcat Example” shows the contents of the web.xml file.

Example 5.1. web.xml File for the camel-example-servlet-tomcat Example

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

  <display-name>My Web Application</display-name>

  <!-- location of spring xml files -->
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>classpath:camel-config.xml</param-value>
  </context-param>

  <!-- the listener that kick-starts Spring -->
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>

  <!-- Camel servlet -->
  <servlet>
    <servlet-name>CamelServlet</servlet-name>
    <servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <!-- Camel servlet mapping -->
  <servlet-mapping>
    <servlet-name>CamelServlet</servlet-name>
    <url-pattern>/camel/*</url-pattern>
  </servlet-mapping>

</web-app>
The key settings in the preceding web.xml file are:
servlet/servlet-class
Specifies the org.apache.camel.component.servlet.CamelHttpTransportServlet class, which implements the Camel servlet component.
servlet-mapping/url-pattern
Determines which URLs are routed to this servlet. In general, the servlet URL has the following form: 
http://Host:Port/WARFileName/URLPattern
Where the base URL, http://Host:Port, is determined by the configuration of the Web server, the WARFileName is the root of the WARFileName.war WAR file, and the URLPattern is specified by the contents of the url-pattern element.
Assuming that the Web server port is set to 8080, the camel-example-servlet-tomcat example servlet will match URLs of the following form: 
http://localhost:8080/camel-example-servlet-tomcat-2.15.1.redhat-621084/camel/*
listener/listener-class
This element launches the Spring container.
context-param
This element specifies the location of the Spring XML file, camel-config.xml, in the WAR. The Spring container will read this parameter and load the specified Spring XML file, which contains the definition of the Camel route.

Example Camel route

Example 5.2, “Route Definition for the Camel Servlet Example” shows the Camel route for this example, defined in a Spring XML file, using Camel's XML DSL syntax.

Example 5.2. Route Definition for the Camel Servlet Example

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xsi:schemaLocation="
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
         http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

  <camelContext xmlns="http://camel.apache.org/schema/spring">

    <route>
      <!-- incoming requests from the servlet is routed -->
      <from uri="servlet:///hello"/>
      <choice>
        <when>
          <!-- is there a header with the key name? -->
          <header>name</header>
          <!-- yes so return back a message to the user -->
          <transform>
            <simple>Hello ${header.name} how are you?</simple>
          </transform>
        </when>
        <otherwise>
          <!-- if no name parameter then output a syntax to the user -->
          <transform>
            <constant>Add a name parameter to uri, eg ?name=foo</constant>
          </transform>
        </otherwise>
      </choice>
    </route>

  </camelContext>

</beans>
Because the servlet URL, servlet:///hello, specifies the relative path, /hello, the complete URL to access this servlet is the following: 
http://localhost:8080/camel-example-servlet-tomcat-2.15.1.redhat-621084/camel/hello