viernes, 31 de octubre de 2014

JAXBException is not a valid property on class

Si estas trabajando con WebServices y recibes este error: JAXBException <prop> is not a valid property on class <class> posiblemente venga dados por los siguientes motivos:


  1. Si el targetNamespace del WSDL usa la notación: camel case, el paquete de tu clases también debes usar camel case. 
  2. Si usas JAX-WS para generar las clases automáticamente usando un WSDL, es importante que definas el paquete. Si tienes dos WSDL y realizas dos WSImport usando el mismo paquete puede que te aparezca el error. Lo mejor es que definas un paquete distinto para las clases generadas y te funcionara. 

miércoles, 29 de octubre de 2014

Solución al Error 206 de Eclipse: El nombre del archivo o extensión es demasiado largo

Seguramente te haya salido este error muchas veces usando Eclipse.


El error 206 puede indicar que la linea de comandos que ejecuta Eclipse bajo Windows es demasiado larga. Este error puede saltar dado que tengas un nombre de paquete de clases excesivamente largo, o bien que el classpath tenga muchas librerías. Es un bug de Eclipse que ya ha sido corregido.

El problema fue resuelto en versiones posteriores a la version de INDIGO 3.8 en adelante. Si estas en versiones anteriores, hay un pequeño parche.

Debes seguir los siguientes pasos:


  1. Dirígete al siguiente enlace: https://bugs.eclipse.org/bugs/show_bug.cgi?id=327193 , y descargate el siguiente fichero: bug327193_3.4.2_hack.zip de la sección de attachment.
  2. Respalda el fichero existente en: eclipse/plugins/org.eclipse.jdt.launching_3.*.*.jar 
  3. Renombra el fichero actual  org.eclipse.jdt.launching_3.*.*.jar a .zip para que puedas abrirlo.
  4. Abre el fichero org.eclipse.jdt.launching_3.*.*.zip y ubica el directorio org/eclipse/jdt/internal/launching
  5. Abre el fichero bug327193_3.4.2_hack.zip. Copia y pega las classes del patch del fichero zip al directorio  org/eclipse/jdt/internal/launching de tu fichero org.eclipse.jdt.launching JAR (reemplazando los ficheros existentes)
  6. Renombra  org.eclipse.jdt.launching_3.*.*.zip a .jar
  7. Este paso es opcional. Edita el fichero META-INF /MANIFEST.MF de tu fichero org.eclipse.jdt.launching JAR  y remueve todo lo que empieza por la entrada "NAME:". Asegúrate que dejas dos  (2)  saltos de lineas al final del fichero.
  8. Reinicia el eclipse. [Opcional] Usa el comando eclipse -clean para que limpie el workspace.



viernes, 10 de octubre de 2014

Ejemplo: productor y consumidor de mensajes con ActiveMQ


Vamos a ver un ejemplo de un escenario donde podría ser interesante el uso de ActiveMQ.

Supongamos que tenemos una aplicación (o varias) con un elevado número de usuarios. En dicha aplicación queremos poder "trazar" la actividad del usuario, o lo que es lo mismo, queremos saber cómo interactúa el usuario con la aplicación para que, posteriormente, el departamento de negocio pueda explotar esa información.

Como hemos dicho, la aplicación tiene un elevado número de usuarios por lo que se decide que el responsable de procesar y almacenar la información de la actividad de los usuarios sea otra aplicación. De esta forma liberamos a la aplicación principal de carga de trabajo.

Para implementar esta solución haremos uso de ActiveMQ. Cada vez que la aplicación principal detecte una acción de un usuario (ej: cuando el usuario vaya a "Opciones de configuración") enviará un mensaje a nuestro intermediario de mensajes con la información de dicha acción.

Estos mensajes quedarán almacenados en nuestro broker de mensajería a la espera de que la aplicación que procesa los datos los consuma para su posterior tratamiento. Si NO se necesitase un tratamiento instantáneo de la información, podría ser un proceso nocturno quien se encargase de esto (se presupone que la cantidad de mensajes generados es muy elevada).

Dicho esto, vamos a ver cómo creamos un productor y un consumidor de mensajes.

Productor de mensajes


En el código que viene a continuación podemos ver cómo un emisor de mensajes envía 20 mensajes a nuestro intermediario con la información de las acciones que realizan los usuarios.

Para este ejemplo es necesaria la librería activemq-all-X.X.X.jar. Viene incluida en la distribución de Apache ActiveMQ.

import org.apache.activemq.ActiveMQConnection;
import org.apache.activemq.ActiveMQConnectionFactory;
 
import javax.jms.*;
import java.util.Random;
 
public class MessageSender {
 
    public enum UserAction {
 
        CONFIGURACION("IR A OPCIONES DE CONFIGURACION"),
        PORTADA("VER PORTADA"),
        LOGIN("ACCEDER A LA APLICACION"),
        SUGERENCIA("ENVIAR SUGERENCIA");
 
        private final String userAction;
 
        private UserAction(String userAction) {
            this.userAction = userAction;
        }
 
        public String getActionAsString() {
            return this.userAction;
        }
    }
 
    private static final Random RANDOM = new Random(System.currentTimeMillis());
 
    private static final String URL = "tcp://localhost:61616";
 
    private static final String USER = ActiveMQConnection.DEFAULT_USER;
 
    private static final String PASSWORD = ActiveMQConnection.DEFAULT_PASSWORD;
 
    private static final String DESTINATION_QUEUE = "APLICATION1.QUEUE";
 
    private static final boolean TRANSACTED_SESSION = true;
     
    private static final int MESSAGES_TO_SEND = 20;
 
    public void sendMessages() throws JMSException {
 
        final ActiveMQConnectionFactory connectionFactory = new ActiveMQConnectionFactory(USER, PASSWORD, URL);
        Connection connection = connectionFactory.createConnection();
        connection.start();
 
        final Session session = connection.createSession(TRANSACTED_SESSION, Session.AUTO_ACKNOWLEDGE);
        final Destination destination = session.createQueue(DESTINATION_QUEUE);
 
        final MessageProducer producer = session.createProducer(destination);
        producer.setDeliveryMode(DeliveryMode.PERSISTENT);
 
        sendMessages(session, producer);
        session.commit();
 
        session.close();
        connection.close();
 
        System.out.println("Mensajes enviados correctamente");
    }
 
    private void sendMessages(Session session, MessageProducer producer) throws JMSException {
        final MessageSender messageSender = new MessageSender();
        for (int i = 1; i <= MESSAGES_TO_SEND; i++) {
            final UserAction userActionToSend = getRandomUserAction();
            messageSender.sendMessage(userActionToSend.getActionAsString(), session, producer);
        }
    }
 
    private void sendMessage(String message, Session session, MessageProducer producer) throws JMSException {
        final TextMessage textMessage = session.createTextMessage(message);
        producer.send(textMessage);
    }
 
    private static UserAction getRandomUserAction() {
        final int userActionNumber = (int) (RANDOM.nextFloat() * UserAction.values().length);
        return UserAction.values()[userActionNumber];
    }
 
    public static void main(String[] args) throws JMSException {
        final MessageSender messageSender = new MessageSender();
        messageSender.sendMessages();
    }
 
}


Si nos fijamos en el código observamos que lo que se está haciendo es enviar un número de mensajes con acciones del usuario al azar. No es exactamente lo que hemos descrito en el punto anterior pero creo que así se entiende mejor.

Con ActiveMQ arrancado lanzamos el ejemplo (método main) y vemos en la consola de administración cómo la cola de mensajes destino (APLICATION1.QUEUE) guarda la información de los mensajes que le acabamos de enviar.


Si además tenemos configurado que los mensajes se almacenen en una base de datos relacional (en nuestro caso MySQL) podemos ver cómo en la tabla "activemq_msgs" tenemos guardados nuestros mensajes.



En caso de que tuviésemos varias colas de mensajes (imaginemos varios productores donde cada uno envía mensajes a una cola), podemos ver la cantidad de mensajes de un vistazo con la consola de administración



consumidor de mensajes.


Nuestro consumidor procesará los todos mensajes que haya en la cola "a demanda" (cuando se ejecute). Si quisiésemos que procesase cada mensaje cuando llega a la cola (no es nuestro caso) deberíamos implementar la interface javax.jms.MessageListener y lanzar nuestro proceso como un hilo que se queda en espera (Thread).

import org.apache.activemq.ActiveMQConnection;
import org.apache.activemq.ActiveMQConnectionFactory;
 
import javax.jms.*;
import java.util.HashMap;
import java.util.Map;
 
public class UserActionConsumer {
 
    private static final String URL = "tcp://localhost:61616";
 
    private static final String USER = ActiveMQConnection.DEFAULT_USER;
 
    private static final String PASSWORD = ActiveMQConnection.DEFAULT_PASSWORD;
 
    private static final String DESTINATION_QUEUE = "APLICATION1.QUEUE";
 
    private static final boolean TRANSACTED_SESSION = false;
 
    private static final int TIMEOUT = 1000;
 
    private final Map consumedMessageTypes;
 
    private int totalConsumedMessages = 0;
 
    public UserActionConsumer() {
        this.consumedMessageTypes = new HashMap();
    }
 
    public void processMessages() throws JMSException {
 
        final ActiveMQConnectionFactory connectionFactory = new ActiveMQConnectionFactory(USER, PASSWORD, URL);
        final Connection connection = connectionFactory.createConnection();
 
        connection.start();
 
        final Session session = connection.createSession(TRANSACTED_SESSION, Session.AUTO_ACKNOWLEDGE);
        final Destination destination = session.createQueue(DESTINATION_QUEUE);
        final MessageConsumer consumer = session.createConsumer(destination);
 
        processAllMessagesInQueue(consumer);
 
        consumer.close();
        session.close();
        connection.close();
 
        showProcessedResults();
    }
 
    private void processAllMessagesInQueue(MessageConsumer consumer) throws JMSException {
        Message message;
        while ((message = consumer.receive(TIMEOUT)) != null) {
            proccessMessage(message);
        }
    }
 
    private void proccessMessage(Message message) throws JMSException {
        if (message instanceof TextMessage) {
            final TextMessage textMessage = (TextMessage) message;
            final String text = textMessage.getText();
            incrementMessageType(text);
            totalConsumedMessages++;
        }
    }
 
    private void incrementMessageType(String message) {
        if (consumedMessageTypes.get(message) == null) {
            consumedMessageTypes.put(message, 1);
        } else {
            final int numberOfTypeMessages = consumedMessageTypes.get(message);
            consumedMessageTypes.put(message, numberOfTypeMessages + 1);
        }
    }
 
    private void showProcessedResults() {
        System.out.println("Procesados un total de " + totalConsumedMessages + " mensajes");
        for (String messageType : consumedMessageTypes.keySet()) {
            final int numberOfTypeMessages = consumedMessageTypes.get(messageType);
            System.out.println("Tipo " + messageType + " Procesados " + numberOfTypeMessages + " (" +
                    (numberOfTypeMessages * 100 / totalConsumedMessages) + "%)");
        }
    }
 
    public static void main(String[] args) throws JMSException {
        final UserActionConsumer userActionConsumer = new UserActionConsumer();
        userActionConsumer.processMessages();
    }
}


Como vemos, lo que hace nuestro consumidor es procesar los mensajes de la cola y mostrar el número de acciones de usuario de cada tipo. Con ActiveMQ arrancado lanzamos el ejemplo y el resultado es el siguiente.



Si consultásemos la consola de administración o la base de datos, veríamos que todos los mensajes de la cola han desaparecido puesto que ya han sido consumidos.

jueves, 9 de octubre de 2014

ActiveMQ para intercambio de mensajes

Apache ActiveMQ


Apache ActiveMQ es un componente MOM (Message Oriented Middleware), es decir, un intermediario (broker) de mensajes que usan dos o más sistemas o aplicaciones para intercambiar mensajes. Ofrece "Características empresariales" tales como clustering, múltiples almacenes para mensajes, así como la capacidad de emplear cualquier administrador de base de datos como proveedor de persistencia JMS, aparte de VM, caché y persistencia de jornales.


En este artículo veremos las características de ActiveMQ, un intermediario de mensajes entre diferentes aplicaciones o sistemas, se describen algunos de los escenarios donde puede ser interesante su uso. Claro está, veremos cómo se instala, cómo se configura y un ejemplo de funcionamiento.

Características principales


  • Es Código Open Source. 
  • Actúa como mediador de mensajes entre aplicaciones emisoras y receptoras.
  • Proporciona comunicación asíncrona entre aplicaciones.
  • Pese a ser una implementación de la especificación JMS (Java Message Service), proporciona una gran cantidad de APIs para diferentes lenguajes como PHP, C/C++, .Net, Ruby, etc.
  • Soporta diferentes protocolos de conexión como HTTP, TCP, SSL, etc.
  • Tiene una GUI de administración.

Instalación


La instalación de Apache ActiveMQ es sencilla.Primero debemos descargar el software de: http://activemq.apache.org/download.html.  Una vez descargado el fichero, debemos seguir los siguientes pasos:
  1. Descomprimir la distribución descargada en el directorio deseado. 
    • Para entornos Unix: tar zxvf apache-activemq-X.X.X-bin.tar.gz
    • Comprobar que el script de arranque de la aplicación tiene permisos de ejecución. Entramos en el directorio bin  que se encuentra dentro de la carpeta de instalación, y asignamos al script "activemq" permisos de ejecución. chmod 755 activemq
  2. Arrancamos Apache ActiveMQ de la siguiente forma: directorio_instalacion_activemq]/bin/activemq start 
    • También podemos "parar" la aplicación, "reiniciarla" o comprobar su "estado" con: stop, restart o status.
  3. Para comprobar que nuestro intermediario de mensajes ha arrancado correctamente: netstat -an|grep 61616, donde 61616 es el puerto por defecto.
También podemos acceder a la consola de administración en http://localhost:8161/admin/

Para que puedas acceder:

  • Usuario: admin
  • Password: admin

Configuración


La configuración del ActiveMQ se encuentra en un fichero activemq.xml localizado en el directorio [directorio_instalacion_activemq]/conf/. No obstante, se puede cambiar el fichero de configuración con el que arrancar ActiveMQ de la siguiente forma:

[directorio_instalacion_activemq]/bin/activemq start xbean:[nombre_del_fichero_configuracion].xml

A continuación destacamos cada una de las propiedades principales:

Transport Connector

Define la conexión con el "broker" de mensajería. Se configura en el tag transportConnectors (dentro
del tag broker) de activemq.xml de la siguiente forma:

    ...
    
        
    
    ...



Se pueden definir varios tipos de conexiones dependiendo del protocolo de transporte (ver lista completa en http://activemq.apache.org/configuring-transports.html).

A continuación se muestran dos ejemplos por VM y TCP:


  • VM Transport permite la conexión con un cliente Java que corra bajo la misma JVM. Se define de la siguiente forma: vm://nombre_del_broker?transportOptions, donde:
    • nombre_del_broker: es el atributo brokerName del tag broker del activemq.xml
    • transportOptions: distintas opciones de la comunicación. Se puede ver la lista de opciones en http://activemq.apache.org/vm-transport-reference.html


    ...
    
        
    
    ...



  • TCP Transport permite la conexión entre el cliente y el gestor de mensajería mediante protocolo TCP. Se define de la siguiente forma: tcp://nombre_o_ip_de_la_maquina:puerto?options, donde:
    • nombre_o_ip_de_la_maquina: máquina o IP donde reside ActiveMQ
    • puerto: puerto de la máquina donde escucha ActiveMQ (por defecto suele ser el 61616)
    • options: opciones de la conexión. Se puede ver la lista entera de opciones en http://activemq.apache.org/tcp-transport-reference.html

    ...
    
        
    
    ...



http://www.adictosaltrabajo.com/tutoriales/tutoriales.php?pagina=ActiveMQ


Persistencia de mensajes

Define la manera de persistir los mensajes en caso de que sea necesario (ver especificación JMS). En este artículo hablaremos de dos tipos: con KahaDB y con JDBC.

Persistencia con KahaDB:
KahaDB es un sistema de almacenamiento propio de ActiveMQ diseñado específicamente para las necesidades de un intermediario de mensajes. Proporciona un rendimiento muy alto. Más que cualquier base de datos relacional. Es un sistema de almacenamiento en ficheros combinado con una caché en memoria.

A continuación un ejemplo de configuración de broker con persistencia en KahaDB, donde:

  • directory: directorio donde se almacenará la información.
  • maxDataFileLength: máximo número de bytes que tendrán los ficheros que compondrán KahaDB.



    ...
    
        
    
    ...




Persistencia con JDBC:

ActiveMQ tiene soporte para poder almacenar mensajes en la mayoría de bases de datos.



    ...
    
        
    
    ...

 


    
    
    
    
    



Importante: es necesario añadir el driver JDBC de conexión de cualquier base de datos al classpath de ActiveMQ, para ello basta con copiarlo en el directorio [directorio_instalacion_activemq]/lib/

Más información sobre persistencia de mensajes en http://activemq.apache.org/persistence.html.

Control de flujo


Existe un problema muy típico en ActiveMQ cuando se usan mensajes no persistentes (almacenados en memoria) y es que el buffer de almacenamiento termine con toda la RAM. Para solucionar esto existe un sistema de control de flujo, mediante el cual, es posible limitar el número de mensajes en memoria de uno o varios productores de mensajes no persistentes.

A continuación un ejemplo de configuración:


    ...
    
        
            
        
    
    ...



El valor del atributo queue igual a >, significa que este control de flujo se aplicará a cualquier cola de mensajes. Podríamos aplicar distintas políticas de control de flujo según el nombre de la cola. Ejemplo:

  • queue="TEST.FOO" : para todos los mensajes de la cola TEST.FOO
  • queue="TEST.>" : para todos los mensajes de las colas que comiencen por TEST.

Más info sobre control de flujo en http://activemq.apache.org/producer-flow-control.html

Uso del sistema



Es posible realizar una configuración más genérica de determinadas partes del sistema como puede ser el uso de memoria o el límite de almacenamiento físico o temporal.

Aquí vemos ejemplo:

....

    ...
    
        
            
                
            
            
                
            
            
                
            
        
    
    ...



Nótese que el límite de almacenamiento no influye en bases de datos externas aunque sí en KahaDB.


Ejemplo: productor y consumidor de mensajes.

En el siguiente artículo encontrarán un ejemplo para ActiveMQ

miércoles, 8 de octubre de 2014

Uso de Jax-WS Handlers para leer encabezados (headers) en los Servicios Web

La semana pasada un compañero de trabajo me comento que no encontraba como leer un encabezado de un mensaje soap mediante el uso de web-services. He decidido compartir esta información para que sea más accesible de encontrar en la web. La respuesta es fácil... usa handlers.

Jax-WS Handlers

El framework JAX-WS (el último API de Java usado para la creación de servicios web basados en SOAP: para publicar y consumir servicios Web) también proporciona un framework Handlers.

Los Handlers (controladores) proporcionan un medio para inspeccionar y manipular los mensajes SOAP entrantes o salientes (tanto en el cliente como en el servidor). Ellos actúan como poderosos interceptores de mensajes que pueden realizar una variedad de funciones tales como la transformación de mensajes, filtrado de contenidos, seguimiento (tracking), etc. De hecho, los handlers se utilizan a menudo en entornos de ejecución para implementar las especificaciones de SOAP y servicios web tales como WS-Security, WS-ReliableMessaging, etc.

Los JAX-WS Handlers son similares a los interceptores EJB o filtros de servlets. Tanto los Handlers, como los interceptores y los filtros, recomiendan a los desarrolladores a seguir la cadena del patrón de responsabilidad.

Tipos de JAX-WS Handlers

JAX-WS ofrece dos tipos de handlers (con dos interfaces): LogicalHandler y SOAPHandler.

  • LogicalHandlers son el protocolo de mensajes neutral. 
  • LogicalHandlers sólo tienen acceso a la carga útil del mensaje de un mensaje. 
  • SOAPHandlers también se conocen como controladores de mensajes o de protocolo. 
  • SOAPHandlers tienen acceso a todo el mensaje SOAP. 
nos enfocaremos en los SoapHandlers.

SOAPHandlers 

La interfaz SOAPHandler requiere que la clase del Handler implemente cuatro métodos:
handleMessage, handleFault, close y getHeaders. 

  • El handleMessage suele ser el método de mayor interés en un handler. El método handleMessage es invocado para el procesamiento normal por el framework como lo es el envío o recepción del mensaje (entrante y saliente). 
  • El método handleFault es invocado por el framework cuando se produce un error de SOAP durante el procesamiento de mensajes. 
  • El método close es invocado por el framework justo antes del envío del mensaje. El método de close permite cualquier limpieza o liberación de recursos al final del procesamiento del handler.

A continuación se muestra un ejemplo de un SOAPHandler (menos el método getHeaders que se explicará a continuación) que se encarga de contar el número de elementos en el encabezado (header) y el cuerpo (body) de un mensaje SOAP. 

//required imports here

public class HeaderHandler implements SOAPHandler {

    @Override 
    public void close(MessageContext context) { 
    }

    @Override 
    public boolean handleFault(SOAPMessageContext context) { 
        return false; 
    }

    @Override 
    public boolean handleMessage(SOAPMessageContext messagecontext) { 
        Boolean outbound = (Boolean) messagecontext 
                .get(MessageContext.MESSAGE_OUTBOUND_PROPERTY); 
        if (outbound) { 
            System.out.println("SOAP message departing…"); 
        } else { 
            System.out.println("SOAP message incoming…"); 
        } 
        try { 
            SOAPMessage message = messagecontext.getMessage(); 
            SOAPHeader header = message.getSOAPHeader(); 
            if (header != null) { 
                Iterator i = header.getChildElements(); 
                System.out.println("Number of header elements:  " 
                        + countElements(i)); 
            } 
            SOAPBody body = message.getSOAPBody(); 
            if (body != null) { 
                Iterator i = body.getChildElements(); 
                System.out.println("Number of body elements:  " 
                        + countElements(i)); 
            } 
        } catch (Exception e) { 
            System.out.println(e); 
            e.printStackTrace(); 
        } 
        return true; 
    }

    private int countElements(Iterator i) { 
        int count = 0; 
        while (i.hasNext()) { 
            count++; 
            i.next(); 
        } 
        return count; 
    }
}

El último método, getHeaders, es justo el punto de interés de esta entrada del blog. El método getHeaders recupera los bloques de la cabecera que pueden ser procesados por el handler. No toma ningún parámetro y devuelve un conjunto de nombres completos de encabezado.

El método GetHeaders()

El método getHeaders() obtiene el encabezado soap  (header:soap) así como el tiempo de ejecución del servicio de hosting (alojamiento), de los cuales el handler es el encargado de procesar. Devuelve los QNames del elemento exterior de cada encabezado SOAP que el handler entiende. 

MustUnderstand Not Understood! 


Si has trabajado con los mensajes SOAP, seguramente te habrás dado cuenta que los elementos de header SOAP pueden venir con un atributo global SOAP llamado: mustUnderstand. Los valores válidos para mustUnderstand son true | false (SOAP 1.2) ó 1 | 0 (SOAP 1.1). Este atributo es utilizado para indicar si se requiere o no el receptor o intermediario de servicios web  para entender el elemento de la cabecera antes de procesar el mensaje. 

El SOAPHandler puede servir como un "intermediario" que procesa el encabezado SOAP antes de que el servicio real se encargue de procesar el resto (Body) del mensaje. 

Por ejemplo, a continuación un ejemplo de mensaje SOAP que contiene falsas credenciales de seguridad para ser usado por el lado del servidor para autenticar/autorizar alguna invocación del servicio. Observa donde esta el atributo mustUnderstand entre nombre de usuario (usernameHeader) y contraseña (passwordHeader) de los elementos que tiene la cabecera? 

 
    
      Jim 
      supersecret 
    
    
       
         4 
       
    


si algo no procesa los elementos de la cabecera: nombre de usuario y contraseña, este mensaje podría retornar una falla al cliente. Por ejemplo, supongamos que el servicio no maneja los elementos de la cabecera y el metodo getHeaders del SOAPHandler se codifica como se muestra a continuación.


@Override 
    public Set getHeaders() { 
        return null; 
    }


Dado que nada maneja el usuario y contraseña de la cabecera, el mensaje SOAP resultante dirigido al cliente incluiría un código de fallo MustUnderstand como se muestra aquí

 
    
       
         soap:MustUnderstand 
         MustUnderstand headers: [{urn:com.intertech.secty}password, {urn:com.intertech.secty}username] are not understood. 
       
    


Usando getHeaders() para entender el MustUnderstand


Sin embargo, el método getHeaders () puede ser codificado para indicar al entorno de ejecución que el handler de SOAP se va a encargar de los elementos de la cabecera mustUnderstand devolviendo un conjunto de objetos QName (nombre completo) que coinciden con los elementos de la cabecera mustUnderstand. A continuación, un ejemplo con el nuevo método getHeaders () que maneja el usuario y contraseña de las cabeceras.

@Override 
public Set getHeaders() { 
    System.out.println("Inside SOAP handler of get Headers"); 
    QName securityUsernameHeader = new QName("urn:com.intertech.secty", 
            "username"); 
    QName securityPasswordHeader = new QName("urn:com.intertech.secty", 
            "password"); 
    HashSet headers = new HashSet(); 
    headers.add(securityUsernameHeader); 
    headers.add(securityPasswordHeader); 
    System.out.println("got Headers:  " + headers); 
    return headers; 
}

Ahora, si el mismo elemento SOAP con los elementos de la cabecera: nombre de usuario y contraseña se envía a un servicio, mediante el HeaderHandler del ejemplo, no se genera un fallo. Se supone por el tiempo de ejecución que los elementos de la cabecera fueron consumidos por el handler. Por supuesto, en un mundo real para el SOAP handler, en el método handleMessage () deberías agregar algún código para manejar efectivamente estos encabezados.

Espero que esta información pueda serles de gran utilidad.


jueves, 2 de octubre de 2014

Rest Api - Conceptos

¿Qué es REST?


REST (REpresentational State Transfer) es un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP.

REST nos permite crear servicios y aplicaciones que pueden ser usadas por cualquier dispositivo o cliente que entienda HTTP, siendo más simple y convencional que otras alternativas que se han usado en los últimos años (SOAP, XML-RPC, etc)

Existen tres niveles de calidad a la hora de aplicar REST en el desarrollo de una aplicación web y, concretamente en una API. Estos niveles son:

  • Uso correcto de URIs
  • Uso correcto de HTTP.
  • Implementar Hypermedia.

Además de estas tres reglas, nunca se debe guardar el estado en el servidor, toda la información que se requiere para mostrar la información que se solicita debe estar en la consulta por parte del cliente. Al no guardar el estado, REST puede escalar mejor sin tener que preocuparnos por temas como el almacenamiento de variables de sesión e incluso, podemos jugar con distintas tecnologías para servir determinadas partes o recursos de una misma API.

Nivel 1: Uso correcto de URIs


Cuando desarrollamos una aplicación web, las URLs nos permiten acceder a cada uno de los recursos: páginas, información de una sección, a las imagenes, ficheros o documentos del sitio web. El recurso por lo tanto es la información a la que queremos acceder (consultar, modificar, borrar) independientemente de su formato.

Las URL (Uniform Resource Locator) son un tipo de URI (Uniform Resource Identifier) que además de permitir identificar de forma única el recurso, nos permite localizarlo para poder acceder a él o compartir su ubicación.

Una URL se estructura de la siguiente forma:

{protocolo}://{dominio o hostname}[:puerto (opcional)]/{ruta del recurso}?{consulta de filtrado}

Por ejemplo, http://innovaskynet.blogspot.com/2013/conceptos-sobre-apis-rest/, sería la URL para visualizar este artículo.

Existen varias reglas básicas para ponerle nombre a la URI de un recurso:
  • Los nombres de URI no deben implicar una acción, por lo tanto debe evitarse usar verbos en ellos.
  • Deben ser únicas, no debemos tener más de una URI para identificar un mismo recurso.
  • Deben ser independiente de formato.
  • Deben mantener una jerarquía lógica.
  • Los filtrados de información de un recurso no se hacen en la URI.
  • Las URIs no deben implicar acciones y deben ser únicas

Por ejemplo, la URI /facturas/234/editar sería incorrecta ya que tenemos el verbo editar en la misma.

Para el recurso factura con el identificador 234, la siguiente URI sería la correcta, independientemente de que vayamos a editarla, borrarla, consultarla o leer sólo uno de de sus conceptos: /facturas/234

Las URIs deben ser independientes de formato


Por ejemplo, la URI /facturas/234.pdf no sería una URI correcta, ya que estamos indicando la extensión pdf en la misma.

Para el recurso factura con el identificador 234, la siguiente URI sería la correcta, independientemente de que vayamos a consultarla en formato pdf, epub, txt, xml o json: /facturas/234

Las URIs deben mantener una jerarquía lógica


Por ejemplo, la URI /facturas/234/cliente/007 no sería una URI correcta, ya que no sigue una jerarquía lógica.

Para el recurso factura con el identificador 234 del cliente 007, la siguiente URI sería la correcta: /clientes/007/facturas/234

Filtrados y otras operaciones.


Para filtrar, ordenar, paginar o buscar información en un recurso, debemos hacer una consulta sobre la URI, utilizando parámetros HTTP en lugar de incluirlos en la misma.

Por ejemplo, la URI /facturas/orden/desc/fecha-desde/2007/pagina/2 sería incorrecta ya que el recurso de listado de facturas sería el mismo pero utilizaríamos una URI distinta para filtrarlo, ordenarlo o paginarlo.

La URI correcta en este caso sería: /facturas?fecha-desde=2007&orden=DESC&pagina=2


Nivel 2: HTTP


Conocer bien HTTP no es opcional para un desarrollador web al que le importe su trabajo. Aunque el RFC es sencillo de leer, si estás interesado en aprender bien las bases de este protocolo es muy recomendable la guía de O’Reilly sobre el mismo.

Para desarrollar APIs REST los aspectos claves que hay que dominar y tener claros son:
  • Métodos HTTP
  • Códigos de estado
  • Aceptación de tipos de contenido

Métodos

Como hemos visto en el anterior nivel, a la hora de crear URIs no debemos poner verbos que impliquen acción, aunque queramos manipular el recurso.

Para manipular los recursos, HTTP nos dota de los siguientes métodos con los cuales debemos operar:

  • GET: Para consultar y leer recursos
  • POST: Para crear recursos
  • PUT: Para editar recursos
  • DELETE: Para eliminar recursos.
  • PATCH: Para editar partes concretas de un recurso.

Por ejemplo para un recurso de facturas:

GET /facturas Nos permite acceder al listado de facturas

POST /facturas Nos permite crear una factura nueva

GET /facturas/123 Nos permite acceder al detalle de una factura

PUT /facturas/123 Nos permite editar la factura, sustituyendo la totalidad de la información anterior por la nueva.

DELETE /facturas/123 Nos permite eliminar la factura

PATCH /facturas/123 Nos permite modificar cierta información de la factura, como el número o la fecha de la misma.


Quizá debido al desconocimiento o el soporte de ciertos navegadores, los desarrolladores web han usado, durante los últimos años, únicamente los métodos GET Y POST para realizar todas estas acciones. Si trabajamos con REST, esto sería un error de base y puede darnos problemas incluso a la hora de nombrar nuestros recursos, obligándonos a poner verbos en las URLs.

Códigos de estado


Uno de los errores más frecuentes a la hora de construir una API suele ser el reinventar la rueda creando nuestras propias herramientas en lugar de utilizar las que ya han sido creadas, pensadas y testadas. La rueda más reinventada en el desarrollo de APIs son los códigos de error y códigos de estado.

Cuando realizamos una operación, es vitar saber si dicha operación se ha realizado con éxito o en caso contrario, por qué ha fallado.

Un error común sería por ejemplo:

Petición
========
PUT /facturas/123

Respuesta
=========
Status Code 200
Content:
{
  success: false,
  code:    734,
  error:   "datos insuficientes"
}

En este ejemplo se devuelve un código de estado 200, que significa que la petición se ha realizado correctamente, sin embargo, estamos devolviendo en el cuerpo de la respuesta un error y no el recurso solicitado en la URL.


Este es un error común que tiene varios inconvenientes:

  • No es REST ni es estándar.
  • El cliente que acceda a este API debe conocer el funcionamiento especial y cómo tratar los errores de la misma, por lo que requiere un esfuerzo adicional importante para trabajar con nosotros.
  • Tenemos que preocuparnos por mantener nuestros propios códigos o mensajes de error, con todo lo que eso supone.
HTTP tiene un abanico muy amplio que cubre todas las posibles indicaciones que vamos a tener que añadir en nuestras respuestas cuando las operaciones han ido bien o mal.

Es imperativo conocerlos y saber cuándo utilizarlos, independientemente de que desarrolles siguiendo REST.

El siguiente ejemplo sería correcto de la siguiente forma:

Petición
========
PUT /facturas/123

Respuesta
=========
Status Code 400
Content:
{
  message: "se debe especificar un id de cliente para la factura"
}

Tipos y formatos de contenido


Cuando hablamos sobre URLs, vimos también que no era correcto indicar el tipo de formato de un recurso al cual queremos acceder o manipular.

HTTP nos permite especificar en qué formato queremos recibir el recurso, pudiendo indicar varios en orden de preferencia, para ello utilizamos el header Accept.

Nuestra API devolverá el recurso en el primer formato disponible y, de no poder mostrar el recurso en ninguno de los formatos indicados por el cliente mediante el header Accept, devolverá el código de estado HTTP 406.

En la respuesta, se devolverá el header Content-Type, para que el cliente sepa qué formato se devuelve, por ejemplo:

Petición
========
GET /facturas/123
Accept: application/epub+zip , application/pdf, application/json

Respuesta
=========
Status Code 200
Content-Type: application/pdf


En este caso, el cliente solicita la factura en epub comprimido con ZIP y de no tenerlo, en pdf o json por orden de preferencia. El servidor le devuelve finalmente la factura en pdf.

Nivel 3: Hypermedia.


El concepto y la finalidad de Hypermedia es conectar mediante vínculos las aplicaciones clientes con las APIs, permitiendo a dichos clientes despreocuparse por conocer de antemano del cómo acceder a los recursos.

Con Hypermedia básicamente añadimos información extra al recurso sobre su conexión a otros recursos relacionados con él.

Aquí tenemos un ejemplo:

 666
 Procesado
 
   

http://example.com/api/pedido/666/factura

   
 


En este ejemplo vemos cómo indicar en un xml que representa un pedido, el enlace al recurso de la factura relacionada con el mismo.

Sin embargo, necesitamos que el cliente que accede a nuestra API entienda que esa información no es propia del recurso, sino que es información añadida que puede utilizar para enlazar el pedido con la factura.

Para ello conseguir esto, debemos utilizar las cabeceras Accept y Content-Type, para que tanto el cliente como la API, sepan que están hablando hypermedia.

Por ejemplo:

Petición
========
GET /pedido/666
Accept: application/nuestra_api+xml, text/xml

Respuesta
=========
Status Code: 200
Content-Type: application/nuestra_api+xml
Content:


 666
 Procesado
 
   
http://example.com/api/pedido/666/factura
 


Como vemos, el cliente solicita el formato application/nuestra_api+xml de forma preferente al formato text/xml. De esta forma, le indica al servicio web, que entiende su formato hypermedia y puede aprovecharlo.

El servicio web por lo tanto, como implementa hypermedia, le devuelve la información de recurso y la información de hypermedia que puede utilizar el cliente.

Hypermedia es útil, por ejemplo, para que el cliente no tenga que conocer las URLs de los recursos, evitando de esta forma tener que hacer mantenimientos en cada uno de los mismos si en un futuro dichas URLs cambian (cosa que no debería pasar). También es útil para automatizar procesos entre APIs sin que haya interacción humana.

Conclusión

Los principios básicos para construir APIs REST se basan en conocer sobre todo HTTP, algo que no es opcional para un desarrollador web.