====== Anotaciones JAX-WS para crear servicios web ======

 --- //[[pedrody@um.es|PEDRO DELGADO YARZA]] 2014/02/13 14:00//

Con FundeWeb resulta posible generar un servicio web e invocar un servicio web con anotaciones proporcionadas por la pila de servicios JAX-WS, para una fácil configuración y despliegue de servicios web.

Para ello vamos a repasar las anotaciones de las que disponemos para poder crear nuestro servicio web desde cero a partir de nuestras clases Java ya creadas.

===== Anotaciones =====

**@WebService**: Utilizada para especificar que la clase que la contiene ha de convertirse en un servico web. Sus propiedades son:

  * **name**: Por defecto nombre de la clase, equivale a wsdl:portType.
  * **targetNamespace**: El namespace que queremos definir para nuestro servico web.
  * **serviceName**: El nombre del servicio, equivale a wsdl:service. Por defecto nombre de la clase más sufijo "Service".
  * **endpointInterface**: El nombre del endpoint, con esta anotación podeoms desligar la interfaz de la implementación.
  * **portName**: Nombre del puerto del servicio, equivale a wsdl:portName. Por defecto nombre del servicio web más sufijo "Port".
  * **wsdlLocatio**: Ya no se usa en JAX-WS 2.0.

<code java>
@WebService(targetNamespace = "urn:atica:cursosoa:services:conversordivisa", name = "ConversorDivisa")
@XmlSeeAlso({ObjectFactory.class})
public interface ConversorDivisa { ... }

@WebService( serviceName = "ConversorDivisa",
             portName = "ConversorDivisaSOAP",
             targetNamespace = "urn:atica:cursosoa:services:conversordivisa",
             wsdlLocation = "WEB-INF/wsdl/ConversorDivisa.wsdl",
             endpointInterface = "org.umu.atica.wservices.ConversorDivisa")
                      
public class ConversorDivisaImpl implements ConversorDivisa { ... }
</code>

**@WebMethod**: Situada sobre un método de nuestro código, se utiliza para exponer esa operación en el servicio web. 

  * **operationName**: Nombre de la operación, por defecto el nombre de nuestro método.
  * **action**: El espacio de nombres de la operación.
  * **exclude**: La ponemos a "true" si queremos excluir la operación del servicio.

**@WebParam**: Situada dentro de los parámetros de un método de nuestro código se utiliza para personalizar el mapeo de un parámetro concreto, entre el dato que se expone en el servicio y con el tipo java correspondiente. Sus principales propiedades son:

  * **name**: Nombre del parámetro que se expondrá en el servicio web.
  * **targetNamespace**: El espacio de nombres que tendrá el servicio web.

**@WebResult**: Situada sobre un método de nuestro código, se utiliza para personalizar el mapeo del resultado de dicho método. Sus principales propiedades son:

  * **name**: Nombre del parámetro que se expondrá en el servicio web.
  * **targetNamespace**: El espacio de nombres que tendrá el servicio web.

**@RequestWrapper**: Situado en la cabecera de un método indica la clase Java que mapea la petición del servicio web para ese método. Sus principales propiedades son:

  * **localName**: Nombre de la operación tal y como estará definida en el WSDL que se genere.
  * **targetNamespace**: El espacio de nombres que tendrá el servicio web.
  * **className**: Nombre de la clase Java que encapsula la petición.


A continuación mostramos un ejemplo completo de la definición de un método con los parámetros anteriores:

<code java>
@WebResult(name = "ValorCambio", targetNamespace = "")
    @RequestWrapper(localName = "ObtenCambio", targetNamespace = "urn:atica:cursosoa:services:conversordivisa", className = "org.umu.atica.wservices.ObtenCambio")
    @WebMethod(operationName = "ObtenCambio", action = "urn:atica:cursosoa:services:conversordivisa/ObtenCambio")
    @ResponseWrapper(localName = "ObtenCambioResponse", targetNamespace = "urn:atica:cursosoa:services:conversordivisa", className = "org.umu.atica.wservices.ObtenCambioResponse")
    public double obtenCambio(
        @WebParam(name = "MonedaOrigen", targetNamespace = "")
        org.umu.atica.wservices.MonedaType monedaOrigen,
        @WebParam(name = "MonedaDestino", targetNamespace = "")
        org.umu.atica.wservices.MonedaType monedaDestino
    );
</code>
===== Definición del servicio web =====

En primer lugar debemos una interfaz con las anotaciones necesarias para utilizar un EJB como un servicio web. 

<code java>
@WebService(targetNamespace = "urn:atica:cursosoa:services:conversordivisa", name = "ConversorDivisa")
@XmlSeeAlso({ObjectFactory.class})
public interface ConversorDivisa {

    @WebResult(name = "ValorCambio", targetNamespace = "")
    @RequestWrapper(localName = "ObtenCambio", targetNamespace = "urn:atica:cursosoa:services:conversordivisa", className = "org.umu.atica.wservices.ObtenCambio")
    @WebMethod(operationName = "ObtenCambio", action = "urn:atica:cursosoa:services:conversordivisa/ObtenCambio")
    @ResponseWrapper(localName = "ObtenCambioResponse", targetNamespace = "urn:atica:cursosoa:services:conversordivisa", className = "org.umu.atica.wservices.ObtenCambioResponse")
    public double obtenCambio(
        @WebParam(name = "MonedaOrigen", targetNamespace = "")
        org.umu.atica.wservices.MonedaType monedaOrigen,
        @WebParam(name = "MonedaDestino", targetNamespace = "")
        org.umu.atica.wservices.MonedaType monedaDestino
    )
    
    ...
    
  }
</code>

Tras ello definimos la clase que implementará la interfaz.

<code java>
WebService( serviceName = "ConversorDivisa",
            portName = "ConversorDivisaSOAP",
            targetNamespace = "urn:atica:cursosoa:services:conversordivisa",
            wsdlLocation = "WEB-INF/wsdl/ConversorDivisa.wsdl",
            endpointInterface = "org.umu.atica.wservices.ConversorDivisa")
                      
public class ConversorDivisaImpl implements ConversorDivisa {

    private static final Logger LOG = Logger.getLogger(ConversorDivisaImpl.class.getName());

    public double obtenCambio(org.umu.atica.wservices.MonedaType monedaOrigen,org.umu.atica.wservices.MonedaType monedaDestino) { 
        LOG.info("Executing operation obtenCambio");
        try {
           ...
           ...
        } catch (java.lang.Exception ex) {
           ...
        }
    }
    ... 
}
</code>

Por último debemos asegurarnos que en el fichero **components.xml** tenemos habilitado el contexto para el servicio web, en nuestro caso sería este:
<code xml>
   <web:context-filter url-pattern="/services/*" />
</code>