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.
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.
@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
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.
<?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.
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;
}
}