jax-ws: Java Web Services

Para comenzar es necesario descargar el binario correspondiente a la implementacion de referencia de JAX-WS. En la seccion de vinculos se encuentra una referencia al sitio donde puede encontrarlo. Los ejemplos presentados aqui refieren a la distribucion que se encuentra aqui.

Instalacion de JAX-WS

Una vez que se ha obtenido JAX-WS, es necesario instalarlo en el entorno local para comenzar a desarrollar web services. Para ello descomprima la distribucion de JAX-WS de la siguiente manera:

java -jar JAXWSx.x.x-.jar

por ejemplo:

java -jar JAXWS2.1.3-20071218.jar

De esto resultara el directorio jaxws-ri que contiene las librerias, documentacion y ejemplos.

A continuacion se desarrolla un web service y un cliente que consuma el servicio para mostrar, mediante un ejemplo sencillo el proceso de creacion de web services mediante JAX-WS.

Creacion del servicio Echo

El servicio Echo es definido por la interfaz java IEchoService.java y la clase java que implementa dicha interfaz EchoServiceImpl.java. A continuacion se presenta el codigo para ambas, clase e interfaz:

package test.echo.service;

import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService(serviceName="EchoService", name="Echo")
public class EchoService {

@WebMethod()
public String echo(String value) {
return value;
}
}

JAX-WS provee un conjunto de anotaciones que permite convertir una simple clase java en un web service. Como se observa en el ejemplo anterior, la clase java EchoService se encuentra decorada con la anotacion @WebService, que indica que dicha clase es un web service.

La anotacion @WebMethod es utilizada para indicar cuales de los metodos de la clase definida como servicio seran expuestos o publicados.

Las anotaciones que decoran a la clase EchoService deben ser procesadas para que JAX-WS genere las clases adicionales que dan forma al servicio Echo. Para esto es necesario emplear la herramienta Apt (Annotation processing tool) que se encuentra en la libreria jaxws-tools.jar. Esta herramienta puede ser invocada por linea de comando, de la siguiente manera:

apt -classpath C:\jaxws-ri\lib\FastInfoset.jar;
C:\jaxws-ri\lib\activation.jar;
C:\jaxws-ri\lib\http.jar;
C:\jaxws-ri\lib\jaxb-api.jar;
C:\jaxws-ri\lib\jaxb-impl.jar;
C:\jaxws-ri\lib\jaxb-xjc.jar;
C:\jaxws-ri\lib\jaxws-api.jar;
C:\jaxws-ri\lib\jaxws-rt.jar;
C:\jaxws-ri\lib\jaxws-tools.jar;
C:\jaxws-ri\lib\jsr173_api.jar;
C:\jaxws-ri\lib\jsr181-api.jar;
C:\jaxws-ri\lib\jsr250-api.jar;
C:\jaxws-ri\lib\resolver.jar;
C:\jaxws-ri\lib\saaj-api.jar;
C:\jaxws-ri\lib\saaj-impl.jar;
C:\jaxws-ri\lib\sjsxp.jar;
C:\jaxws-ri\lib\stax-ex.jar;
C:\jaxws-ri\lib\streambuffer.jar com.sun.tools.apt.Main
-d "jaxws-samples\bin"
-s "jaxws-samples\src"
-sourcepath "jaxws-samples\src"
-g:none "jaxws-samples\src\test\echo\service\IEchoService.java"
"jaxws-samples\src\test\echo\service\EchoServiceImpl.java"

o tambien puede ser incorparada al proceso de costruccion (build), invocada por Ant. Para hacerlo, es necesario primero declarar la tarea correspondiente a Apt, como se muestra a continuacion:

Luego es necesario definir los targets para invocar a la herramienta Apt y compilar la clase que contiene la logica del servicio Echo definida antes:

La ejecucion de Apt generara dos clases:

• Echo.java
• EchoResponse.java

en el directorio test/echo/service/jaxws. Estas dos son clases de bajo nivel y se encargan de encapsular los mensajes SOAP empleados en la consulta y en la respuesta. Son altamente dependientes de anotaciones empleadas por JAXB para el mapeo de XML a objetos java.

Si obtiene el siguiente mensaje de advertencia cuando se ejecuta la tarea que ejecuta apt:

apt:
[apt] warning: Annotation types without processors:
[javax.xml.bind.annotation.XmlRootElement,
javax.xml.bind.annotation.XmlAccessorType, javax.xml.bind.annotation.XmlType,
javax.xml.bind.annotation.XmlElement]
[apt] 1 warning

asegurece que apt recibe como argumento fork="true".

Si obtiene el siguiente mensaje:

apt:
[apt] java.lang.NoClassDefFoundError: com/sun/tools/apt/Main
[apt] Exception in thread "main"

asegurece que tools.jar, distribuido junto con el JRE, este incluido en el classpath empleado para ejecutar apt.

Ahora sera necesario generar el wsdl empleado para publicar el servicio. Para esto se debe emplear otra herramienta de JAX-WS llamada wsgen. A continuacion se muestra como ejecutar la herramienta wsgen por linea de comando:

C:\jaxws-ri\bin>wsgen -cp "project-home\jaxws-samples\bin"
 -d "project-home\jaxws-samples\bin" -keep -wsdl
 -r "project-home\jaxws-samples\src\test\echo\service\wsdl"
 -s "project-home\jaxws-samples\src" test.echo.service.EchoService

o tambien puede ser incorparada al proceso de costruccion (build), invocada por Ant. Para hacerlo, es necesario primero declarar la tarea correspondiente a wsgen, como se muestra a continuacion:

Luego se define el target para invocar a la herramienta wsgen y generar el wsdl correspondiente al servicio:

Creacion del cliente para el servicio Echo

wsimport

Buildfile: C:\Documents and Settings\sg0203921\workspacee\jaxws-samples\build.xml
Trying to override old definition of task apt
wsimport:
[wsimport] parsing WSDL...
[wsimport] generating code...
[wsimport] compiling code...
BUILD SUCCESSFUL
Total time: 6 seconds

Clases generadas:

• Echo_Type.java
• Echo.java
• EchoResponse.java
• EchoService.java
• ObjectFactory.java
• package-info.java

Publicacion del servicio Echo en Tomcat 6

Vinculos:

• JAX-WS Reference implementation
• JAX-WS 2.1 JavaDoc
  
• Java API for XML Web Services - Annotations
• Annotation Processing Tool (apt)
• wsgen command line tool and Ant task (2.0) @ java.sun.com
  
• wsgen command line tool (2.1.2) @ java.net
• war Ant task
• Apache Tomcat