TechJava» TechJava – Articles tagged by ejb

Exposing Functionality using Web Services and JEE

Simon Zambrovski — Thu, 07 Jan 2010 11:11:22 +0000

Abstract

About two years ago, I published an article about Exposing the Functionality implemented in Stateless Session Beans (EJB 2.1) using Web Services. J2EE 1.4 times are over and the new version of the Java Enterprise framework, called Java Enterprise Edition 5 (JavaEE 5, or simply JEE) has emerged. In this article the same business scenario is repeated in the new framework.

Requirements

Before we dive into code examples, some software is required. The good news about the software is, that it also evolved over time. Here is what we use:

Sun’s Java 6 SDK
JBoss AS 5.1.0 GA for JDK6
Eclipse Galileo 3.5.1 for JEE development

Some words about the used software. It is important to get the JDK6-compiled version of the JBoss Application Server. There are some issues with running the version compiled with Java 5 on JDK6, since JDK6 has its own JAX-WS implementation which causes problems with JBoss (affected should be all versions of JBoss < 5.2. Currently it seems like version 5.2 will be compiled with JDK6 by default.) If you launch JBoss from Eclipse, make sure to add the -Djava.endorsed.dirs=PATH_TO_JBOSS/jboss-5.1.0.GA/lib/endorsed as a VM argument, if launched from the command line, please add it as an option inside of the run.conf.bat file:

set "JAVA_OPTS=%JAVA_OPTS% -Djava.endorsed.dirs=$JBOSS_HOME/lib/endorsed"

Otherwise you will get the following exception:

java.lang.UnsupportedOperationException: setProperty must be overridden by all subclasses of SOAPMessage

After installation (unpacking) of Eclipse, make sure to configure the JDK (under Preferences > Java > Installed JREs) and the JBoss instance (Preferences > Server > Runtime Environment).

Use Case

In order to demonstrate the technology by example, imagine the following use case. The system under construction is capable of providing measurements of some sensors. The sensors are identified by numbers and can be queried by the user by providing the timespan of measurements. As a result, the systems delivers the set of measurements for the given timespan with one measurement per minute but at most sixty measurements. Every measurement contains the id of sensor from which it has been recorded, the timestamp, the value as a byte array, the measurement unit and finally a flag whether the measurement exceeds the limits or specified alarm values.

Implementation

We start the implementation with the creation of a JEE Session Bean and then expose the functionality using a second Facade bean. In doing so we follow the EJB 3 specification.

Eclipse for Java EE development

The plugins in Eclipse for Java EE provide massive support and foster the development by deep integration withe JEE servers. Instead of a simple Java Project, start with an Enterprise Application Project. Then, create a new EJB Project and add it to the created Enterprise Application Project. In order to deploy the resulting application to the server, right-click on the enterprise project and select Run As > Run on Server .

To check the deployment on the application server, use the JBoss Consoles. These can be accessed via http://localhost:8080/ for the locally installed JBoss. An additional Web Service Console is accessible via http://localhost:8080/jbossws/.

Implementing the Functionality

In order to implement the functionality in a stateless session bean, we start with the creation of the business interface.

/**
 * Defines the sensor manager functionality
 */
public interface SensorManager
{
	/**
	 * Retrieve sensor data
	 * @param sensorId id of the sensor
	 * @param timespan the measurement period
	 * @return a list of measurements in the given period
	 * @throws SensorManagerException on any kinds of errors
	 */
	public List getSensorData(SensorID sensorId, Timespan timespan) throws SensorManagerException;
}

The POJOs Measurement, SensorID and Timespan are used to show the usage of custom user types:

public class Measurement
{
	private SensorID sensorID;
	private Date timestamp;
	private boolean critical;
	private byte[] value;
	private String unit;
...
// getters and setters
}
....
public class SensorID
{
	private long sensorId;
...
// getters and setters
}

public class Timespan
{
	private Date start;
	private Date end;
...
// getters and setters
}

After the creation of the business interface, let us create the actual Session Bean. The class is annotated with the @javax.ejb.Stateless annotation in order to indicate that the bean is a Stateless Session Bean. Since it implements the business interface (and only it), the container will be able to deduce that the given interface is the Local Business interface: this is just one of many examples of the Configurations by Exception in EJB 3. In order to be able to reference the bean from other beans, we annotate the binding of the local interface to a specific JNDI name using the vendor-specific annotation org.jboss.ejb3.LocalBinding.

@Stateless
@LocalBinding(jndiBinding="de.techjava.sensor/SensorManager")
public class SensorManagerBean implements SensorManager
{
	/** Logging facility */
	protected static Logger LOG = Logger.getLogger(SensorManagerBean.class);
	/** Max number of returned values */
	private static final long MAX_DURATION = 60;

	/**
	 * Implementation of the business method
	 */
	public List getSensorData(SensorID sensorId, Timespan timespan) throws SensorManagerException
	{
		LOG.debug("Entering getSensorData()");
		if (sensorId == null || timespan == null || timespan.getStart() == null || timespan.getStart() == null)
		{
			throw new SensorManagerException("Missing a mandatory parameter, that was null (not set)");
		} else if (!timespan.getStart().before(timespan.getEnd()))
		{
			throw new SensorManagerException("The timespan is defined by the start that should be before end");
		}

		List measurements = new LinkedList();
		for (long i = 0; i < getNumberOfElements(timespan); i++)
		{
			Date date = new Date();
			date.setTime(timespan.getStart().getTime() + i * 1000 * 60);
			if (date.after(timespan.getEnd()))
				break;
			Measurement measurement = createMeasurement(sensorId, date, i);
			measurements.add(measurement);
		}

		LOG.debug("Leaving getSensorData(). Returning " + measurements.size() + " values.");
		return measurements;
	}

	/**
	 * Retrieves the number of measurements in timespan
	 */
	private long getNumberOfElements(Timespan timespan) { ... }

	/**
	 * Creates a measurement instance, a dummy implementation
	 */
	private Measurement createMeasurement(SensorID sensorId, Date timestamp, long number) { ... }
}

Web Service Definition

The quality of the web service interface is an important design consideration. As described in the previous post, in many cases it is a good idea to create it by hand instead of generation by a tool. In this particular case, we create another annotated Stateless Session Bean, which is used as a Facade and contains all Web Service-specific settings. From this Bean we generate the WSDL and then tune it in order to show the capability of the customization. In doing so we try to match the WSDL from the previous example as close as possible.

Firstly, we create the business interface and the bean class, then annotate it and finally add the code delegating the Web Service request to the SensorManager.

public interface MeasurementProviderFacade
{
	public List getSensorData(SensorID id, Timespan timespan) throws SensorDataOperationFault;
}

...

@Stateless
public class MeasurementProviderFacadeBean implements MeasurementProviderFacade
{
	public List getSensorData(SensorID id, Timespan timespan) throws SensorDataOperationFault
	{
	...
	// implementation code
	}
}

In order to have a Session Bean exposed as a Web Service, the JAX-WS specification defines a set of annotations. The most important two are @javax.jws.WebMethod and @javax.jws.WebService. The @WebService annotation is used to mark the class to be exposed e.G.

@Stateless
@WebService(
	serviceName = "MeasurementProviderService",
	name = "MeasurementProviderPortType",
	portName = "MeasurementProviderPort",
	targetNamespace = "http://www.techjava.de/2010/ws4jee/measurement/"
)
public class MeasurementProviderFacadeBean implements MeasurementProviderFacade
{
	@WebMethod(
		operationName="GetSensorDataOperation",
		action="http://www.techjava.de/2010/ws4jee/measurement/GetSensorDataOperation"
	)
	public List getSensorData(SensorID id, Timespan timespan) throws SensorDataOperationFault { ... }
}

All the attributes of the annotation are optional and their values will be derived from the classname and the name of the business interface. The default target namespace for the service definition is derived from the package name, the annotated class is located in. By default, all public methods of the annotated class will be exposed as WSDL operations, with operation’s name derived from the method name. Using the @WebMethod annotation, the name of the WSDL operation and the SOAP action can be changed.

The careful reader might have observed that the getSensorData-method is throwing an exception. In order to map the exception to a SOAP-Fault, the javax.xml.ws.WebFault class-level annotation can be used. The faultBean attribute is used to provide the full-qulified class name of the exception.

...
@WebFault(
	name="GetSensorDataFault",
	targetNamespace="http://www.techjava.de/2010/ws4jee/measurement/",
	faultBean="de.techjava.sensor.bean.SensorDataOperationFault")
public class MeasurementProviderFacadeBean implements MeasurementProviderFacade { ... }

In order to increase the quality of the WSDL further, the method parameters and return type can be annotated with javax.jws.WebParam and javax.jws.WebResult respectively, so the method signature becomes a little unreadable. In order not to copy the long string containing the taget namespace a String constant can be used.

...
	public final static String TYPES = "http://www.techjava.de/2010/ws4jee/measurement/types/";
...
	@WebResult(name="measurement", targetNamespace=TYPES)
	public List getSensorData(
		@WebParam(name="sensor-id", targetNamespace=TYPES) SensorID id,
		@WebParam(name="timespan", targetNamespace=TYPES) Timespan timespan) throws SensorDataOperationFault	{ ... }

Finally, in order to force the marshaller / unmarshaller to map the custom data types (Measurement, SensorID and Timespan) to belong to the same namespace, the JAX-B class-level annotation javax.xml.bind.annotation.XmlType has to be used. By default, the datatypes will be mapped to XML Schema types according to their package name and class name.

@XmlType(namespace = "http://www.techjava.de/2010/ws4jee/measurement/types/", name = "TimeSpan", propOrder = { "start", "end" })
public class Timespan
{
	private Date start;
	private Date end;

If deployed to the JBoss, the resulting WSDL looks as following:

Please note, that the domain datatypes are mapped to the different namespace as the target namespace of the Web Service.

After some tuning the WSDL, like changing the cardinality of elements (minOccurs = 1, maxOccurs = 1) or adding comments we can let the container use the changed WSDL file instead of generating a new one. In order to do this, let us package the WSDL together with the source code. A good place for it is for example /META-INF/wsdl/, so we can provide a reference to it in an wsdlLocationattribute of the @WebService annotation:

@WebService(
...
        wsdlLocation="META-INF/wsdl/MeasurementProviderService.wsdl"
)

Putting all together

After the creation of the Facade Bean and its exposure as a Web Service, we need to delegate the call to the SensorManagerBean, providing the actual implementation. In order to do so, add a private member of type SensorManager inside of the facade bean and annotate it with the javax.ejb.EJB annotation. The container will intialize the member using Dependency Injection and provide a valid reference which can be simply used inside of the method.

...
public class MeasurementProviderFacadeBean implements MeasurementProviderFacade
{
	@EJB(mappedName="de.techjava.sensor/SensorManager")
	private SensorManager sensorManager;

	/**
	 * Simple delegate to the business method of the sensor manager
	 */
	@WebMethod(
			operationName="GetSensorDataOperation",
			action=TNS + "/GetSensorDataOperation"
	)
	public @WebResult(name="measurement", targetNamespace=TYPES) List getSensorData(
			@WebParam(name="sensor-id", targetNamespace=TYPES) SensorID id,
			@WebParam(name="timespan", targetNamespace=TYPES) Timespan timespan) throws SensorDataOperationFault
	{
		try
		{
			return sensorManager.getSensorData(id, timespan);
		} catch (SensorManagerException e)
		{
			throw new SensorDataOperationFault("Error accessing the Sensor Manager: " + e.getMessage() + "");
		}
	}
}

Here is the call in Web Service Explorer:

Outline

In this article we showed how to expose the functionality implemented in an EJB 3 Session Bean using Web Service Technology. In fact, the creation of a FacadeBean was not required since one could annotate the SensorManager-Bean directly, but we separated the implementation Bean from the exposing Bean to make it easier to understand. Even if we didn’t match the WSDL from the J2EE 1.4 example exactly, we came very close. Merely some message-related datatypes have different names. In this example we used the Document/Literal/Wrapped style of Web Services in order to gain maximum interoperability. Even though the creation of the Web Service is a simple task using the annotations. The number of tools and dependencies has dramataically reduced since J2EE 1.4 and the development became less error-prone. Together with other EJB3 improvements it makes the JEE framework suitable for development in the context of enterprise distributed systems.

References and Resources

The example source code is available for download ( ws4jee.zip). Just import the projects from the archive into Eclipse Worskspace. Make sure to set up the JRE and JBoss Server instance for the projecst to work.

[2008,techreport] bibtex

E. Jendrock, J. Ball, D. Carson, I. Evans, S. Fordin, and K. Haase, "The Java EE 5 Tutorial," 2008.

@techreport{JAVAEE, author = {Eric Jendrock and Jennifer Ball and Debbie Carson and Ian Evans and Scott Fordin and Kim Haase}, title = {The Java EE 5 Tutorial}, url = {http://java.sun.com/javaee/5/docs/tutorial/doc/}, month = {Oct}, year = {2008} }
[2007,book] bibtex

O. Ihns, D. Harbeck, S. M. Heldt, H. Koschek, R. Schl�r, J. Ehm, and C. Sahling, EJB 3 professionell. Grundlagen- und Expertenwissen zu Enterprise JavaBeans 3 fr Einsteiger, Umsteiger und Fortgeschrittene , publisher DPunkt Verlag, , 2007.

@Book{IHNS_2003, author = {Oliver Ihns and Dierk Harbeck and Stefan M. Heldt and Holger Koschek and Roman Schl�mmer and Jo Ehm and Carsten Sahling}, title = {EJB 3 professionell. Grundlagen- und Expertenwissen zu Enterprise JavaBeans 3 f�r Einsteiger, Umsteiger und Fortgeschrittene }, publisher {DPunkt Verlag}, year = {2007}, month = {Jul}, url = {Oliver Ihns, Dierk Harbeck, Stefan M. Heldt, Holger Koschek, Roman Schl�mmer, Jo Ehm, Carsten Sahling} }

Hacking, Progmatic, Productive

Simon Zambrovski — Wed, 17 Sep 2008 14:12:49 +0000

Yesterday, the second Adam Bien event in Lehmanns Bookstore took place. Again, the event was a full success. I arrived half-an-hour earlier and got a seat only in the tenth row.
Adam spoke about new features of EJB 3.1 and Glassfish. He showed examples running on a developer build of Glassfish V3, promising that the features will work without exceptions…
Here are some topics, I remember:

Singleton Beans: usefull a s a central point of the application, e.G. central cache etc…
Async Methods: allows asynchronous execution of time-consuming methods. Especially, it is possible to abort the execution
Deploying Beans in WARs: could be helpful for small applications
Global JNDI-Namespace
No interface view: simplifies the access to beans, if needed
EJBCOntainer.getEJBContainer().getContext(): allows external initialization of bean context, which is nice for testing

Later, Adam discussed some Core J2EE patters, that become absolete with EJB 3.1 and others which are still valid.

After the talk, I spoke with Adam about the OSGi as a module architecture inside JEE application, which seems interesting to me.

The pictures are as usual available in my FlickR Gallery.

Marco published a video on Loroma.

Productive Java EE 6

Simon Zambrovski — Wed, 10 Sep 2008 22:16:53 +0000

The holiday season is over and we can enjoy an event every week. After Maven 2, Eclipse Stammtisch and reasoning on modularity an event on enterprise systems can be visited. It seems that after the last visit on Java EE 5 Hacking Adam want to tell something on Java EE 6 Hacking…

This session will be interactive / openspace like. He will walk through the new EJB 3.1 APIs and explain some interesting stuff as well. It is the logical conduction of the first JUG HH session in May 2008.

Location: Lehmanns Fachbuchhandlung (Hamburg Hauptbahnhof), Kurze Mühren 6, 20095 Hamburg

Date and Time: 16.09.2008, 20:00
Topic: Productive Java EE 6 – Rethinking Best Practices And Bashing On Patterns, Cluster One

Abstract: Java EE 6 is great, but many questions like:

Are DAOs dead?
Do JSF really suck?
Are anemic JPA-entities a best practice?
Are XML deployment descriptors legacy?
Are EJBs lightweight?
How to test EJBs?
Is layering an antipattern?
Do we need factories?
How to integrate with RESTFul services?
Is it possible to deploy EJBs into a …WAR?
Are “plain old web containers” dead?
Services or Objects – what is the way to go?

still remain open. These and many other questions will be discussed interactively with …code.

Speaker: Adam Bien

About the speaker: Java Champion Adam Bien is a self-employed consultant, lecturer, software architect, developer, and author in the enterprise Java sector in Germany who implements Java technology on a large scale. He is also the author of several books and articles on Java and J2EE technology, as well as distributed Java programming. His books include J2EE Patterns, J2EE HotSpots, Java EE 5 Architectures, Enterprise Architectures, Enterprise Java Frameworks, SOA Expert Knowledge, and Struts, all published in German.

As BEA technical director, Bien is also a member of the NetBeans Dream Team; an Expert Group member of the Java Community Process for EJB 3.1, JPA 2.0, and Java EE 6; and involved in embedded Java, Grid, and P2P technology. He currently works as an architect and developer in several J2EE-Java EE Model-Driven Architecture (MDA) and EAI component architecture projects for the Java EE platform and .NET.

Exposing functionality using Web Services and J2EE 1.4

Simon Zambrovski — Tue, 19 Feb 2008 16:30:23 +0000

Abstract

In this article we describe how to implement a simple Web Service using old fashioned Java EE 1.4. The dummy functionality is implemented in Session Beans and exposed via document-literal Web Service following the recommendations of W3C and WS-I.

Introduction

Before we get in to technical details about the implementation a short overview of planned is helpful. The main idea of this article is to show how a web service can be implemented using Java Enterprise Edition. Especially, this article tries to achieve two goals: show how existing EJB functionality can be exposed using Web Service technology and how Web Service technology can be linked to something stable, most of us have experience with. Many people follow the new trend of saying that EJB is ineffective and heavyweight – we don’t want to argue about this thesis. In this article we show a progmatic EJB development approach using “code-by-convention” combined with Generative-Programming techniques. We develop the EJB functionality and Web Service definition independent from each other and link them later together – we are sure that this is the only approach to keep both parts simple, clean and reusable. During the WSDL design we follow a certain style of type and element selection, that results from some experiences of using generators and integration with non-Java environments. Our use case is a little synthetic in order to show the variety of types and seems to introduce structural complexity, which can be avoided. We implement the examples using open source products only.

The article starts with a short introduction which could look a little lyrical for some technicians of you. Then the requirements to the selected software are listed, followed by the practical use case. Then we jumpstart the EJB development cycle, design the Web Service and finally put both implementations together. In the outline, we discuss the testing possibilities…

Requirements

In order to develop, generate, package and finally deploy and run the component, exposing its functionality we need special software. Following selections has been made:

Sun’s JDK (> 1.4.2)
Apache Ant (> 1.6.5)
XDoclet (1.2.3)
Sun’s Java Web Service Developer Pack (1.6)
JBoss AS (4.0.5 GA)
Eclipse IDE (> 3.3), recommended WTP installation

First of all we need to setup our environment. In order to make development under MS Windows convenient, we used to setup the entire environment variables in a single shell script:

@echo off
echo ----------------------------------------
echo Project Environment
echo ----------------------------------------
set DEVEL=c:\environment
set ANT_HOME=%DEVEL%\libraries\ant\1.6.5
set JAVA_HOME=%DEVEL%\compiler\j2sdk1.5.0_01
set JAVAC_EXEC=%DEVEL%\compiler\j2sdk1.5.0_01\bin\javac.exe
set JWSDP_HOME=%DEVEL%\compiler\jwsdp-1.6
set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%;%DEVEL%\bin;%JWSDP_HOME%\jaxrpc\bin
echo Environment variables:
echo ANT home : %ANT_HOME%
echo JAVA home : %JAVA_HOME%
echo PATH set to : echo %PATH%
echo ----------------------------------------
echo CLASSPATH set to : echo %CLASSPATH%
echo ----------------------------------------
cmd

For usage under Linux/MacOS the script should be adjusted correspondingly.

Eclipse is used as IDE for the whole development. In order to avoid any dependency to certain Eclipse functionalities we use Apache Ant as a build tool. In order to use the build tools these should be configured. In Preferences of Eclipse we set up Apache Ant and XDoclet. In Window -> Preferences -> Ant -> Runtime set up the Ant Home pointing to the Ant installation directory. In Window -> Preferences -> XDoclet set up XDoclet Home to XDoclet installation directory and set the version to 1.2.3.

Project Setup

Even if we don’t want to rely on the build and shortcommings of Eclipse in the area of EJB development, we want to use maximum of support if possible.

Create a new EJB Project and select the following Project Facets: EJB Module 2.1, XDoclet 1.2.3 and Java 1.4. We use the following project structure: all hand-written Java files go to /java/src directory, all Doclet-generated goes to /java/generated, the compiled files go to /java/class and the resulting archives (jars and ears) go to /java/build. The additional /metadata directory contains source and descriptor files needed for the project. To set all this up go to Project Properties -> Java Build Path. As long as we control XDoclet from an Ant script, we deactivate the XDoclet Builder in Project Preferencies -> XDoclet and in Project Preferences -> Builders. Before we begin with the implementation we have to set up the Ant script, that will build and package our project. The script unifies different tools we use to a single toolchain and contains several targets. These are EJB-Doclet generation target, WS-Compile target, Web-Doclet target, target for compilation of the Java classes and, finally, creation of a JAR and EAR files. In order to hold the build file project independent we use properties files that contain project specific settings. In order to access XDoclet and WSCompile from Ant the corresponding task definitions must be included and the libraries must be put to directories in classpath. For this purpose we used to create a library project in the same workspace, containing the libraries (called general).

In order to demonstrate the implementation we introduce a use case. This is sonstructed for the demonstration purposes and shows the usage of different types.

Use Case

The constructed system is capable of providing the measurements of some sensors. The sensors are identified by numers and can be queried by the user by providing the timespan of measurements. As a result, the systems delivers the set of measurements for the given timespan with one measurement per minute but at most sixty measurements. Every measurement contain the id of sensor from which it has been recorded, the timestamp, the value as a byte array, the measurement unit and finally the flag if the measurement exceeds the expectation and has alarming values.

We start with typical EJB implementation and then adopt the resulting types to those, that should be used in a Web Service.

First Session Bean powered by XDoclet

Following the EJB 2.1 specification the stateless session bean class must implement the javax.ejb.SessionBean interface. We follow the Class Adapter design pattern and create an abstract session bean that serves as a super class of all session beans.

public abstract class AbstractSessionBean implements SessionBean
{
	/** Logging facility */
	protected static Logger LOG = Logger.getLogger(AbstractSessionBean.class);
	/** Session context */
	protected SessionContext	sessionContext;

	/**
	 * @see javax.ejb.SessionBean#ejbActivate()
	 */
	public void ejbActivate() throws EJBException, RemoteException
	{
	}

	/**
	 * @see javax.ejb.SessionBean#ejbPassivate()
	 */
	public void ejbPassivate() throws EJBException, RemoteException
	{
	}

	/**
	 * @see javax.ejb.SessionBean#ejbRemove()
	 */
	public void ejbRemove() throws EJBException, RemoteException
	{
	}

	/**
	 * @see javax.ejb.SessionBean#setSessionContext(javax.ejb.SessionContext)
	 */
	public void setSessionContext(SessionContext sessionContext) throws EJBException, RemoteException
	{
		this.sessionContext = sessionContext;
	}
}

Using such an adapter we can avoid code repetition in functional session beans. It could be also a good idea to put the logging facility into this abstract class. Any functional bean extends AbstractSessionBean and overwrites the ejbCreate() method which is used to setup the working copy of a Bean. Mostly, references to other beans are initialized in this method. Due to the usage of XDoclet, we follow the Factory pattern implemented in the EJB-Util class, which simplifies access to other EJBs.

In our example we flatten the exception handling to the minimum and introduce one exception class for every functional bean, which is thrown by any error during processing. Therefore, any functional methods throw this exception. Usually, exceptions should be topic-related instead of being bean-related.

Information needed for XDoclet generation is stored in the corresponding XDoclet tags inside of the JavaDoc comments. For the full list of XDoclet tag please refer to the XDoclet site. We only explain the tags, we use. The ejb.bean tag indicates that a class is an EJB, providing a name, display-name, description as well as JNDI-Names of LocalHome interface and of the bean itself. The visibility is controlled over the view-type tag, the transactionality over transaction-type tag. Every business method we want to be included to business interfaces (Remote or Local) should be tagged with ejb.interface-method with corresponding view-type. Using this simple rule set we can easily implement business logic layer based on the stateless session beans:

/**
 * ...
 * @ejb.bean name="SensorManager"
 *  description="A Bean responsible for sensor operations"
 *  display-name="SensorManagerBean"
 *  jndi-name="techjava/SensorManagerrBean"
 *  local-jndi-name="techjava/SensorManagerLocalHome"
 *  type="Stateless"
 *  transaction-type="Container"
 *  view-type="both"
 * ...
 */
public class SensorManagerBean extends AbstractSessionBean
{

	/**
	 * Max number of returned values
	 */
	private static final long MAX_DURATION = 60;

	/**
	 * Retrieves data from sensors
	 * @param sensorId id of sensor to query
	 * @param timespanStart start of the time period
	 * @param timespanEnd end of the time period
	 * @return a collection of Measurement POJOs or an empty collection
	 * @throws SensorManagerException if something goes wrong
	 * @ejb.interface-method view-type="both"
	 */
	public Collection getSensorData(Long sensorId, Date timespanStart, Date timespanEnd)
          throws SensorManagerException
	{
		Collection ret = new Vector();
		LOG.debug("Entering getSensorData()");
		if (sensorId == null || timespanStart == null || timespanEnd == null)
		{
			throw new SensorManagerException("Missing a mandatory parameter, that was null (not set)");
		} else if (!timespanStart.before(timespanEnd)) {
			throw new SensorManagerException("The timespan is defined by the start that should be before end");
		}

		for (long i = 0; i < getNumberOfElements(timespanStart, timespanEnd); i++)
		{
			Date date = new Date(timespanStart.getTime() + i*1000*60);
			if (date.after(timespanEnd))
			{
				break;
			}

			Measurement measurement = createMeasurement(sensorId, date, i);
			ret.add(measurement);
		}

		LOG.debug("Leaving getSensorData(). Returning " + ret.size() +" values");
		return ret;
	}

        /**
	 * retrieves the number of measurements in timespan
	 * @param timespanStart
	 * @param timespanEnd
	 * @return
	 */
	public long getNumberOfElements(Date timespanStart, Date timespanEnd) {	... }

	/**
	 * Creates a measurement instance
	 * @param sensorId
	 * @param timestamp
	 * @param number
	 * @return
	 */
	public Measurement createMeasurement(Long sensorId, Date timestamp, long number) { ... }
}

In order to generate the artifacts required by the specification from the written bean, we need to call a corresponding EJBDoclet task. The task itself is configuring only main generation options, during the subtasks are invoked for artifact generation. We used to separate classes of different purpose by packages and massively use the packageSubstitution subtask for this purpose. Remote, local, local home and remote home interfaces, util factory class and both EJB and a vendor-specific descriptors are generated using corresponding tasks.

After generation of the classes and descriptors, which will be executed in a separate directory, it is a good idea to copy the descriptors back to the primary source folder, in order to allow for Eclipse to work with generated descriptors. Now we can compile the hand written code, together with generated code, put the results in a Java archive and assembly it to an enterprise archive, which can be deployed on an application server.

Hands on the Web Service Definition

The design of the interface definition is in general one of the most important steps in the component development life cycle. Depending on the quality of the interface design the component becomes reuseable or remains in usage only in the application it was initially built for. Therefore, we rely on a human engineering instead of generation.

For the definition of our Web Service, we use a standard language for this purpose, the WSDL. A WSDL file has a following structure:

Types
Messages
Operations
Port Type
Bindings
Services

As long as we intend to use document-literal, SOAP-style Web Services, the Binding and the Service parts are straight forward. The only thing we should pay attention is the Fault definition. We start from the Port Type definition, which is the equivalence of the business interface. A Port Type has a name and a collection of operation definitions, containing references to incoming, outgoing and fault messages. The Message part defines how XML Schema Types are used in the operations. This means that the most important parts of the WSDL file are the introduced Types, which are defined using XML Schema and the Port Types, which defines Operations, which use the Types.

The main purpose of a WSDL file is to define an interface. In order to distinguish it from the others, the interface is named. As long as WSDL defines a web-accessible resource, we use full qualified names, similar to XML target namespace.

Web Service Implementation

The created WSDL file is used for further Java code generation. For this purpose we use WSCompile, a tool supplied with Sun’s Java Web Service Developer Pack. The tool need a configuration file (wsdl-config.xml) storing the location of the WSDL file and namespace-to-package mappings. As a result of its execution, the tool generate Java classes for every custom type defined in XML Schema and the descriptor for JAX-RPC mapping required by the container for serialization and deserialization. In addition, it creates a Service interface, that is a interface to the factory of generated Port Type interfaces. The tool also generate implementation stubs for every Port Type, which can be ignored.

The WS Compile is usually called from the command line, but we use the Ant Task for this. Important are the features passed to the generator: documentliteral, wsi, searchschema, serializeinterfaces and explicitcontext. The path to the generated JAX-RPC mapping file is provided by the mapping attribute. Pay attention on the tool call, because depending on parameters given it generates Java classes from WSDL or vice versa.

After we generated the Java representation of the Web Service interface, we can integrate it with our EJB implementation. In order to do this, we used to create a Facade session bean, that implements the Port Type interface. The methods of the facade bean provide some parameter validation, form the values needed for the calculations, invoke the corresponding EJBs, receive results or exceptions and, finally, form the response object or fault. The XDoclet annotation of the facade bean follows the one discussed above, but differs from it slightly. The view-type attribute of the ejb.bean tag should hold the value remote-service-endpoint. In addition, the ejb.interface tag provide information about the Java Port Type interface and about the special Endpoint interface, that is required for the container. In order to generate the Endpoint interface, we add the service-endpoint subtask to the ejbdoclet task.

...
/**
 * @ejb.interface
 *  service-endpoint-class="de.techjava.sensor.interfaces.session.MeasurementProviderFacadeConnectorEndpoint"
 *  service-endpoint-extends="de.techjava.sensor.interfaces.stubs.MeasurementProviderPortType"
 * @wsee.port-component
 * 	name="MeasurementProviderService"
 * 	local-part="MeasurementProviderService"
 * 	display-name="MeasurementProviderService"
 * 	description="MeasurementProvider Bean exposed as a web service"
 */
public class MeasurementProviderFacadeBean
	extends AbstractSessionBean
	implements MeasurementProviderPortType
{
	private SensorManagerLocal sensorManagerLocal = null;

	/**
	 * Creates a link to SensorManager
	 * @see de.techjava.sensor.ejb.session.AbstractSessionBean#ejbCreate()
	 */
	public void ejbCreate()
		throws EJBException
	{
		try
		{
			sensorManagerLocal = SensorManagerUtil.getLocalHome().create();
		} catch (CreateException e)
		{
			throw new EJBException("Error creating new Session Manager instance");
		} catch (NamingException e)
		{
			throw new EJBException("Session Manager Local Home could not be found in JNDI");
		}
	}

	/**
         * Method called on web service message receipt
	 * @ejb.interface-method view-type="remote-service-endpoint"
	 */
	public GetSensorDataResponse getSensorData(GetSensorData parameters)
		throws GetSensorDataFault
	{
		LOG.debug("Received a web service request getSensorData()");
		if (parameters == null
                  || parameters.getTimespan() == null
                  || parameters.getTimespan().getEnd() == null
                  || parameters.getTimespan().getStart() == null)
		{
			LOG.debug("Leaving getSensorData() with error");
			throw new GetSensorDataFault("Wrong request, check mandatory parameters");
		}
		if (sensorManagerLocal == null)
		{
			LOG.debug("Leaving getSensorData() with error");
			throw new GetSensorDataFault("Sensor Manager is not available");
		}

		Long sensorId = new Long(parameters.getSensorid());
		Date timespanStart = parameters.getTimespan().getStart().getTime();
		Date timespanEnd = parameters.getTimespan().getEnd().getTime();

		try
		{
			Collection simpleMeasurements = sensorManagerLocal.getSensorData(sensorId, timespanStart, timespanEnd);
			Vector measurements = new Vector(simpleMeasurements.size());
			Iterator simpleMeasurementI = simpleMeasurements.iterator();

			// convert types from EJB to generated XSD representations
			while(simpleMeasurementI.hasNext())
			{
				SimpleMeasurement sm = (SimpleMeasurement) simpleMeasurementI.next();
				Measurement measurement = convertMeasurement(sm);
				measurements.add(measurement);
			}

			GetSensorDataResponse response = new GetSensorDataResponse();
			response.setMeasurements((Measurement[]) measurements.toArray(new Measurement[measurements.size()]));
			LOG.debug("Leaving getSensorData().");
			return response;

		} catch (SensorManagerException e)
		{
			LOG.debug("Leaving getSensorData() with error");
			throw new GetSensorDataFault(e.getMessage());
		}
	}

}

In addition, the special J2EE Web Service descriptor webservices.xml needs to be created. For this purpose we use WSEE-Doclet, that introduces its own tags. The wsee-port-component provides display-name, web-service-description-name and port-component-name in the attributes name, local-part and display-name. The WSEE-Doclet is started from an Ant task and has one subtask wsee-deploymentdescriptor which is used to generate the required webservice.xml file.

...

	
		
	
	

...

Outline

For testing of Web Services is an important step of development. Especially, the resulting SOAP messages should be reviewed at least once, to ensure that the description is completed correctly, and no malformed XML structures are used. In order to play around with fresh-deployed Web Service open a browser of you choice and enter the URL of the web service overview of your application server. If JBoss (>4.0.5) runs locally, this will be http://localhost:8080/jbossws/. You should see a list of deployed web services. By clicking on a wsdl-button you can retrieve the version of WSDL after deployment (containing the target URL of the endpoint interface). Using this WSDL you can run tests of your web service. We use Eclipse’s Web Service Explorer to run developer tests (WTP installation needed). You can access it under Run -> Launch the Web Service Explorer. Switsch to WSDL-Page by clicking on the second button from right, in the upper right corner, enter the URL and hit Go. Fill the form generated for each method, send the request and analsye the response. If you want to create more advanced tests (and test suites) please refer to SOAP-UI Project.

Resources

You can download the zip file ( de.techjava.ws4j2ee14.sensor_20080219_src.zip) containing the example above.

References

[2004,techreport] bibtex

S. Microsystems, "The Java Web Services Tutorial," 2004.

@techreport{SUN_2004_JWSTUTORIAL, author = {Sun Microsystems}, title = {The Java Web Services Tutorial}, month = Jun, year = {2004}, url = {http://java.sun.com/webservices/docs/1.4/tutorial/doc/index.html} }
[2003,book] bibtex

O. Ihns, S. M. Heldt, R. Wirdemann, and H. Zuzmann, Enterprise JavaBeans komplett, publisher Oldenburg, , 2003.

@Book{IHNS_2003, author = {Oliver Ihns and Stefan M. Heldt and Ralf Wirdemann and Henning Zuzmann}, title = {Enterprise JavaBeans komplett}, publisher {Oldenburg}, year = {2003}, month = {Oct}, url = {http://www.ejbkomplett.de/} }
[2000,book] bibtex

K. Czarnecki and U. W. Eisenecker, Generative Programming, publisher Addison-Wesley, , 2000.

@Book{CZARNECKI_2003, author = {Krzysztof Czarnecki and Ulrich W. Eisenecker}, title = {Generative Programming}, publisher {Addison-Wesley}, year = {2000}, month = {May}, }
[1994,book] bibtex

E. Gamma, R. Helm, R. Johnson, and J. Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software, , 1994.

@Book{GAMMA_1994, author = {Erich Gamma and Richard Helm and Ralph Johnson and John Vlissides}, title = {Design Patterns: Elements of Reusable Object-Oriented Software}, year = {1994} }
[,techreport] bibtex

"XDoclet Project,".

@techreport{XDOCLET, author = {}, title = {XDoclet Project}, url = {http://xdoclet.sourceforge.net/xdoclet/index.html} }