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 I’ve been working on a project which requires developing some...
2. The EJB Specification, Concurrency, and Batch Processing The EJB specification does not leave much room for implementing...

The enterprise bean must not attempt to manage threads. The enterprise bean must not attempt to start, stop, suspend, or resume a thread, or to change a thread’s priority or name. The enterprise bean must not attempt to manage thread groups.

These functions are reserved for the EJB container. Allowing the enterprise bean to manage threads would decrease the container’s ability to properly manage the runtime environment.

Researching this topic I found that while the specification states the restrictions, the EJB containers do not actually enforce the rule. I was able to test an implementation using a ThreadPoolExecutor in JBoss with no problems. Most implementations addressing long running batch processing solutions specify developing applications outside the EJB container. While the design respects the EJB programming restrictions it is not always a feasible solution for developers. Currently, I am confronted with business requirements to process a large set of files within the process flow of a business method.  The process flow would be to select files based on some criteria, specify what to do with the file collection, and submit the task asynchronously as a background process through JMS to a message-driven bean (MDB) for processing. When the job is done, update the database with the new file paths and notify the user of successful completion. There are several underlying issues:

1. The user submits a request to process a very large set of files. The time to process this request may take hours to complete and will most-likely exceed the default configured transaction time-out of the message-driven bean at which point a TransactionTimeOut Exception is thrown and the operation halts. This can be overcome to a certain extent by increasing the transaction timeout period in the application server settings.
2. The single large task executes in a sequential manner, and does not take advantage of all available CPU’s on a multi-processor machine.
3. It would be more efficient and reduce execution time if the task could be broken up into smaller tasks (or batches) and executed in parallel, or distributed across a group of servers which can process each sub-task individually.

The design concepts are relatively simple but the implementation details are complex due to the programming restrictions in the EJB specification. This screams concurrency! The most commonly suggested solution for concurrency is to use JMS. One solution I found is to break up the task, create multiple JMS messages that reply to an acknowledgment queue. Then set the Session Bean to listen to that ack queue using a message filter to collect the results of each sub-task. This is a good solution but a bit more complex to implement than bending the rules and using a ThreadPoolExecutor. I think the real issue with managing threads within the EJB container is the topic of reentrancy. In my case, I am calling a remote service so there is no chance of that.

There are many factors to consider when implementing a batch processing framework for your application. There is no one size fits all solution. You really have to evaluate all the options, weigh the pros and cons of each, and decide on your own which approach works best in your environment. Here is a list of articles I found very helpful in making that decision:

• High Performance Batch Processing with Java Enterprise Edition
• Add Concurrent Processing with Message Driven Beans
• JMS Enables Concurrent Processing in EJB
• High Volume Transaction Processing in J2EE

Related posts:

1. Java Web Services: Getting Started When it came time for me to tackle my first...

It’s been a frustrating experience so far. I’ve spent the past week troubleshooting and prototyping various web service implementations with different versions of JBossWS rather than developing my application code. The issues have revolved primarily around different versions of JBossWS and deployment. For instance, I found that I could successfully deploy multiple web service endpoints configured as servlets on JBossWS 1.2.0.SP1 which I could not do in 1.0.3.SP1. That being fixed my next task was to refactor the code as EJB service endpoints. Prior to doing that I decided to upgrade JBossWS to version 1.2.1.GA. Logically it is a minor upgrade 1.2.0 to 1.2.1 and should just contain minor bug fixes. However, after upgrading and refractoring my service endpoints as stateless session beans I fired up JBoss to encounter this error:

org.jboss.deployment.DeploymentException: Cannot create service endpoint; – nested throwable: (org.jboss.ws.WSException: Multiple context root not supported)

I cut-and-paste the error into Google and shortly thereafter I stumbled upon the answer. Apparently, there was quite a major change in functionality between JBossWS 1.2.0 and 1.2.1 which is not documented very well.

Posted: Wed May 16, 2007 07:55 AM    Post subject: Re: If I deploy more than one web service I get

——————————————————————————–

Thanks for the valuable discussion. I will try to explain what changes between 1.2.0 and 1.2.1 are causing the problems you encounter.

1.) For EJB3 deployments we need to create a web app for HTTP invocations (obviously)

2.) EJB’s don’t contain web context information, so we derive it automagically.

3.) Until 1.2.0 the context name was derived from the ear/jar name.

4.) This changed with 1.2.1 to an algorithm that derives it from the bean class name

So what’s happening when you deploy a EJB3 jar that contains multiple beans?
The default algorithm derives different context names for each bean in this deployment, which in turn we cannot use to setup the HTTP endpoint and thus throw an exception.

This also explains why the following did work:

@WebContext(contextRoot=”/beans”)

Unfortunately this is left out in the specs and thus has been changed many times.
Until we a have a definite solution i suggest you refer to the @WebContext annotation, even though it’s not the most elegant solution.

–
Heiko

Finally an answer! Well sort of. I didn’t want to use the annotations. I found an alternative solution in the JBossWS FAQ which described setting the context root explicitly but no information on how to set the context root. Some more searching and I found the DTD for the jboss.xml file which described the XML tags required to set the web service context root. After adding these tags and specifying a context root I successfully deployed my multiple EJB endpoints.

Wow! That’s a lot of work and I haven’t written any of my own business logic yet. Needless to say these issues put me a bit behind schedule on my project. The examples provided in the JBoss J2EE  Guide for creating web services are simple enough to follow and are good for getting started but that’s about it. The provided examples work on all of the above mentions versions of JBossWS but fail when you want to get a little more complex with your service. Notice the documentation only provides examples for creating web services that pass primitive types. What about passing custom types? What about passing an array or collection of custom types? None of this is covered and you must refer to outside books and resources to find the answers. In following post I plan to address these topics in detail.

Related posts:

1. Java Web Services: Getting Started When it came time for me to tackle my first...