Java Web Services: Getting Started

When it came time for me to tackle my first web service implementation I ran into a lot of problems. Here I will write a series of articles to address the questions and problems I encountered in hopes of helping you get started in developing web services faster than I did. The following example will show you how to create a web service using JAX-WS and packaged as a servlet.

A Simple Service

To start out you should create an interface defining your business methods. I will keep the implementation extremely simple so we can focus on the details of web services. Here’s our interface named SimpleServiceWS

public interface SimpleServiceWS {

	public String simpleMethod();

}

The next step is to create a plain java class (POJO) which implements this interface. I’ll name it SimpleServiceImpl

public class SimpleServiceImpl implements SimpleServiceWS {

	public String simpleMethod() {
		return "Simple response";
	}

}

Please note that it is not required to create and implement an interface and almost every web service example I found did not do so. I feel it is good practice and consistent with Java programming practices to program against interfaces.

What we have so far is just a plain Java class (POJO) that returns a simple string. Now we have to decorate our class with some annotations to make it behave as a web services.

import javax.jws.WebService;

@WebService(
		serviceName="SimpleService",
		portName="SimpleServicePort",
		endpointInterface="net.franksalinas.javablog.SimpleServiceWS")
public class SimpleServiceImpl implements SimpleServiceWS {

	public String simpleMethod() {
		return "Simple response";
	}

}

I added the @WebService annotation and supplied some values to the annotation attributes. You can simply add the @WebService annotation without specifying any of the attributes and they will pick up default values based on the class and package names. However, there is one exception. If you choose to define and implement an interface you must do two things:

1. You must decorate the interface with the @WebService annotation.
2. You must also supply the endpointInterface annotation attribute with the fully qualified name of the interface in the implementation class.

import javax.jws.WebService;

@WebService()
public interface SimpleServiceWS {

	public String simpleMethod();

}

As far as code goes this is all there is to it. The remaing steps describe how to package and deploy these objects.

Package and Deploy

As I mentioned above we will package and deploy these classes as a servlet implementation. I am most familiar with JBoss so that is the application server I will use but any servlet container should work fine.

Create a new xml file named web.xml and define the servlet mappings for the SimpleServiceImpl class as shown here.

<?xml version="><?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>
	<servlet>
		<servlet-name>SimpleServiceWS</servlet-name>
		<servlet-class>net.franksalinas.javablog.SimpleServiceImpl</servlet-class>
	</servlet>

	<servlet-mapping>
		<servlet-name>SimpleServiceWS</servlet-name>
		<url-pattern>/SimpleService</url-pattern>
	</servlet-mapping>
</web-app>

Now create a WEB-INF directory and place this file there. Compile your Java files and place them in a folder named classes. Create a folder named dist. Copy the WEB-INF and classes directory to this new folder. Now create a JAR file named SimpleService.war containing the contents of dist directory. (Visit http://en.wikipedia.org/wiki/Sun_WAR_(file_format) for more info on the WAR file structure.)

You should now have a WAR file with the following structure:

META-INF/
META-INF/MANIFEST.MF
WEB-INF/
WEB-INF/web.xml
classes/
classes/net/
classes/net/franksalinas/
classes/net/franksalinas/javablog/
classes/net/franksalinas/javablog/SimpleServiceImpl.class
classes/net/franksalinas/javablog/SimpleServiceWS.class

Now you can copy this SimpleService.war file to your application server’s deployment directory (<jboss_home>/server/default/deploy) and start the server. Your web service will be deployed. On JBoss you can see the deployment and access the WSDL for the service at url http://127.0.0.1:8080/SimpleService/SimpleService?wsdl

That’s all there is to it!

Note that we did not implement the javax.servlet.http.HttpServlet interface in the service class. It is not required but may be considered good practice to do so depdending on your implementation.

Summary

In this example we created a simple web service using JAX-WS and packaged and deployed the implementation as a servlet configuration. We learned that web services are nothing more than plain old Java objects (POJOs) that are decorated with a few simple annotations and that servlet configurations do not require the web service class to implement the javax.servlet.http.HttpServlet interface. We covered packaging the code as a WAR file and deploying on the JBoss application server.

This is a very simple example and there’s a lot more material to cover. I hope you found this posting informative and helpful. You can download all the source code for this example here: SimpleService.zip.

Related posts:

1. Web Services on JBoss
2. The EJB Specification, Concurrency, and Batch Processing