Developing Web services using Apache CXF and Maven

By E.Hooijmeijer

(C) 2008-2011

• 15 March 2008 : initial Dutch version
• 12 January 2011: update for CXF 2.2.3
• 17 May 2011: update for CXF 2.4.0
• 21 Nov 2011: translation into English.

This tutorial describes three different methods in which you can create a web-service and client using Apache CXF. The first method is using Java interfaces and Aegis data binding. The second method is using JAX-WS (the Java API for XML Web Services) and JAXB (Java API for XML Binding) annotated classes. The third and final method uses contract first development using a WSDL. At the end of the tutorial the strengths and weaknesses of the different methods are discussed.

In order to efficiently configure, build, generate and test the projects we're going to use Maven as a build environment. The installation and configuration of Maven is part of this tutorial.

Installing Apache Maven

Download the binary distribution of the 3.0.x version of Apache Maven. Unpack it to a useful folder and note the path. In order to successfully use Maven you need to have two environment variables set:

• JAVA_HOME which should point to the root folder of your JDK
• M2_HOME which should point to the root folder of your Maven install.

Also you will need to adjust the PATH environment variable so that you can issue the 'mvn' command.

On windows you need to open the 'advanced system settings' using
Control Panel->System->advanced system settings->Environment Variables
and then add JAVA_HOME and M2_HOME to the system variables. The PATH needs also adjusting, append ';%M2_HOME%\bin'. Then open a new command prompt and enter:

              
> mvn -version
              

If all is well, it should report the maven version.

On a Linux machine the steps to perform are the same, only the place where is different and dependent on the flavor of Linux you're using. For Ubuntu read this .

Starting a project with Apache Maven

Its easy to setup a project structure using Maven by means of the 'Archetype' plugin. This plugin contains customizable project templates for common types of projects. There are archetypes for a simple single jar project or a complete enterprise application. Lets start with the simple jar file :) First go to your Java projects folder and in that folder you'll execute the following maven command:

              
/home/user/java/> mvn archetype:generate
              

Maven will now download the plugin and will give you a list of all possible archetype projects. In this instance we'll pick the 'maven-archetype-quickstart', which is the default. After that there will be some questions about the project parameters:

              
Define value for groupId: : nl.cad 
Define value for artifactId: : CXFTestService
Define value for version: : 1.0-SNAPSHOT
Define value for package: : nl.cad.cxf.testservice
              

The groupId determines the group this project is in. In this case I place the project in my own group nl.cad (as in ctrl-alt-dev ;) The groupId determines where in the repository the project is placed. The second parameters is the artifactId. This is the name of the project and the name of the project directory that will be made and also the name if the jar file. The version parameter indicates the version of the project and SNAPSHOT indicates its a version that is actively developed. Finally there is the package name, which is the package that will be generated with some sample java files in it.

Now enter the CXFTestService directory and check out the files there. Aside from a directory for source files there is also a file called pom.xml. This file contains the Maven Project information. If you open the file with a text editor you can read back the various project settings you've made previously as well as the dependencies of this project (currently only JUnit). Of course we want to do stuff with CXF so we'll need to add CXF as a dependency:

                
<dependency>
	<groupId>org.apache.cxf</groupId>
	<artifactId>cxf-rt-frontend-jaxws</artifactId>
	<version>2.4.0</version>
</dependency>
<dependency>
	<groupId>org.apache.cxf</groupId>
	<artifactId>cxf-rt-transports-http</artifactId>
	<version>2.4.0</version>
</dependency>
<dependency>
	<groupId>org.apache.cxf</groupId>
	<artifactId>cxf-rt-databinding-aegis</artifactId>
	<version>2.4.0</version>
</dependency> 
<dependency>
	<groupId>org.apache.cxf</groupId>
	<artifactId>cxf-rt-transports-http-jetty</artifactId>
	<version>2.4.0</version>
	<scope>test</scope>
</dependency>

                

We'll specify 4 new dependencies. The first two are needed if you want to create HTTP based web-services with CXF. The third dependency contains the Aegis data binding. The final dependency allows us to test the web-service using a unit test. The scope of this dependency is therefore 'test', which means that the jar files of this dependency will only available when testing.

To verify the correctness of this configuration you can execute the command 'mvn clean install'. Maven will now download all required dependencies, clear out the target directory (which is not there yet) and compiles and tests the code after which its placed in a jar file. This illustrates the power of maven: one command, complete build, all dependencies included.

Eclipse Integration

If you're, like me, using Eclipse as primary IDE its useful to know that Maven can also generate the .project and .classpath files using the 'mvn eclipse:eclipse' command. The project can now be imported using the eclipse import wizard. You'll notice that eclipse can't find the dependencies so you'll need to add the M2_REPO classpath variable. You can do this in the Window->Preferences->Java->BuildPath-Classpath variables screen.

If you change the pom file you'll need to regenerate the settings. Eclipse won't pick-up the changed files automatically, so you'll need to press F5 after each

              
mvn eclipse:eclipse
              

All right, Maven and the IDE are ready, on with the real work!