OK, so like a lot of folks out there, I was all eager to start building RESTful web services for my product. Only one problem… there is still a bit of mystery involved in getting a setup working with everything ready to rock and roll. Here are my notes in the hopes that it will help you break thru the entry barrier (this is one of several different approaches to the problem).
Tools
- Mac OS X Lion
- Apache Tomcat 7.0.21
- Apache Maven 3.0.3 (pre-installed with Lion)
- Eclipse Indigo (Eclipse IDE for Java Developers 1.4.1)
- M2Eclipse Plugin 0.12.1
- Spring 3.0.1
- Apache CXF 2.5.0
Make sure these tools are installed before moving forward (plenty of info on the web about these tools and installing them that doesn’t need repeating here).
By using maven’s quickstart archetype, we can save some time setting up our initial project. If you aren’t familiar with Maven, the following should get you up to speed:
- Maven in 5 Minutes (http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)
So essentially,
- navigate to your workspace directory ($workspace)
- Execute the command to create a new project
- mvn archetype:generate -DgroupId=com.dnascimb -DartifactId=cxf-demo-first -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false
- This creates a directory $workspace/cxf-demo-first where the project will exist
Let’s open up Eclipse and bring in this new project, so that we can see the directory contents and work with the files a bit easier.
Project Directory Structure
Now we can see the directory structure maven created for us.
Let’s enable the M2Eclipse plugin to manage dependencies on this project so that we can get compilation working.
Now we can see that under the Maven Dependencies folder, maven has automatically brought in the required JUnit library (this was added to the POM file by maven).
Let’s take a look at the POM file and add additional dependencies which we’ll need.
As soon as we save the file, there are even more libraries Maven brings into the project based on the new information we put into the POM.
Let’s ensure that the Java version is 6 so that we can compile (since we’ll need features features present in version 5+). This is done by adding the following to the plugin section of the POM file.
Let’s start creating some classes. But first, let’s define a source directory for our Java packages/classes to live in.
Then a new package for our classes.
Now let’s create our first class (our service). Let’s call it FooBarService.
Let’s put some functionality into this class.
Here we’ve added an @Service annotation to indicate that this class is a service and it is to be named “fooBarService”. We’ve also added an @Path annotation to indicate that it is accessible via the path “/foo” in our webapplication (URL: http://localhost:8080/<app>/foo)
We’ve created a method getFooBarMessage() that returns a String and has some annotations, as well. The @GET annotation indicates that it interacts via the GET HTTP method. The @Produces annotation indicates that it will return or produce content of type “text/plain”.
Now, let’s go ahead and configure the web descriptor (web.xml) to be aware of the Spring Context Listener and the CXF Servlet (these will help wire everything together so that annotations work and the classes can be loaded by the application properly).
Next step is the Spring configuration. Let’s create a new file beans.xml and modify its contents to tell it about the CXF configuration file, as well as where to start scanning to find our service classes. We will also define our JAX-RS container and the services it should be aware of.
Now all we need to do for a simple test is to compile/package all of it and deploy the WAR to Tomcat’s webapps directory.
If Tomcat is not running, start it and go to the following URL:
http://localhost:8080/cxf-demo-first/foo
You should see the string returned to the browser from our FooBarService.getFooBarMessage() method.
All for now.
