Utilización de manejadores en los servicios web JAX-WS

JAX-WS (API Java™ para servicios web XML) le proporciona un método estándar para desarrollar servicios web interoperables y transferibles. Utilice los manejadores JAX-WS para personalizar el manejo de respuestas o solicitudes de servicios web.

Antes de empezar

Es necesario un archivo EAR (Enterprise Archive) para las aplicaciones que desea configurar. Si va a realizar la ejecución en un entorno de cliente ligero para JAX-WS, no es necesario que empiece con un archivo EAR. Para algunos usos del manejador, tales como el registro cronológico o el rastreo, sólo es necesario que se configure el servidor o cliente de aplicaciones. Para los demás usos del manejador, incluido el envío de la información en cabeceras SOAP, es necesario que se configuren el cliente y servidor de aplicaciones con manejadores simétricos.

Los módulos del archivo EAR deben contener las clases de manejador que se van a configurar. Las clases de manejador implementan la interfaz javax.xml.ws.handler.LogicalHandler<LogicalMessageContext> o la interfaz javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext>.
Recuerde: Si intercepta un SOAPMessage de entrada y lo manipula, como por ejemplo añadienso un adjunto, debe utilizar la parte setmessage del SOAPMessageContext para asegurarse de que el adjunto forma parte delSOAPMessageContext. Esto garantiza que el tiempo de ejecución JAX-WS puede acceder a este último SOAPMessage para poder procesar correctamente los adjuntos. En el ejemplo siguiente se ilustra este proceso:
 SOAPMessage m = context.getMessage(); 
 AttachmentPart ap1 = m.createAttachmentPart(); 
 ap1.setContent("abc", "text/plain");           
 m.addAttachmentPart(ap1);
 context.setMessage(m);                       

Acerca de esta tarea

Como en el modelo de programación de JAX-RPC (API de Java para RPC basado en XML), el modelo de programación de JAX-WS proporciona un recurso de manejador de aplicaciones que le permite manipular un mensaje en ambos flujos, el de entrada y el de salida. Puede añadir manejadores en el entorno de ejecución JAX-WS para realizar un proceso adicional de mensajes de respuesta y de solicitud. Puede utilizar manejadores para una variedad de fines como, por ejemplo, capturar y registrar información y añadir seguridad u otra información a un mensaje. Debido al soporte para protocolos adicionales más allá de SOAP, JAX-WS ofrece dos clasificaciones diferentes para los manejadores. Un tipo de manejador es un manejador lógico que es independiente del protocolo y puede obtener el mensaje en el flujo como un mensaje XML (Extensible Markup Language). Los manejadores lógicos funcionan en las propiedades del contexto del mensaje y en la carga de datos del mensaje. Estos manejadores deben implementar la interfaz javax.xml.ws.handler.LogicalHandler. Un manejador lógico recibe un objeto LogicalMessageContext desde el cual el manejador puede obtener información del mensaje. Los manejadores lógicos pueden existir en configuraciones basadas en SOAP y también basadas en XML/HTTP.

El segundo tipo de manejador es un manejador de protocolo. Los manejadores de protocolo funcionan en propiedades de contexto de mensaje y en mensajes específicos del protocolo. Los manejadores de protocolo están limitados a las configuraciones basadas en SOAP y deben implementar la interfaz javax.xml.ws.handler.soap.SOAPHandler. Los manejadores de protocolo reciben el mensaje como javax.xml.soap.SOAPMessage para leer los datos del mensaje.

El tiempo de ejecución JAX-WS no hace distinción entre las clases de manejador del lado del servidor y del lado del cliente. El tiempo de ejecución no distingue entre el flujo de entrada y el de salida, cuando se invoca un método handleMessage(MessageContext) o un método handleFault(MessageContext) para un manejador específico. Debe configurar los manejadores para el servidor y el cliente, e implementar la lógica suficiente dentro de estos métodos para detectar la dirección de entrada o salida del mensaje actual.

Para utilizar manejadores con aplicaciones cliente de servicios web, debe añadir la anotación @HandlerChain a la interfaz del punto final de servicio o la clase de servicio generada y proporcionar el archivo de configuración de la cadena del manejador. La anotación @HandlerChain contiene un atributo de archivo que señala a un archivo de configuración de cadena de manejador que ha creado. Para aplicaciones cliente de servicios web, también puede configurar la cadena del manejador mediante programación utilizando la API Binding. Para modificar la clase de la cadena del manejador a través de programa, utilice la implementación predeterminada o una implementación personalizada del método HandlerResolver.

Para utilizar manejadores con la aplicación de servidor, debe establecer la anotación @HandlerChain en la interfaz de punto final de servicio o en la clase de implementación del punto final, y proporcionar el archivo de configuración de la cadena de manejador asociado. Los manejadores del servidor sólo se configuran estableciendo la anotación @HandlerChain en la implementación del punto final de servicio o en la clase de implementación. Las clases de manejador se deben incluir en el archivo EAR de la aplicación de servidor.

Para las implementaciones de servidor y de cliente de los manejadores mediante la anotación @HandlerChain, debe especificación la ubicación de la configuración del manejador como una vía de acceso relativa desde el archivo anotado o como un URL absoluto. Por ejemplo:
@HandlerChain(file="../../common/handlers/myhandlers.xml")
o bien
@HandlerChain(file="http://foo.com/myhandlers.xml")
Si desea más información sobre el esquema del archivo de configuración del manejador, consulte la especificación de JSR 181.

Si desea más información en relación con los manejadores JAX-WS, consulte el capítulo 9 de la especificación JAX-WS.

Procedimiento

  1. Decida si desea implementar manejadores JAX-WS en el servicio o en el cliente.
  2. Configure los manejadores de cliente estableciendo la anotación @HandlerChain en la instancia del servicio o en la interfaz de punto final de servicio, o puede modificar la cadena del manejador a través de programa para controlar cómo se genera la cadena del manejador en el tiempo de ejecución. Si opta por modificar la cadena del manejador a través de programa, debe determinar si utilizará el resolvedor de manejadores predeterminado o si utilizará una implementación personalizada de un resolvedor de manejadores que está registrado en la instancia del servicio. Una instancia de servicio utiliza un resolvedor de manejadores cuando se crean proveedores de enlaces. Cuando se crean los proveedores de enlaces, se utiliza el resolvedor de manejadores que está registrado con un servicio para crear una cadena de manejador y esta cadena se utiliza, posteriormente, para configurar el proveedor de enlaces.
    1. Utilice la implementación predeterminada de un resolvedor de manejadores. Ahora, el tiempo de ejecución utiliza la anotación @HandlerChain y la implementación predeterminada de la clase HandlerResolver para generar la cadena de manejador. Puede obtener la cadena de manejador existente desde Binding, añadir o eliminar manejadores y, a continuación, devolver a la cadena de manejador modificada al objeto Binding.
    2. Para utilizar una implementación personalizada de un resolvedor de manejadores, establezca la clase HandlerResolver personalizada en la instancia del servicio. El tiempo de ejecución utiliza la implementación predeterminada de la clase HandlerResolver para generar la cadena de manejador, y no se utiliza la implementación del tiempo de ejecución predeterminado. En este escenario, la anotación @HandlerChain no se lee cuando se recupera la cadena de manejador del enlace, después de registrar la instancia personalizada HandlerResolver en la instancia del servicio. Puede obtener la cadena de manejador existente desde Binding, añadir o eliminar manejadores y, a continuación, devolver a la cadena de manejador modificada al objeto Binding.
  3. Configure los manejadores del servidor estableciendo la anotación @HandlerChain en la interfaz de punto final de servicio o en la clase de implementación. Cuando se configura la anotación @HandlerChain en la interfaz de punto final de servicio y, también, en la clase de implementación, la clase de implementación tiene prioridad.
  4. Cree el archivo XML de configuración de la cadena de manejador. Debe crear un archivo XML de configuración de cadena de manejador para que @HandlerChain lo tenga de referencia.
  5. Añada el archivo XML de configuración de la cadena de manejador a la vía de acceso de la clase para la interfaz de punto final de servicio, cuando configure los manejadores del servidor o del cliente utilizando la anotación @HandlerChain. También debe incluir las clases de manejador incluidas en el archivo XML de la configuración en la vía de acceso de la clase.
  6. Escriba la implementación del manejador.

Resultados

Ha habilitado el cliente de servicios web JAX-WS o de servicios web para utilizar manejadores para realizar el proceso adicional del intercambio de mensajes de solicitud y de respuesta.

Ejemplo

En el ejemplo siguiente se muestran los pasos necesarios para configurar los manejadores JAX-WS en una interfaz de punto final de servicio utilizando la anotación @HandlerChain.

La anotación @HandlerChain tiene un atributo de archivo que señala un archivo XML de configuración de cadena de manejador que ha creado. En el ejemplo siguiente se muestra un archivo típico de configuración de manejador. Los elementos protocol-bindings, port-name-pattern y service-name-pattern son todos filtros que se utilizan para restringir los servicios que se aplican a los manejadores.
<?xml version="1.0" encoding="UTF-8"?> 

<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
<!-- Nota:  '*" denota un comodín. -->

		<jws:handler-chain name="MyHandlerChain">
				<jws:protocol-bindings>##SOAP11_HTTP ##ANOTHER_BINDING</jws:protocol-bindings>
				<jws:port-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:MySampl*</jws:port-name-pattern>
        <jws:service-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:*</jws:service-name-pattern>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
				</jws:handler>
		</jws:handler-chain>
	
</jws:handler-chains>

</jws:handler-chains>

Asegúrese de añadir el archivo handler.xml y las clases de manejador incluidas en el archivo handler.xml en la vía de acceso de clases.

En el ejemplo siguiente se muestra la implementación de un manejador:
package com.ibm.samples.handlersample;

import java.util.Set;

import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class SampleProtocolHandler implements
        javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> {

    public void close(MessageContext messagecontext) {
    }

    public Set<QName> getHeaders() {
        return null;
    }

    public boolean handleFault(SOAPMessageContext messagecontext) {
        return true;
    }

    public boolean handleMessage(SOAPMessageContext messagecontext) {
        Boolean outbound = (Boolean) messagecontext.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        if (outbound) {
            // Incluir los pasos del flujo de salida.
        }
        return true;
    }

}

Qué hacer a continuación

Despliegue la aplicación de servicios web.

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxwshandler
File name: twbs_jaxwshandler.html