Anotaciones y Propiedades de Webservice SOAP
El objetivo del post de hoy es intentar dar una visión general de cuáles son los tipos de anotaciones y de propiedades que nos podemos encontrar en la definición de un webservice de tipo SOAP. Por supuesto, no pretende ser una guía exhaustiva (para eso ya tenemos los manuales de usuario), sino simplemente hacer referencia sobre todo a las más importantes. Creo que, a la hora de enfrentarnos con la codificación de un nuevo webservice, lo más operativo es contar con un resumen de las etiquetas SOAP más utilizadas.
En general, trabajar con la lista completa de Propiedades no suele ayudar mucho a desarrollar con rapidez, de ahí que quiera centrarme sólo en lo más relevante. Sin embargo, en alguna ocasión necesitaremos disponer de dicha lista para poder encontrar el detalle de alguna propiedad que no solemos usar normalmente. Para esos casos, os dejo aquí el enlace de IBM con la guía de referencia de Anotaciones y Propiedades de los webservices SOAP.
https://www.ibm.com/docs/es/was/9.0.5?topic=ws-jax-annotations
Anotaciones de Webservice SOAP
En primer lugar, vamos a revisar cuáles son las principales anotaciones que nos podemos encontrar en las implementaciones de los servicios SOAP. Aunque la mayoría se encuentran en el servicio del servidor, también haremos un repaso de las existentes en la parte del cliente.
👉 En los servicios del lado servidor nos podremos encontrar las siguientes anotaciones:
- @WebService: clase que va a actuar como webservice.
- Propiedades: name, targetNamespace, serviceName, wsdlLocation, endpointInterface, portName
- @WebMethod: métodos que deben ser publicados.
- Propiedades: operationName, action, exclude
- @SOAPBinding: requisitos que debe cumplir el webservice.
- Propiedades: style, use, ParameterStyle
- @WebParam: parámetros precisados por los métodos publicados.
- Propiedades: name, targetNamespace, mode, header, partName
- @WebResult: parámetros devueltos por los métodos publicados.
- Propiedades: name, targetNamespace, header, partName
- @WebFault: excepciones devueltas por el webservice.
- Propiedades: name, targetNamespace, faultBean
👉 En los servicios del lado del cliente nos podremos encontrar las siguientes anotaciones:
- @WebServiceClient: clase que va a actuar como servicio cliente.
- Propiedades: name, targetNamespace, wsdlLocation
- @WebEndpoint: ubicación de la clase que actúa como servicio del servidor.
- Propiedades: name
- @Action: acciones (request/response) que puede realizar el webservice publicado.
- Propiedades: input, output, fault
- @FaultAction: asocia acciones con mensajes Fault del WSDL (los Fault son mapeos de las excepciones del webservice).
- Propiedades: className, value
Propiedades de los Webservices SOAP
Una vez revisadas las anotaciones principales, vamos a aprovechar el tiempo y echarle un vistazo a algunas de las Propiedades que podemos encontrarnos en los webservices. Comparada con las anotaciones, aquí la variedad de etiquetas se multiplica, así que vamos a intentar revisar sólo aquellas más relevantes.
✅ Anotación @WebService
Las propiedades asociadas a la anotación @WebService son las siguientes:
* Propiedad name: Este es el nombre que queremos asignar a la variable "portType" del WSDL. Por defecto, es el nombre de la clase Java. El "portType" es la interfaz que define un webservice, así que con esta propiedad le estamos proporcionando un nombre único a nuestro servicio.
* Propiedad targetNamespace: Se especifica el Namespace de los elementos WSDL generados a partir del webservice. El Namespace proporciona un espacio de nombres que permite evitar conflictos de nomenclatura.
* Propiedad serviceName: Nombre del identificador "service" del WSDL, esto es, nombre del servicio que será utilizado para crear el endpoint. Por defecto, es el nombre de la clase Java más el sufijo "Service".
* Propiedad endpointInterface: Nombre calificado de la interfaz del endpoint que se define en el WSDL. Se trata de la localización específica para acceder al webservice.
* Propiedad portName: Nombre que queremos asignar a la variable "portName" del WSDL. Por defecto, este valor es igual a la propiedad "name" (en principio, el nombre de la clase Java) más el sufijo "Port".
* Propiedad wsdlLocation: Indica la ubicación web del WSDL del webservice (siempre y cuando no queramos usar la ubicación por defecto).
🌐 Ejemplo de uso:
@WebService(name="HolaMundoPortType",
targetNamespace="http://server.soap.universo.com/",
serviceName="HolaMundoService",
endpointInterface="com.universo.soap.server.HolaMundo",
portName="HolaMundoPortName")
🌐 Esto se corresponde en el servicio cliente con las siguientes clases:
* HolaMundoPortType.java: se trata de una interface que se crea para apuntar al webservice que hemos creado en el servidor. De hecho, apunta a la clase HolaMundo.java del paquete com.universo.soap.server del proyecto del servidor.
// **************************************************
@WebService(
name = "HolaMundoPortType",
targetNamespace = "http://server.soap.universo.com/")
public interface HolaMundoPortType {
* HolaMundoService.java: se trata de la clase que implementa las herramientas necesarias para realizar la llamada al webservice del servidor.
// **************************************************
@WebServiceClient(name = "HolaMundoService",
targetNamespace = "http://server.soap.universo.com/",
wsdlLocation = "http://localhost:8080/AnotacionSoapApp/ws/hola?wsdl")
public class HolaMundoService extends Service {
En concreto, dentro de la clase HolaMundoService.java se crea el método getHolaMundoPortName(), que recupera un objeto de tipo HolaMundoPortType.
@WebEndpoint(name = "HolaMundoPortName")
public HolaMundoPortType getHolaMundoPortName() {
✅ Anotación @WebFault
Esta anotación nos permite mapear las faults del fichero WSDL con las excepciones Java. De hecho, se puede usar para personalizar la transformación de una excepción específica en una fault. Las propiedades asociadas a la anotación @WebFault son las siguientes:
* Propiedad name: este es el nombre que queremos asociar al elemento XML que representa al correspondiente Fault del fichero WSDL.
* Propiedad targetNamespace: valor del namespace del elemento XML que se corresponde con el Fault existente en el WSDL.
* Propiedad faultBean: aquí tenemos que especificar el nombre del objeto que va a ser usado como clase Fault.
* Propiedad messageName: se trata del valor del atributo "message" asociado al elemento Fault del fichero WSDL.
🌐 Ejemplo de uso:
@WebFault(name="operationfault",
targetNamespace = "http://server.soap.universo.com/",
faultBean="com.universo.soap.server.BaseException")
🌐 Esto se corresponde en el servicio cliente con las siguientes clases:
* OperacionFault.java: se trata de la clase que nos permite capturar los Fault generados por el welbservice ubicado en el servidor.
// **************************************************
@WebFault(name = "operationfault",
targetNamespace = "http://server.soap.universo.com/")
public class OperacionFault extends Exception {
* BaseException.java: se trata de la clase que contiene la estructura de las excepciones generadas por los Fault del webservice.
// **************************************************
@XmlType(name = "baseException", propOrder = {
"errorDesc",
"errorID",
"errorType"
})
public class BaseException {
Por supuesto, todos sabemos que existen muchos más tipos de anotaciones y propiedades en los webservices SOAP, pero los aquí mencionados nos deberían bastar para trabajar de forma dinámica. Poco a poco intentaré completar un poco esta lista, aunque en ningún momento la idea es disponer de un catálogo exhaustivo. Una vez que tengamos agilidad con las propiedades básicas, ya no nos resultará demasiado complicado investigar alguna propiedad menos conocida si lo necesitamos en algún momento de nuestra vida como programador.
Pues nada, eso es todo lo que quería comentar en relación con las Anotaciones y Propiedades de los webservices SOAP. Espero que la lista nos sirva al menos para poder arrancar con la codificación de este tipo de servicios. Seguro que a algunos nos facilitará bastante la vida.
Saludos.
Comentarios
Publicar un comentario