JAX-WS simplifies the development model for a web service endpoint a great deal. In short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. The server automatically generates and publishes the abstract contract (i.e. wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to JAXB.  

Setting up your environment

This sample has been tested with JBoss-5.0.0.CR2 and JBoss WS native 3.0.4

To get started you need to download jbossws and install JBossWS on your preferred target container.

http://www.jboss.org/downloading/?projectId=jbossws&url=/jbossws/downloads/jbossws-native-3.0.4.GA.zip

Follow the installing instructions from the binary distribution. I'd suggest you as well to take a look at the JBoss Sample suite which allows you to test all the Web Service Stack both with Ant scripts and with the Eclipse IDE. Here's a link for it:

http://jbossws.jboss.org/mediawiki/index.php?title=Samples_testsuite
 

EJB 3.0 web services

Let’s first see a straightforward example:  here you expose an EJB 3.0 as a web service. After we'll  dive into the details of some commonly used annotations that can make defining web services even easier. 

package samples.webservice;

import javax.ejb.Remote;
import javax.ejb.Stateless;
import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

import org.jboss.wsf.spi.annotation.WebContext;


@WebService(name = "EndpointInterface", targetNamespace = "http://www.openuri.org/2004/04/HelloWorld", serviceName = "HelloWorldService")
@SOAPBinding(style = SOAPBinding.Style.RPC)
@Remote(HelloRemote.class)
@Stateless
public class HelloWorld implements HelloRemote
{
   @WebMethod
   public String echo(String input)
   {
      return input;
   }
   
    
   
}

package samples.webservice;

import javax.jws.WebParam;
import javax.jws.WebService;
 
 
@WebService
public interface HelloRemote
 
{
   public String echo(String input);
   
    
}

In this sample we have used the @javax.jws.WebService annotation to expose HelloWorld Bean as a web service.

The @WebService annotation can also specify the name of the web service. If you don’t specify the name element, the name of the bean class or interface will be used by default.

You can use the targetNamespace element to specify the target namespace for the WSDL elements generated by the web service. If you don’t specify this element, the EJB container will use the Java package name to generate a default XML namespace.

You can use the serviceName element to specify the service name. Specifying the serviceName is only allowed when you annotate the bean class. The name specified using serviceName is used for generating the name attribute in the service element in the WSDL. If you don’t specify the serviceName element, the server will generate it using the default, which is the bean class name appended with Service.

We specified that the web service is a document-style web service by using the @javax.jws.SOAPBinding annotation.

We used the @javax.jws.WebMethod annotation to expose the echo method in the web service. If you use the @WebService annotation on the interface, then all public methods on the web service endpoint will be exposed in the web service.

A client for our web service can be as simple as this:
 

package samples.webservice;

import java.net.MalformedURLException;
import java.net.URL;

import javax.xml.namespace.QName;
import javax.xml.ws.Service;
 

public class TestEJB {
 
	public static void main(String args[]) throws Exception {
	  String endpointURI ="http://127.0.0.1:8080/ejb/HelloWorld?wsdl";
	  String helloWorld = "Hello world!";
		 
	  Object retObj = getPort(endpointURI).echo(helloWorld);
	  System.out.println(retObj);
	}  
	 private static HelloRemote getPort(String endpointURI) throws MalformedURLException   {
	   QName serviceName = new QName("http://www.openuri.org/2004/04/HelloWorld", "HelloWorldService");
	   URL wsdlURL = new URL(endpointURI);

	   Service service = Service.create(wsdlURL, serviceName);
	   return service.getPort(HelloRemote.class);
	 }
}

Packaging the WebService:

It's just a matter of putting the Bean and the Interface in a jar file. Once you have packed these files put them in the deploy directory of jboss.

verify that JBoss has correclty deployed the web service:
http://localhost:8080/jbossws/services



Running the client should echo your "Hello World" back to the client.
 

Deploying a POJO as web service:

Deploying your ejb as webservice is not your only option: you can deploy a POJO as web service as well. In this case you just need to tag @WebService in a plain java class.
 

package samples.webservice;

import javax.ejb.Remote;
import javax.ejb.Stateless;
import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

import org.jboss.wsf.spi.annotation.WebContext;

@WebService(targetNamespace = "http://www.openuri.org/2004/04/HelloWorld", serviceName = "HelloWorldPOJOService")
@SOAPBinding(style = SOAPBinding.Style.RPC)

public class HelloPOJO  
{
   @WebMethod
   public String hello(String input)
   {
      return "hello from pojo " +input;
   }
   
    
   
}

Package your WebService in a Web Application Archive. Take care to map the WebService as a Servlet in your web-inf.xml
 

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" 
	xmlns="http://java.sun.com/xml/ns/j2ee" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
	http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
	<servlet>
	 <servlet-name>POJOService</servlet-name>
	 <servlet-class>samples.webservice.HelloPOJO</servlet-class>
	</servlet>
	<servlet-mapping>
          <servlet-name>POJOService</servlet-name>
	 <url-pattern>/*</url-pattern>
         </servlet-mapping>
</web-app>

Once deployed the war you should see it in your webservice console:

 

The client logic doesn't change compared with the previous example.

So when you choose EJB over a POJO for a web service?

JAX-WS 2.0 allows both regular Java classes and stateless EJBs to be exposed as web services. If you
were using J2EE 1.4, you’re probably wondering why you’d use a stateless EJB as a web service. A
look at the code for a POJO and for EJB 3 web services reveals that there are hardly any differences,
with the exception that the EJB 3 web service will have a few extra annotations. A Java class web
service is packaged in a web module whereas an EJB web service is packaged in an EJB-JAR.
 

Both a Java web service and an EJB web service support dependency injection and lifecycle
methods such as @PostConstruct and @PreDestroy, but you get a few extra benefits from
using EJB 3 web services.
 

First, you automatically get the benefits of declarative transaction and security available only to
EJB 3 components. You can use interceptors and the timer service if your applications need them,
without depending on extra layering.
Second, a web service that uses EJB 3 can easily expose your business applications using
additional protocols, such as RMI, by adding a remote interface. As you saw in the previous section,
exposing an EJB 3 stateless session bean is easy and can be done by simply adding the
@WebService annotation
 

JBoss.org Search

Custom Search