Using the CXF Servlet

Overview

FUSE Services Framework provides a standard servlet, the CXF servlet, which acts as an adapter for the Web service endpoints. The CXF servlet is the easiest method for deploying Web services into a servlet container.

Figure 6.1 shows the main components of a FUSE Services Framework endpoint deployed using the CXF servlet.

Figure 6.1. FUSE Services Framework Endpoint Deployed in a Servlet Container

The deployed application includes a WAR file containing the application and the CXF servlet.

Deployed WAR file — Service providers are deployed to the servlet container in a Web Archive (WAR) file. The deployed WAR file contains:
- the compiled code for the service provider being deployed
- the WSDL file defining the service
- the FUSE Services Framework configuration file
  This file, called cxf-servlet.xml, is standard FUSE Services Framework configuration file that defines all of the endpoints contained in the WAR.
- the Web application deployment descriptor
  All FUSE Services Framework Web applications using the standard CXF servlet need to load the org.apache.cxf.transport.servlet.CXFServlet class.
CXF servlet — The CXF servlet is a standard servlet provided by FUSE Services Framework. It acts as an adapter for Web service endpoints and is part of the FUSE Services Framework runtime. The CXF servlet is implemented by the org.apache.cxf.transport.servlet.CXFServlet class.

Deployment steps

To deploy a FUSE Services Framework endpoint to a servlet container you must:

Build a WAR that contains your application and all the required support files.
Deploy the WAR file to your servlet container.

Building a WAR

To deploy your application to a servlet container, you must build a WAR file. The WAR file's WEB-INF folder should include the following:

cxf-servlet.xml — a FUSE Services Framework configuration file specifying the endpoints that plug into the CXF servlet. When the CXF servlet starts up, it reads the jaxws:endpoint elements from this file, and initializes a service endpoint for each one. See Servlet configuration file for more information.
web.xml — a standard web application file that instructs the servlet container to load the org.apache.cxf.transport.servlet.CXFServlet class.
Tip
A reference version of this file is contained in your InstallDir/etc directory. You can use this reference copy without making changes to it.
classes — a folder including your Web service implementation class and any other classes required to support the implementation.
wsdl — a folder including the WSDL file that defines the service you are deploying.
lib — a folder including any JARs required by your application.

	Tip
A reference version of this file is contained in your `InstallDir/etc` directory. You can use this reference copy without making changes to it.

Servlet configuration file

The cxf-servlet.xml file is a FUSE Services Framework configuration file that configures the endpoints that plug into the CXF servlet. When the CXF servlet starts up it reads the jaxws:endpoint elements in this file and initializes a service endpoint for each one.

Example 6.1 shows a simple cxf-servlet.xml file.

Example 6.1. CXF Servlet Configuration File

<?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-2.0.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 
        id="hello_world"
        implementor="demo.hw.server.GreeterImpl"
        wsdlLocation="WEB-INF/wsdl/hello_world.wsdl"
        address="/hello_world">
             <jaxws:features>
                  <bean class="org.apache.cxf.feature.LoggingFeature"/>
             </jaxws:features>
    </jaxws:endpoint>
</beans>

The code shown in Example 6.1 is explained as follows:

The Spring beans element is required at the beginning of every FUSE Services Framework configuration file. It is the only Spring element that you need to be familiar with.

The jaxws:endpoint element defines a service provider endpoint. The jaxws:endpoint element has the following attributes:

id — Sets the endpoint id.
implementor — Specifies the class implementing the service.
Important
This class needs to be included in the WAR's WEB-INF/classes folder.
wsdlLocation — Specifies the WSDL file that contains the service definition.
Important
The WSDL file location is relative to the WAR's WEB-INF/wsdl folder.
address — Specifies the address of the endpoint as defined in the service's WSDL file that defines service that is being deployed.
jaxws:features — Defines features that can be added to your endpoint.

For more information on configuring a jaxws:endpoint element, see Using the jaxws:endpoint Element.

Web application configuration

You must include a web.xml deployment descriptor file that instructs the servlet container to load the CXF servlet. Example 6.2 shows a web.xml file. It is not necessary to change this file. A reference copy is located in the InstallDir/etc directory.

Example 6.2. A web.xml Deployment Descriptor File

<?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>

Deploying a WAR file to the servlet container

How you deploy your WAR file depends on the servlet container that you are using. For example, to deploy your WAR file to Tomcat, you copy it to the Tomcat CATALINA_HOME/server/webapp directory.