JAX-WS with Apache CXF and Eclipse [step1]

Few months ago, I had to migrate WebServices from my professional project based on Axis to JAX-WS which is the Java API for XML Web Services supported by the Java Platform, Standard Edition 6 (Java SE 6).

There are several implementations of JAX-WS like :

• Glassfish – Metro.
• JBoss WS.
• Axis2.
• Spring JAX-WS.
• Apache CXF which is based on XFire.

In my case, my professionnal project doesn’t use Spring. We have chosen Apache CXF which use Spring by default but you can manage CXF without Spring.

I have discovered and learned CXF with Eclipse JEE Indigo (works too with Eclipse JEE Helios) which provides Wizard to generate JAX-WS annotation and initialize CXF application. I think that playing with the CXF Eclipse Wizard is a good start point to learn CXF, so I decided to write some articles called JAX-WS with Apache CXF and Eclipse (this link is the plan of articles) which explains step by step how to generate WebService and Consumer of WebService with CXF Eclipse Wizard.

In my articles I will use :

• the last version 2.4.2 of CXF.
• Tomcat 7 as server.
• Eclipse JEE Indigo.

But you can do the same thing with another version of CXF and another server. In this article I will explain how to

1. initialize the CXF Plugin
2. and create an empty Eclipse Dynamic Web Project with Tomcat 7.

Download

You can download jaxwswithcxf_step1.zip which is a zip which contains the empty Dynamic Web Project jaxwswithcxf.

Why CXF?

My experimentation with Axis2

When I started to play with JAX-WS, I decided to test Axis2 because I was happy with Axis but I was disappointed with the JAX-WS implementation of Axis2 for serveral reasons :

• documentation is very complex when you are a newbie.
• axis2 distribution provides a lot of JARs and we don’t know which JARs we must select
• default deploy service force you to set your WebService JARs in a servicejars folder.
• that’s why I tried to implement my own deployer to follow my custom architecure (WebService JARs are stored on another folders) but default axis2 deployer code is not based on JAX-WS Endpoint#publish(String address, Object implementor) to deploy a WebService.
• webservice is not a singleton
• have some bugs with method which don’t have any parameter, etc.

My experimentation with CXF

After my Axis2 experimentation, I have noticed that Eclipse JEE Indigo provides a wizard to generate JAX-WS annotation and initialize a Dynamic Web Project with CXF by using Spring. Unfortunately we have not Spring in our project, but CXF can work without Spring! I will explain to you how to do that in the next articles.

Today I’m not disappointed in CXF for several reasons :

• Eclipse JEE Indigo generate well JJAX-WS annotation for the Java class you wish publish as WebService.
• If you can use Spring, the CXF Wizard is very helpfull because it generate you the well web.xml with Spring CXF Servlet and Spring beans which are used to declare classes which must be published as WebService.

  Writing a service with Spring explains that.

• If you don’t use Spring, you can still use the CXF Wizard to generate JAX-WS annotation. For the publish of the WebService you need to do that manually with Java code by using JAX-WS API Endpoint#publish(String address, Object implementor) to deploy a WebService :

  MyService serviceInstance = new MyService();
  Endpoint.publish("http://localhost:8080/MyService", serviceInstance);
  

  will deploy your service available at the http://localhost:8080/MyService.

  A simple JAX-WS service explains that.

• CXF architecture is based on CXF Interceptors (In/Out) to do some process before (In)/after (Out) calling your WebService. You can use existing CXF Interceptor or develop your own Interceptor to manage logging, security, etc.
• CXF Team is very available. As soon as you post your questions/requirements on the CXF Mailing list, you have an answer.

Install CXF

CXF distribution provides several tools to generate JAX-WS annotation, WSDL, etc. The CXF Eclipse Plugin use those tools for the CXF wizard.

Installing CXF means :

• download CXF distribution
• Initialize CXF Eclipse Plugin to set the path of the CXF distribution in the CXF Eclipse Preferences.

Download CXF distribution

Go to the CXF Download and download the last version of the CXF distribution. In this article apache-cxf-2.4.2.zip is used :

Unzip apache-cxf-2.4.2.zip on your Hard Disk wherever you want. In my case I have unzipped to C:\Apache\apache-cxf-2.4.2 :

Initialize CXF Eclipse Plugin

In this section we will set the path of the CXF distribution in the CXF Eclipse Preferences. Open your Eclipse JEE (Helios or Indigo) and go to the Window / Preferences menu :

This action opens the Preferences dialog. Click on the Web Services / CXF 2.x Preferences menu item :

Click on Add… button (on the right of the dialog) to select the path of the CXF distribution. This action opens the Add CXF Runtime. Add Browse… button and select the path of CXF distribution (in my case C:\Apache\apache-cxf-2.4.2) :

If the path of CXF distribution is valid, the fields of the dialog are filled automatically like this :

Click on Finish button, the dialog closes and CXF Runtime tab is filled with the CXF Runtime :

At this step, CXF Runtime is not available. Click on checkbox to make it available :

CXF Runtime is now available. In the next article we will see that CXF Runtime will be present in the generic WebServices wizard.

Initialize CXF Web Application

Here we will create an empty Dynamic Web Project named jaxwswithcxf which will host the JAX-WS WebService.

Download Tomcat 7

Go to the Tomcat 7 Download and download the last version of the Tomcat distribution. In this article apache-tomcat-7.0.20.zip is used :

Unzip apache-tomcat-7.0.20.zip on your Hard Disk wherever you want. In my case I have unzipped to C:\Apache\apache-tomcat-7.0.20 :

Create Dynamic Web Project

In this section we will create an empty jaxwswithcxf WEB application with Dynamic Web Project. To do that go to menu File/New /Dynamic Web Project :

New Dynamic Web Project wizard opens. Fill in the project name with jaxwswithcxf and select Target runtime with your Server. If no server is defined, click on New Runtime… button to define it.

Click on New Runtime… button, open the wizard to create a server. Select Tomcat v7.0 Server :

Click on Next button, the wizard page displays the selection of the Tomcat directory (existing Tomcat or empty folder where Tomcat must be installed). Here we will select the installed Tomcat 7. Click on the Browse… button to select the Tomcat home (in my case C:\Apache\apache-tomcat-7.0.20) :

Click on the Finish button, the New Dynamic Web Project wizard page appears :

Fields of this wizard are pre-filled like 3.0 Dynamic Module Web version which means that Tomcat 7.0 support 3.0 servlet (you can select another version if you wish). Click on Finish Button, the empty jaxwswithcxf WEB application is generated :

Launch Empty WEB application

Now you can start the Tomcat server and launch the empty WEB Application. Select the jaxwswithcxf project, click on right mouse button and select menu Run As->Run on Server

This action opens the wizard to select the server :

Select Tomcat 7.0 server and click on the Finish button. This action create a Server folder in your workspace which is the configuration of your Tomcat and launch the jaxwscxf WEB Application :

You can notice that you will have a 404 error because the generated web.xml is like this :

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
  <display-name>jaxwswithcxf</display-name>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>default.html</welcome-file>
    <welcome-file>default.htm</welcome-file>
    <welcome-file>default.jsp</welcome-file>
  </welcome-file-list>
</web-app>

And your web application contains no such files.

Conclusion

In this article we have initialized CXF Eclipse Plugin and created an empty Dynamic Web Project with Tomcat 7.

In the next article [step2] we will create a simple Java class HelloServiceImpl and we will use CXF Eclipse wizard to expose it as WebService with JAX-WS and CXF.