TechJava» TechJava – Articles tagged by web service

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} }

Using SOAP on Nokia 6131 NFC

Simon Zambrovski — Mon, 25 Feb 2008 14:50:38 +0000

Introduction

During some work executed for the proposal to the NFC Congress 2008, we introduced a scenario for using the NFC-enabled Nokia 6131 in the industrial environment. The selected use case records some NFC data and uses the Internet to transmit it to the cental server. During the prototype construction, we decided to use Google Maps as a framework for location-based display of gathered information. The server has been constructed based on J2EE EJBs and exposes its functionality using SOAP-based document-literal Web Serives, as described in one of the privious posts.

Nokia 6131 NFC

The Nokia 6131 NFC is first NFC-enabled mobile phone. NFC stands for Near-Field-Communication – a new evolving wireless technology to interact with RFID tags. It is strongly supported and pushed by several big players. This results in several conferences around this subject all around the world.
The NFC in Java is specified in JSR 257. In addition to that, 6131 seems to support several other JSRs, also including JSR 172 for Web Services. After having a closer look on the offered API, it cames out, that only the XML-parser part of JSR 172 is supported.

Sending SOAP Requests without JSR 172

In order to set the requests to a Web Service from a mobile phone, that does not supprt Web Service JSR 172, a manual creation of request is needed. This results in something like:

public abstract class SoapHandler extends DefaultHandler {

    public static final String SOAP_BEGIN = "";
    public static final String SOAP_END = "";

    private StringBuffer reqBuf = new StringBuffer(); // Buffer that holds the request message

    ...
    public SoapHandler(String message) {
        reqBuf.append(message);
    }

    public int doHttpRequest(String url, String soapAction) throws IOException {

        reqBuf.insert(0, SOAP_BEGIN);
        reqBuf.append(SOAP_END);

        HttpConnection httpConn = (HttpConnection) Connector.open(url);
        httpConn.setRequestMethod(HttpConnection.POST);
        httpConn.setRequestProperty("SOAPAction", soapAction);
        httpConn.setRequestProperty("Content-Length", Integer.toString(reqBuf.length()));

        OutputStream os = httpConn.openOutputStream();

        os.write(reqBuf.toString().getBytes());
        os.close(); // Request is sent when output-stream is closed
        return httpConn.getResponseCode();
    }

...
}

If you execute the code above, the 6131 device send a HTTP request using Content-Type plain/text, that is automatically inserted and changes the case of “SOAPAction” to lower. As long as JBoss 4.0.5 GA used in this experiment supports only Content-Types application/soap+xml and text/xml (as it should according to the specification), it throws a SOAP Exception:

javax.xml.soap.SOAPException: Unsupported content type: text/plain
        at org.jboss.ws.soap.MessageFactoryImpl.createMessageInternal(MessageFactoryImpl.java:138)
        at org.jboss.ws.soap.MessageFactoryImpl.createMessage(MessageFactoryImpl.java:87)
        at org.jboss.ws.server.ServiceEndpoint.handleRequest(ServiceEndpoint.java:190)
        at org.jboss.ws.server.ServiceEndpointManager.processSOAPRequest(ServiceEndpointManager.java:355)
        at org.jboss.ws.server.StandardEndpointServlet.doPost(StandardEndpointServlet.java:115)
        at javax.servlet.http.HttpServlet.service(HttpServlet.java:717)
        at org.jboss.ws.server.StandardEndpointServlet.service(StandardEndpointServlet.java:76)
        at javax.servlet.http.HttpServlet.service(HttpServlet.java:810)
        ...

The MIME Content-Type can easily be set on any HTTP connection:

        httpConn.setRequestProperty("Content-Type", "application/soap+xml");

This works well in the NFC Nokia simulator, part of the Nokia SDK, but breaks down executed from the device. It seems to be a bug in the implementation, or an intended feature of Nokia limiting the usage of the phone for business applications, but the HTTP-Request contains a duplicate Content-Type entry valued by the “application/soap+xml”. Playing around with the implementation, we found that it put any Content-Type header twice into the request. Decompiling and analyzing of simulator code does not helped at all. Since we don’t know how to get and patch sources of J2ME port to Nokia 6131, I decided to apply a workaround.

Server tolerance

JBoss reacts to this fact of a duplicate Content-Type header by throwing a SOAPFaultException.

javax.xml.rpc.soap.SOAPFaultException: Could not parse content type:javax.mail.internet.ParseException: Expected ';', got ","
        at org.jboss.ws.jaxrpc.SOAPFaultExceptionHelper.exceptionToFaultMessage(SOAPFaultExceptionHelper.java:194)
        at org.jboss.ws.server.ServiceEndpoint.handleRequest(ServiceEndpoint.java:223)
        at org.jboss.ws.server.ServiceEndpointManager.processSOAPRequest(ServiceEndpointManager.java:355)
        at org.jboss.ws.server.StandardEndpointServlet.doPost(StandardEndpointServlet.java:115)
        at javax.servlet.http.HttpServlet.service(HttpServlet.java:717)
        at org.jboss.ws.server.StandardEndpointServlet.service(StandardEndpointServlet.java:76)
        at javax.servlet.http.HttpServlet.service(HttpServlet.java:810)
        ...

We followed the stacktrace, and identified the class that causes the Execption. It is org.jboss.ws.soap.MessageFactoryImpl located in JBOSS_DEPLOY /jbossws14.sar/jbossws14-core.jar. After some source code alanysis, we found several problems in the implementation:

private static ContentType getContentType(MimeHeaders headers) throws SOAPException
{
	ContentType contentType = null;
	try
	{
		String type[] = headers.getHeader("Content-Type");
		if (type != null)
		{
			contentType = new ContentType(type[0]);
		} else
		{
			contentType = new ContentType("text/xml");
		}
		return contentType;
	} catch (ParseException e)
	{
		String message = (new JBossStringBuilder()).append("Could not parse content type:").append(e).toString();
		throw new SOAPException(message);
	}
}

First of all, we would expect that the array length is proven, before the first element is accessed. Secondly, if multiple same headers are present in the request, their values are combined using a comma resulting in:

application/soap+xml; charset=utf-8, application/soap+xml; charset=utf-8

This combination could make sence if you put multiple Content-Lang headers in your request, but not for Content-Type. So we fixed the implementation by following code, taking only the first Content-Type value from the list, if present:

...
String type[] = headers.getHeader("Content-Type");
if (type != null && type.length != 0)
{
	int index = type[0].indexOf(',');
	String correctedType = (index != -1) ? type[0].substring(0, index) : type[0];

	contentType = new ContentType(correctedType);
} else
{
	contentType = new ContentType("text/xml");
}
return contentType;
...

Summary

Even if Nokia 6131 NFC offers some functionality for the developer, it does not provide the best platform for use case try-outs. Especially, the lack of supported standard (like full JSR 172) and a low-end OS (Symbian 40-Series), and some bugs / features in implementation of connectivity will lead to problems in prototype implementations of use cases…