Deploying into a Web Server
Deploying Apache CXF and Apache Camel applications into an Enterprise Web Services container or an Enterprise Application Platform container
Copyright © 2011-2014 Red Hat, Inc. and/or its affiliates.
Abstract
Chapter 1. Overview of JBoss Fuse Deployment
Abstract
1.1. Supported Web Server Platforms
Overview
- JBoss Enterprise Web Server (JBoss EWS)
- JBoss Enterprise Application Platform (JBoss EAP)
Supported product versions
1.2. WAR Build and Deployment Model
How to install Fuse libraries
Build model
Figure 1.1. Building the WAR with Maven
Maven POM file
pom.xml, which is typically used to configure the following aspects of the build:
- The packaging type to be
war(which instructs Maven to build a WAR file). - Dependent JAR files, which will be bundled with the WAR (including the requisite JBoss Fuse libraries).
- The name of the WAR file.
Build process
Deployment
Chapter 2. Building a WAR
Abstract
2.1. Preparing to use Maven
Overview
Prerequisites
- Maven installation—Maven is a free, open source build tool from Apache. You can download the latest version from the Maven download page.
- Network connection—whilst performing a build, Maven dynamically searches external repositories and downloads the required artifacts on the fly. By default, Maven looks for repositories that are accessed over the Internet. You can change this behavior so that Maven will prefer searching repositories that are on a local network.NoteMaven can run in an offline mode. In offline mode Maven will only look for artifacts in its local repository.
Adding the Red Hat JBoss Fuse repository
settings.xml file. Maven looks for your settings.xml file in the .m2 directory of the user's home directory. If there is not a user specified settings.xml file, Maven will use the system-level settings.xml file at M2_HOME/conf/settings.xml.
.m2/settings.xml file or modify the system-level settings. In the settings.xml file, add the repository element for the JBoss Fuse repository as shown in bold text in Example 2.1, “Adding the Red Hat JBoss Fuse Repositories to Maven”.
Example 2.1. Adding the Red Hat JBoss Fuse Repositories to Maven
<settings>
<profiles>
<profile>
<id>my-profile</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>fusesource</id>
<url>http://repo.fusesource.com/nexus/content/groups/public/</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
</releases>
</repository> <repository>
<id>fusesource.snapshot</id>
<url>http://repo.fusesource.com/nexus/content/groups/public-snapshots/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>false</enabled>
</releases>
</repository>
<repository>
<id>apache-public</id>
<url>https://repository.apache.org/content/groups/public/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
</releases>
</repository>
...
</repositories>
</profile>
</profiles>
...
</settings>fusesource-snapshotrepository—if you want to experiment with building your application using an Red Hat JBoss Fuse snapshot kit, you can include this repository.apache-publicrepository—you might not always need this repository, but it is often useful to include it, because JBoss Fuse depends on many of the artifacts from Apache.
Artifacts
Maven coordinates
{groupId, artifactId, version}. Sometimes Maven augments the basic set of coordinates with the additional coordinates, packaging and classifier. A tuple can be written with the basic coordinates, or with the additional packaging coordinate, or with the addition of both the packaging and classifier coordinates, as follows:
groupdId:artifactId:version groupdId:artifactId:packaging:version groupdId:artifactId:packaging:classifier:version
- groupdId
- Defines a scope for the name of the artifact. You would typically use all or part of a package name as a group ID—for example,
org.fusesource.example. - artifactId
- Defines the artifact name (relative to the group ID).
- version
- Specifies the artifact's version. A version number can have up to four parts:
n.n.n.n, where the last part of the version number can contain non-numeric characters (for example, the last part of1.0-SNAPSHOTis the alphanumeric substring,0-SNAPSHOT). - packaging
- Defines the packaged entity that is produced when you build the project. For OSGi projects, the packaging is
bundle. The default value isjar. - classifier
- Enables you to distinguish between artifacts that were built from the same POM, but have different content.
<project ... > ... <groupId>org.fusesource.example</groupId> <artifactId>bundle-demo</artifactId> <packaging>bundle</packaging> <version>1.0-SNAPSHOT</version> ... </project>
dependency element to a POM:
<project ... >
...
<dependencies>
<dependency>
<groupId>org.fusesource.example</groupId>
<artifactId>bundle-demo</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
</dependencies>
...
</project>bundle package type in the preceding dependency, because a bundle is just a particular kind of JAR file and jar is the default Maven package type. If you do need to specify the packaging type explicitly in a dependency, however, you can use the type element.
2.2. Modifying an Existing Maven Project
Overview
Change the package type to WAR
war in your project's pom.xml file. Change the contents of the packaging element to war, as shown in the following example:
<project ... >
...
<packaging>war</packaging>
...
</project>maven-war-plugin, to perform packaging for this project.
Customize the JDK compiler version
JAVA_HOME and the PATH environment variables to the correct values for your JDK, you must also modify the POM file.
maven-compiler-plugin plug-in settings to your POM (if they are not already present):
<project ... >
...
<build>
<defaultGoal>install</defaultGoal>
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
</plugins>
</build>
...
</project>Store resources under webapp/WEB-INF
/WEB-INF directory in the standard WAR directory layout. In order to ensure that these resources are copied into the root of the generated WAR package, store the WEB-INF directory under ProjectDir/src/main/webapp in the Maven directory tree, as follows:
ProjectDir/
pom.xml
src/
main/
webapp/
WEB-INF/
web.xml
classes/
lib/web.xml file is stored at ProjectDir/src/main/webapp/WEB-INF/web.xml.
Customize the Maven WAR plug-in
plugins section of the pom.xml file. Most of the configuration options are concerned with adding additonal resources to the WAR package. For example, to include all of the resources under the src/main/resources directory (specified relative to the location of pom.xml) in the WAR package, you could add the following WAR plug-in configuration to your POM:
<project ...>
...
<build>
...
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>2.1.1</version>
<configuration>
<!-- Optionally specify where the web.xml file comes from -->
<webXml>src/main/webapp/WEB-INF/web.xml</webXml>
<!-- Optionally specify extra resources to include -->
<webResources>
<resource>
<directory>src/main/resources</directory>
<targetPath>WEB-INF</targetPath>
<includes>
<include>**/*</include>
</includes>
</resource>
</webResources>
</configuration>
</plugin>
...
</plugins>
</build>
</project>webXml- Specifies where to find the
web.xmlfile in the current Maven project, relative to the location ofpom.xml. The default issrc/main/webapp/WEB-INF/web.xml. webResources- Specifies additional resource files that are to be included in the generated WAR package. It can contain the following sub-elements:
webResources/resource—each resource elements specifies a set of resource files to include in the WAR.webResources/resource/directory—specifies the base directory from which to copy resource files, where this directory is specified relative to the location ofpom.xml.webResources/resource/targetPath—specifies where to put the resource files in the generated WAR package.webResources/resource/includes—uses an Ant-style wildcard pattern to specify explicitly which resources should be included in the WAR.webResources/resource/excludes—uses an Ant-style wildcard pattern to specify explicitly which resources should be excluded from the WAR (exclusions have priority over inclusions).
maven-war-plugin plug-in, which has a bug that causes two copies of the web.xml file to be inserted into the generated .war file.
Building the WAR
pom.xml file), and enter the following Maven command:
mvn install
ProjectDir/target directory, and then to install the generated WAR in the local Maven repository.
2.3. Bootstrapping a CXF Servlet in a WAR
Overview
web.xml to use the standard CXF servlet, org.apache.cxf.transport.servlet.CXFServlet.
Example
web.xml file shows how to configure the CXF servlet, where all Web service addresses accessed through this servlet would be prefixed by /services/ (as specified by the value of servlet-mapping/url-pattern):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>cxf</display-name>
<description>cxf</description>
<servlet>
<servlet-name>cxf</servlet-name>
<display-name>cxf</display-name>
<description>Apache CXF Endpoint</description>
<servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>cxf</servlet-name>
<url-pattern>/services/*</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>60</session-timeout>
</session-config>
</web-app>cxf-servlet.xml file
web.xml file, it is also necessary to configure your Web services by defining a cxf-servlet.xml file, which must be copied into the root of the generated WAR.
cxf-servlet.xml in the default location, you can customize its name and location, by setting the contextConfigLocation context parameter in the web.xml file. For example, to specify that Apache CXF configuration is located in WEB-INF/cxf-servlet.xml, set the following context parameter in web.xml:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
...
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>WEB-INF/cxf-servlet.xml</param-value>
</context-param>
...
</web-app>Reference
2.4. Bootstrapping a Spring Context in a WAR
Overview
Bootstrapping a Spring context in a WAR
web.xml file shows how to boot up a Spring application context that is initialized by the XML file, /WEB-INF/applicationContext.xml (which is the location of the context file in the generated WAR package):
<?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>Camel Routes</display-name>
<!-- location of spring xml files -->
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/applicationContext.xml</param-value>
</context-param>
<!-- the listener that kick-starts Spring -->
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
</web-app>Maven dependency
ContextLoaderListener class from the Spring framework, you must add the following dependency to your project's pom.xml file:
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
<version>${spring-version}</version>
</dependency>spring-version property specifies the version of the Spring framework you are using.
Chapter 3. Deploying an Apache CXF Web Service
Abstract
3.1. Apache CXF Example
Overview
url-pattern setting from web.xml, and the address attribute of the Web services endpoint are combined to give the URL, http://localhost:8080/wsdl_first/services/CustomerServicePort.
Figure 3.1. Example Web Service Deployed in a Web Server
wsdl_first sample
samples/wsdl_first directory. For details of how to install the Apache CXF distribution, see the section called “Install Apache CXF”.
web.xml file
web.xml file. In the wsdl_first project, the web.xml file is stored at the following location:
wsdl_first/src/main/webapp/WEB-INF/web.xml
web.xml file.
Example 3.1. web.xml File for the wsdl_first Example
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<display-name>cxf</display-name>
<servlet>
<servlet-name>cxf</servlet-name>
<display-name>cxf</display-name>
<description>Apache CXF Endpoint</description>
<servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>cxf</servlet-name>
<url-pattern>/services/*</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>60</session-timeout>
</session-config>
</web-app>web.xml file are:
- Servlet class—specifies the
org.apache.cxf.transport.servlet.CXFServletclass, which implements a special servlet that integrates with Web services. - 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, theWARFileNameis the root of theWARFileName.warWAR file, and theURLPatternis specified by the contents of theurl-patternelement.Assuming that the Web server port is set to 8080, thewsdl_firstexample servlet will match URLs of the following form:http://localhost:8080/wsdl_first/services/*
Implied Spring container
CXFServlet automatically creates and starts up a Spring container, which you can then use for defining Web service endpoints. By default, this Spring container automatically loads the following XML file in the WAR:
WEB-INF/cxf-servlet.xml
wsdl_first example project, this file is stored at the following location:
wsdl_first/src/main/webapp/WEB-INF/cxf-servlet.xml
cxf-servlet.xml file
cxf-servlet.xml file is primarily used to create Web service endpoints, which represent the Web services exposed through the Web server. Apache CXF provides a convenient and flexible syntax for defining Web service endpoints in XML and you can use this flexible syntax to define endpoints in cxf-servlet.xml.
cxf-servlet.xml file, which creates a single CustomerService endpoint, using the jaxws:endpoint element.
Example 3.2. Spring Configuration for the wsdl_first 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:jaxws="http://cxf.apache.org/jaxws"
xmlns:soap="http://cxf.apache.org/bindings/soap"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd
http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">
<jaxws:endpoint
xmlns:customer="http://customerservice.example.com/"
id="CustomerServiceHTTP"
address="/CustomerServicePort"
serviceName="customer:CustomerServiceService"
endpointName="customer:CustomerServicePort"
implementor="com.example.customerservice.server.CustomerServiceImpl">
<!--jaxws:properties>
<entry key="schema-validation-enabled" value="true" />
</jaxws:properties-->
</jaxws:endpoint>
</beans>address attribute of the jaxws:endpoint specifies the final segment of the Web service's URL. When you put together all of the settings from the Web server, the web.xml file, and the cxf-server.xml file, you obtain the following URL for this Web service endpoint:
http://localhost:8080/wsdl_first/services/CustomerServicePort
WSDL address configuration
web.xml, and the Spring configuration, cxf-servlet.xml, it is also necessary to ensure that the SOAP address in the WSDL contract is correctly specified, so that it matches the URL for this Web service.
wsdl_first example, the WSDL contract is located in the following file:
wsdl_first/src/main/resources/CustomerService.wsdl
location attribute of the soap:address element must be set to the correct Web service URL, as shown in Example 3.3, “Address in the WSDL CustomerService Contract”.
Example 3.3. Address in the WSDL CustomerService Contract
<?xml version="1.0" encoding="UTF-8"?>
...
<wsdl:definitions name="CustomerServiceService" targetNamespace="http://customerservice.example.com/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://customerservice.example.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
...
<wsdl:service name="CustomerServiceService">
<wsdl:port name="CustomerServicePort" binding="tns:CustomerServiceServiceSoapBinding">
<!-- embedded deployment -->
<!--soap:address location="http://localhost:9090/CustomerServicePort"/-->
<!-- standalone Tomcat deployment -->
<soap:address location="http://localhost:8080/wsdl_first/services/CustomerServicePort"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>3.2. Deploy the Apache CXF Example
Overview
wsdl_first example) and shows you how to deploy it into a Web server, by packaging the application as a WAR. In this example, the Web service is implemented by binding the service to a Java class with the JAX-WS mapping.
Prerequisites
- Either of the following Web servers are installed:
- JBoss Enterprise Web Server, or
- JBoss Enterprise Application Platform
- Java version 1.6 or later is installed.
- Apache Maven 3.0.0 or later is installed.
- Maven is configured to access the JBoss Fuse repositories, as described in Section 2.1, “Preparing to use Maven”.
- You have access to the Internet, so that Maven can download dependencies from remote repositories.
Install Apache CXF
wsdl_first example, you need to install the Apache CXF kit, apache-cxf-2.7.0.redhat-610379.zip, provided in the extras/ directory of the JBoss Fuse installation.
- Find the Apache CXF kit at the following location:
InstallDir/extras/apache-cxf-2.7.0.redhat-610379.zip
- Using a suitable archive utility on your platform, unzip the
apache-cxf-2.7.0.redhat-610379.zipfile and extract it to a convenient location,CXFInstallDir.
The wsdl_first example
wsdl_first example is located under the following sub-directory of the Apache CXF installation:
CXFInstallDir/samples/wsdl_first/
Build and run the example
wsdl_first example, perform the following steps:
- Using your favorite text editor, open the
CustomerService.wsdlfile, which can be found in the following location in thewsdl_firstproject:wsdl_first/src/main/resources/CustomerService.wsdl
Edit thesoap:addresselement in the WSDL contract, removing comments around the element labeledstandalone Tomcat deploymentand inserting comments around the element labeledembedded deployment. When you are finished editing, thesoap:addresselement should be look as follows:<?xml version="1.0" encoding="UTF-8"?> ... <wsdl:definitions name="CustomerServiceService" targetNamespace="http://customerservice.example.com/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://customerservice.example.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"> ... <wsdl:service name="CustomerServiceService"> <wsdl:port name="CustomerServicePort" binding="tns:CustomerServiceServiceSoapBinding"> <!-- embedded deployment --> <!--soap:address location="http://localhost:9090/CustomerServicePort"/--> <!-- standalone Tomcat deployment --> <soap:address location="http://localhost:8080/wsdl_first/services/CustomerServicePort"/> </wsdl:port> </wsdl:service> </wsdl:definitions> - Build the
wsdl_firstexample using Maven. Change directory to theCXFInstallDir/samples/wsdl_firstdirectory, open a command prompt, and enter the following command at the command line:mvn clean package
If this command executes successfully, you should be able to find the WAR file,wsdl_first.war, under thewsdl_first/targetsub-directory. - Make sure that the Web server is already running (a simple way to test this is to enter the URL,
http://localhost:8080, into your browser). If you need to start the Web server, you can typically do this from the command line. The command to start the Web server depends on the particular product you are using, as follows:- JBoss Enterprise Web Server (EWS)—open a new command prompt and execute the
startup.shscript from thetomcat7/bin/directory (or thetomcat6/bin/directory, as appropriate). For more details about how to configure and launch the EWS, see the Installation Guide from the JBoss Enterprise Web Server library. - JBoss Enterprise Application Platform (EAP)—for a standalone instance, open a new command prompt and execute the
bin/standalone.shscript. For more details about how to configure and launch the EAP, see the Administration and Configuration Guide from the JBoss Enterprise Application Platform library.
- Deploy the
wsdl_firstexample to the running Web server. Manually copy thewsdl_first.warWAR file from thewsdl_first/targetdirectory to the Web server's deployment directory, as follows:- JBoss Enterprise Web Server (EWS)—copy the
wsdl_first.warWAR file to thetomcat7/webappsdirectory (ortomcat6/webappsdirectory, as appropriate). - JBoss Enterprise Application Platform (EAP)—copy the
wsdl_first.warWAR file to thestandalone/deploymentsdirectory.
- Use a Web browser to query the WSDL contract from the newly deployed Web service. Navigate to the following URL in your browser:
http://localhost:8080/wsdl_first/services/CustomerServicePort?wsdl
NoteThis step might not work in the Safari browser. - Run the test client against the deployed Web service. Change directory to the
CXFInstallDir/samples/wsdl_firstdirectory, open a command prompt, and enter the following command at the command line:mvn -Pclient
If the client runs successfully, you should see some output like the following in your command window:... Sending request for customers named Smith Response received Did not find any matching customer for name=None NoSuchCustomer exception was received as expected All calls were successful
Chapter 4. Deploying an Apache Camel Servlet Endpoint
Abstract
4.1. Apache Camel Servlet Example
Overview
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.12.0.redhat-610379/camel/hello.
Figure 4.1. Camel Servlet Example Deployed in a Web Server
camel-example-servlet-tomcat example
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
org.apache.camel.component.servlet.CamelHttpTransportServlet
servlet://RelativePath[?Options]
RelativePath specifies the tail segment of the HTTP URL path for this servlet.
web.xml file
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
web.xml file.
Example 4.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>web.xml file are:
servlet/servlet-class- Specifies the
org.apache.camel.component.servlet.CamelHttpTransportServletclass, 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, theWARFileNameis the root of theWARFileName.warWAR file, and theURLPatternis specified by the contents of theurl-patternelement.Assuming that the Web server port is set to 8080, thecamel-example-servlet-tomcatexample servlet will match URLs of the following form:http://localhost:8080/camel-example-servlet-tomcat-2.12.0.redhat-610379/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 4.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>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.12.0.redhat-610379/camel/hello
4.2. Deploy the Apache Camel Servlet
Overview
camel-example-servlet-tomcat example) and shows you how to deploy it into a Web server, by packaging the application as a WAR.
Prerequisites
- Either of the following Web servers are installed:
- JBoss Enterprise Web Server, or
- JBoss Enterprise Application Platform
- Java version 1.6 or later is installed.
- Apache Maven 3.0.0 or later is installed.
- Maven is configured to access the JBoss Fuse repositories, as described in Section 2.1, “Preparing to use Maven”.
- You have access to the Internet, so that Maven can download dependencies from remote repositories.
Install Apache Camel
camel-example-servlet-tomcat example, you need to install the Apache Camel kit, apache-camel-2.12.0.redhat-610379.zip, provided in the extras/ directory of the JBoss Fuse installation.
- Find the Apache Camel kit at the following location:
InstallDir/extras/apache-camel-2.12.0.redhat-610379.zip
- Using a suitable archive utility on your platform, unzip the
apache-camel-2.12.0.redhat-610379.zipfile and extract it to a convenient location,CamelInstallDir.
The camel-example-servlet-tomcat example
camel-example-servlet-tomcat example is located under the following sub-directory of the Apache Camel installation:
CamelInstallDir/examples/camel-example-servlet-tomcat/
Build and run the example
camel-example-servlet-tomcat example, perform the following steps:
- Build the
camel-example-servlet-tomcatexample using Maven. Change directory to theCamelInstallDir/examples/camel-example-servlet-tomcat/directory, open a command prompt, and enter the following command at the command line:mvn package
If this command executes successfully, you should be able to find the WAR file,camel-example-servlet-tomcat-2.12.0.redhat-610379.war, under thecamel-example-servlet-tomcat/targetsub-directory. - Make sure that the Web server is already running (a simple way to test this is to enter the URL,
http://localhost:8080, into your browser). If you need to start the Web server, you can typically do this from the command line. The command to start the Web server depends on the particular product you are using, as follows:- JBoss Enterprise Web Server (EWS)—open a new command prompt and execute the
startup.shscript from thetomcat7/bin/directory (or thetomcat6/bin/directory, as appropriate). For more details about how to configure and launch the EWS, see the Installation Guide from the JBoss Enterprise Web Server library. - JBoss Enterprise Application Platform (EAP)—for a standalone instance, open a new command prompt and execute the
bin/standalone.shscript. For more details about how to configure and launch the EAP, see the Administration and Configuration Guide from the JBoss Enterprise Application Platform library.
- Deploy the
camel-example-servlet-tomcatexample to the running Web server. Manually copy thecamel-example-servlet-tomcat-2.12.0.redhat-610379.warWAR file from thecamel-example-servlet-tomcat/targetdirectory to the Web server's deployment directory, as follows:- JBoss Enterprise Web Server (EWS)—copy the
camel-example-servlet-tomcat-2.12.0.redhat-610379.warWAR file to thetomcat7/webappsdirectory (ortomcat6/webappsdirectory, as appropriate). - JBoss Enterprise Application Platform (EAP)—copy the
camel-example-servlet-tomcat-2.12.0.redhat-610379.warWAR file to thestandalone/deploymentsdirectory.
- Navigate to the following URL in your browser:
http://localhost:8080/camel-example-servlet-tomcat-2.12.0.redhat-610379/
When the page loads, you should see the following text in your browser window:
- Click the highlighted link in the line
To get started click this link.and follow the on-screen instructions to test the servlet.
Chapter 5. Deploying an Apache Camel WS Endpoint
Abstract
5.1. Apache Camel CXF Example
Overview
url-pattern setting from web.xml, and the URI of the Camel CXF endpoint are combined to give the URL, http://localhost:8080/camel-example-cxf-tomcat/webservices/incident.
Figure 5.1. Camel CXF Example Deployed in a Web Server
camel-example-cxf-tomcat example
examples/camel-example-cxf-tomcat directory. For details of how to install the Apache Camel distribution, see the section called “Install Apache Camel”.
Camel CXF component
Exchange object, and can then propagate through the route.
cxf:Address[?Options]- Specifies the WSDL endpoint address and a (potentially large) number of options to configure the endpoint.
cxf:bean:BeanID[?Options]- References a bean with the ID,
BeanID, defined using thecxf:cxfEndpointelement (where thecxfprefix is bound to thehttp://camel.apache.org/schema/cxfnamespace). The advantage of this approach is that all of the configuration complexity is encapsulated in the bean. Typically, this means that very few options (or none) need to be specified on the endpoint URI.NoteThecxf:cxfEndpointelement, which binds a WS endpoint to a Camel route, should not be confused with thejaxws:endpointelement, which binds a WS endpoint directly to a Java class.
More about the Camel CXF component
- Web Services and Routing with Camel CXF
- The CXF chapter from the EIP Component Reference.
web.xml file
web.xml file. In the camel-example-cxf-tomcat project, the web.xml file is stored at the following location:
camel-example-cxf-tomcat/src/main/webapp/WEB-INF/web.xml
web.xml file.
Example 5.1. web.xml File for the camel-example-cxf-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>
<!-- CXF servlet -->
<servlet>
<servlet-name>CXFServlet</servlet-name>
<servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
<load-on-startup>1</load-on-startup>
<!-- If you want to leverage the Servlet3's async feature in Tomcat,
please enable this feature
<async-supported>true</async-supported>
-->
</servlet>
<!-- all our webservices are mapped under this URI pattern -->
<servlet-mapping>
<servlet-name>CXFServlet</servlet-name>
<url-pattern>/webservices/*</url-pattern>
</servlet-mapping>
</web-app>web.xml file are:
servlet/servlet-class- Specifies the
org.apache.cxf.transport.servlet.CXFServletclass, which implements a special servlet that enables you to deploy Apache CXF WS endpoints. 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, theWARFileNameis the root of theWARFileName.warWAR file, and theURLPatternis specified by the contents of theurl-patternelement.Assuming that the Web server port is set to 8080, thecamel-example-cxf-tomcatexample servlet will match URLs of the following form:http://localhost:8080/camel-example-cxf-tomcat/webservices/*
listener/listener-class- This element launches a 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.
listener-class element here, because the CXFServlet class already creates its own Spring container. If you put the Spring XML file in the location expected by the CXFServlet class (that is, WEB-INF/cxf-servlet.xml) instead of the location used by this example (that is, WEB-INF/classes/camel-config.xml), you could remove the Spring container settings from this web.xml file.
Spring XML file
camel-config.xml, contains the following XML code:
<?xml version="1.0" encoding="UTF-8"?>
<beans ...>
<import resource="classpath:META-INF/cxf/cxf.xml"/>
<bean id="myRoutes" class="org.apache.camel.example.cxf.CamelRoute"/>
<camelContext xmlns="http://camel.apache.org/schema/spring">
<routeBuilder ref="myRoutes"/>
</camelContext>
</beans>RouteBuilder class is defined in the Java class, org.apache.camel.example.cxf.CamelRoute.
Camel route class
Example 5.2. Route Definitions in the CamelRoute Class
// Java
package org.apache.camel.example.cxf;
import org.apache.camel.Exchange;
import org.apache.camel.Processor;
import org.apache.camel.builder.RouteBuilder;
import org.apache.camel.example.cxf.incident.IncidentService;
import org.apache.camel.example.cxf.incident.InputReportIncident;
import org.apache.camel.example.cxf.incident.OutputReportIncident;
import org.apache.camel.example.cxf.incident.OutputStatusIncident;
// this static import is needed for older versions of Camel than 2.5
// import static org.apache.camel.language.simple.SimpleLanguage.simple;
public class CamelRoute extends RouteBuilder {
// CXF webservice using code first approach
private String uri = "cxf:/incident?serviceClass=" + IncidentService.class.getName();
@Override
public void configure() throws Exception {
from(uri)
.to("log:input")
// send the request to the route to handle the operation
// the name of the operation is in that header
.recipientList(simple("direct:${header.operationName}"));
// report incident
from("direct:reportIncident")
.process(new Processor() {
public void process(Exchange exchange) throws Exception {
// get the id of the input
String id = exchange.getIn().getBody(InputReportIncident.class).getIncidentId();
// set reply including the id
OutputReportIncident output = new OutputReportIncident();
output.setCode("OK;" + id);
exchange.getOut().setBody(output);
}
})
.to("log:output");
// status incident
from("direct:statusIncident")
.process(new Processor() {
public void process(Exchange exchange) throws Exception {
// set reply
OutputStatusIncident output = new OutputStatusIncident();
output.setStatus("IN PROGRESS");
exchange.getOut().setBody(output);
}
})
.to("log:output");
}
}from(uri) DSL command). The Camel CXF endpoint is defined using the following endpoint URI:
cxf:/incident?serviceClass=org.apache.camel.example.cxf.incident.IncidentService
IncidentService class in this URI. The relative path, /incident, defines the tail of the servlet URL for this Web service. Hence, the full servlet URL for the Web service is the following:
http://localhost:8080/camel-example-cxf-tomcat/webservices/incidentserviceClass option specifies the name of the Service Endpoint Interface (SEI) for this Web service. By default, the CXF endpoint is set up to use the POJO mode, using the SEI to check the syntax of incoming messages.
5.2. Deploy the Apache Camel CXF Example
Overview
camel-example-cxf-tomcat example) and shows you how to deploy it into a Web server, by packaging the application as a WAR. In this example, the Web service is implemented by binding the service to a Camel route using the Camel CXF component.
Prerequisites
- Either of the following Web servers are installed:
- JBoss Enterprise Web Server, or
- JBoss Enterprise Application Platform
- Java version 1.6 or later is installed.
- Apache Maven 3.0.0 or later is installed.
- Maven is configured to access the JBoss Fuse repositories, as described in Section 2.1, “Preparing to use Maven”.
- You have access to the Internet, so that Maven can download dependencies from remote repositories.
Install Apache Camel
camel-example-cxf-tomcat example, you need to install the Apache Camel kit, apache-camel-2.12.0.redhat-610379.zip, provided in the extras/ directory of the JBoss Fuse installation.
- Find the Apache Camel kit at the following location:
InstallDir/extras/apache-camel-2.12.0.redhat-610379.zip
- Using a suitable archive utility on your platform, unzip the
apache-camel-2.12.0.redhat-610379.zipfile and extract it to a convenient location,CamelInstallDir.
The camel-example-cxf-tomcat example
camel-example-cxf-tomcat example is located under the following sub-directory of the Apache Camel installation:
CamelInstallDir/examples/camel-example-cxf-tomcat/
Build and run the example
camel-example-cxf-tomcat example, perform the following steps:
- Build the
camel-example-cxf-tomcatexample using Maven. Change directory to theCamelInstallDir/examples/camel-example-cxf-tomcat/directory, open a command prompt, and enter the following command at the command line:mvn clean package
If this command executes successfully, you should be able to find the WAR file,camel-example-cxf-tomcat.war, under thecamel-example-cxf-tomcat/targetsub-directory. - Make sure that the Web server is already running (a simple way to test this is to enter the URL,
http://localhost:8080, into your browser). If you need to start the Web server, you can typically do this from the command line. The command to start the Web server depends on the particular product you are using, as follows:- JBoss Enterprise Web Server (EWS)—open a new command prompt and execute the
startup.shscript from thetomcat7/bin/directory (or thetomcat6/bin/directory, as appropriate). For more details about how to configure and launch the EWS, see the Installation Guide from the JBoss Enterprise Web Server library. - JBoss Enterprise Application Platform (EAP)—for a standalone instance, open a new command prompt and execute the
bin/standalone.shscript. For more details about how to configure and launch the EAP, see the Administration and Configuration Guide from the JBoss Enterprise Application Platform library.
- Deploy the
camel-example-cxf-tomcatexample to the running Web server. Manually copy thecamel-example-cxf-tomcat.warWAR file from thecamel-example-cxf-tomcat/targetdirectory to the Web server's deployment directory, as follows:- JBoss Enterprise Web Server (EWS)—copy the
camel-example-cxf-tomcat.warWAR file to thetomcat7/webappsdirectory (ortomcat6/webappsdirectory, as appropriate). - JBoss Enterprise Application Platform (EAP)—copy the
camel-example-cxf-tomcat.warWAR file to thestandalone/deploymentsdirectory.
- Use a Web browser to query the WSDL contract from the newly deployed Web service. Navigate to the following URL in your browser:
http://localhost:8080/camel-example-cxf-tomcat/webservices/incident?wsdl
NoteThis step might not work in the Safari browser. - Run the test client against the deployed Web service. Change directory to the
CamelInstallDir/examples/camel-example-cxf-tomcat/directory, open a command prompt, and enter the following command at the command line:mvn exec:java
If the client runs successfully, you should see some output like the following in your command window:... [INFO] --- exec-maven-plugin:1.1.1:java (default-cli) @ camel-example-cxf-tomcat --- 2013-07-24 13:59:16,829 [teClient.main()] INFO ReflectionServiceFactoryBean - Creating Service {http://incident.cxf.example.camel.apache.org/}IncidentService from class org.apache.camel.example.cxf.incident.IncidentService OK;123 IN PROGRESS [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 7.445s [INFO] Finished at: Wed Jul 24 13:59:17 CEST 2013 [INFO] Final Memory: 10M/81M [INFO] ------------------------------------------------------------------------
Index
Legal Notice
Trademark Disclaimer
Legal Notice
Third Party Acknowledgements
- JLine (http://jline.sourceforge.net) jline:jline:jar:1.0License: BSD (LICENSE.txt) - Copyright (c) 2002-2006, Marc Prud'hommeaux
mwp1@cornell.eduAll rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - Stax2 API (http://woodstox.codehaus.org/StAX2) org.codehaus.woodstox:stax2-api:jar:3.1.1License: The BSD License (http://www.opensource.org/licenses/bsd-license.php)Copyright (c) <YEAR>, <OWNER> All rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - jibx-run - JiBX runtime (http://www.jibx.org/main-reactor/jibx-run) org.jibx:jibx-run:bundle:1.2.3License: BSD (http://jibx.sourceforge.net/jibx-license.html) Copyright (c) 2003-2010, Dennis M. Sosnoski.All rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of JiBX nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - JavaAssist (http://www.jboss.org/javassist) org.jboss.javassist:com.springsource.javassist:jar:3.9.0.GA:compileLicense: MPL (http://www.mozilla.org/MPL/MPL-1.1.html)
- HAPI-OSGI-Base Module (http://hl7api.sourceforge.net/hapi-osgi-base/) ca.uhn.hapi:hapi-osgi-base:bundle:1.2License: Mozilla Public License 1.1 (http://www.mozilla.org/MPL/MPL-1.1.txt)
