Acceso a Servicios Web SOAP en Android (2/2)

En el artículo anterior del curso vimos cómo construir un servicio web SOAP haciendo uso de ASP.NET y una base de datos externa SQL Server. En este segundo artículo veremos cómo podemos acceder a este servicio web desde una aplicación Android y probaremos todo el sistema en local para verificar su correcto funcionamiento.

En primer lugar hay que empezar diciendo que Android no incluye “de serie” ningún tipo de soporte para el acceso a servicios web de tipo SOAP. Es por esto por lo que vamos a utilizar una librería externa para hacernos más fácil esta tarea. Entre la oferta actual, la opción más popular y más utilizada es la librería ksoap2-android. Esta librería es un fork, especialmente adaptado para Android, de la antigua librería kSOAP2. Este framework nos permitirá de forma relativamente fácil y cómoda utilizar servicios web que utilicen el estándar SOAP. La última versión de esta librería en el momento de escribir este artículo es la 2.6.0, que puede descargarse desde este enlace.

Agregar esta librería a nuestro proyecto Android es muy sencillo. Una vez tenemos creado el proyecto en Android, accederemos al menú “Project / Properties” y en la ventana de propiedades accederemos a la sección “Java Build Path“. En esta sección accederemos a la solapa “Libraries” y pulsaremos el botón “Add External JARs…“. Aquí seleccionamos el fichero jar de la librería ksoap2-android (en este caso “ksoap2-android-assembly-2.6.0-jar-with-dependencies.jar”) y listo, ya tenemos nuestro proyecto preparado para hacer uso de la funcionalidad aportada por la librería.

Como aplicación de ejemplo, vamos a crear una aplicación sencilla que permita añadir un nuevo usuario a la base de datos. Para ello añadiremos a la vista principal dos cuadros de texto para introducir el nombre y teléfono del nuevo cliente (en mi caso se llamarán txtNombre y txtTelefono respectivamente) y un botón (en mi caso btnEnviar) que realice la llamada al método NuevoCliente del servicio web pasándole como parámetros los datos introducidos en los cuadros de texto anteriores.

No voy a mostrar todo el código necesario para crear esta vista y obtener las referencias a cada control porque no tiene ninguna particularidad sobre lo ya visto en multitud de ocasiones en artículos anteriores del curso (en cualquier caso al final del artículo podéis descargar todo el código fuente para su consulta). Lo que nos interesa en este caso es la implementación del evento onClick del botón btnEnviar, que será el encargado de comunicarse con el servicio web y procesar el resultado.

Lo primero que vamos a hacer en este evento es definir, por comodidad, cuatro constantes que nos servirán en varias ocasiones durante el código:

• NAMESPACE. Espacio de nombres utilizado en nuestro servicio web.
• URL. Dirección URL para realizar la conexión con el servicio web.
• METHOD_NAME. Nombre del método web concreto que vamos a ejecutar.
• SOAP_ACTION. Equivalente al anterior, pero en la notación definida por SOAP.

Aunque los valores se podrían más o menos intuir, para conocer exactamente los valores que debemos asignar a estas constantes vamos a ejecutar una vez más el proyecto de Visual Studio que construimos en el artículo anterior y vamos a acceder a la página de prueba del método NuevoCliente. Veremos algo parecido a lo siguiente:

En la imagen anterior se muestran resaltados en rojo los valores de las cuatro constantes a definir, que en nuestro caso concreto quedarían de la siguiente forma:

String NAMESPACE = "http://sgoliver.net/";
String URL="http://10.0.2.2:1473/ServicioClientes.asmx";
String METHOD_NAME = "NuevoClienteSimple";
String SOAP_ACTION = "http://sgoliver.net/NuevoClienteSimple";

Como podéis comprobar, y esto es algo importante, en la URL he sustituido el nombre de máquina localhost por su dirección IP equivalente, que en el caso de aplicaciones Android ejecutadas en el emulador se corresponde con la dirección 10.0.2.2, en vez de la clásica 127.0.0.1.

Los siguientes pasos del proceso serán crear la petición SOAP al servicio web, enviarla al servidor y recibir la respuesta. Aunque ya dijimos que todo este proceso sería casi transparente para el programador, por ser ésta la primera vez que hablamos del tema me voy a detener un poco más para intentar que entendamos lo que estamos haciendo y no solo nos limitemos a copiar/pegar trozos de código que no sabemos lo que hacen.

Volvamos a la página de prueba del método web NuevoCliente. Justo debajo de la sección donde se solicitan los parámetros a pasar al método se incluye también un XML de muestra de cómo tendría que ser nuestra petición al servidor si tuviéramos que construirla a mano. Echémosle un vistazo:

Una vez más he marcado varias zonas sobre la imagen, correspondientes a las tres partes principales de una petición de tipo SOAP. Empezando por la “parte interna” del XML, en primer lugar encontramos los datos de la petición en sí (Request) que contiene el nombre del método al que queremos llamar, y los nombres y valores de los parámetros en entrada. Rodeando a esta información se añaden otra serie de etiquetas y datos a modo de contenedor estándar que suele recibir el nombre de Envelope. La información indicada en este contenedor no es específica de nuestra llamada al servicio, pero sí contiene información sobre formatos y esquemas de validación del estándar SOAP. Por último, durante el envío de esta petición SOAP al servidor mediante el protocolo HTTP se añaden determinados encabezados como los que veis en la imagen. Todo esto junto hará que el servidor sea capaz de interpretar correctamente nuestra petición SOAP, se llame al método web correcto, y se devuelva el resultado en un formato similar al anterior que ya veremos más adelante. Aclarada un poco la estructura y funcionamiento general de una petición SOAP veamos lo sencillo que resulta realizarla desde nuestra aplicación Android.

En primer lugar crearemos la petición (request) a nuestro método NuevoCliente. Para ello crearemos un nuevo objeto SoapObject pasándole el namespace y el nombre del método web. A esta petición tendremos que asociar los parámetros de entrada mediante el método addProperty() al que pasaremos los nombres y valores de los parámetros (que en nuestro caso se obtendrán de los cuadros de texto de la vista principal).

SoapObject request = new SoapObject(NAMESPACE, METHOD_NAME);

request.addProperty("nombre", txtNombre.getText().toString());
request.addProperty("telefono", txtTelefono.getText().toString());

El segundo paso será crear el contenedor SOAP (envelope) y asociarle nuestra petición. Para ello crearemos un nuevo objeto SoapSerializationEnvelope indicando la versión de SOAP que vamos a usar (versión 1.1 en nuestro caso, como puede verse en la imagen anterior). Indicaremos además que se trata de un servicio web .NET activando su propiedad dotNet. Por último, asociaremos la petición antes creada a nuestro contenedor llamando al método setOutputSoapObject().

SoapSerializationEnvelope envelope =
	new SoapSerializationEnvelope(SoapEnvelope.VER11);

envelope.dotNet = true;

envelope.setOutputSoapObject(request);

Como tercer paso crearemos el objeto que se encargará de realizar la comunicación HTTP con el servidor, de tipo HttpTransportSE, al que pasaremos la URL de conexión a nuestro servicio web. Por último, completaremos el proceso realizando la llamada al servicio web mediante el método call().

HttpTransportSE transporte = new HttpTransportSE(URL);

try
{
	transporte.call(SOAP_ACTION, envelope);

	//Se procesa el resultado devuelto
	//...
}
catch (Exception e)
{
	txtResultado.setText("Error!");
}

Tras la llamada al servicio ya estamos en disposición de obtener el resultado devuelto por el método web llamado. Esto lo conseguimos mediante el método getResponse(). Dependiendo del tipo de resultado que esperemos recibir deberemos convertir esta respuesta a un tipo u otro. En este caso, como el resultado que esperamos es un valor simple (un número entero) convertiremos la respuesta a un objeto SoapPrimitive, que directamente podremos convertir a una cadena de caracteres llamado a toString(). Más adelante veremos cómo tratar valores de retorno más complejos.

SoapPrimitive resultado_xml =(SoapPrimitive)envelope.getResponse();
String res = resultado_xml.toString();

if(res.equals("1"))
	txtResultado.setText("Insertado OK");

Y listo, con esto ya tenemos preparada la llamada a nuestro servicio web y el tratamiento de la respuesta recibida.

Un detalle más antes de poder probar todo el sistema. Debemos acordarnos de conceder permiso de acceso a internet a nuestra aplicación, añadiendo la linea correspondiente al Android Manifest:

<uses-permission android:name="android.permission.INTERNET"/>

Pues bien, para probar lo que llevamos hasta ahora podemos ejecutar ambos proyectos simultáneamente, en primer lugar el de Visual Studio para iniciar la ejecución del servidor local que alberga nuestro servicio web (hay que dejar abierto el explorador una vez que se abra), y posteriormente el de Eclipse para iniciar nuestra aplicación Android en el Emulador. Una vez están los dos proyectos en ejecución, podemos rellenar los datos de nuestro cliente en la aplicación Android y pulsar el botón “Enviar” para realizar la llamada al servicio web e insertar el cliente en la base de datos (que por supuesto también deberá estar iniciada). Si todo va bien y no se produce ningún error, deberíamos poder consultar la tabla de Clientes a través del SQL Server Management Studio para verificar que el cliente se ha insertado correctamente.

En la imagen vemos cómo hemos insertado un nuevo cliente llamada ‘cliente7′ con número de teléfono ’7777′. Si consultamos ahora nuestra base de datos Sql Server podremos comprobar si el registro efectivamente se ha insertado correctamente.

Con esto, ya sabemos realizar una llamada a un servicio web SOAP que devuelve un valor de retorno sencillo, en este caso un simple número entero. Lo siguiente que vamos a ver será como implementar la llamada a un método del servicio web que nos devuelva un valor algo más complejo. Y esto lo vamos a ver con la llamada al método web ListadoClientes() que recordemos devolvía un array de objetos de tipo Cliente.

En este caso, la llamada al método web se realizará de forma totalmente análoga a la ya comentada. Donde llegarán las diferencias será a la hora de tratar el resultado devuelto por el servicio, comenzando por el resultado del método getResponse() de ksoap. En esta ocasión, dado que el resultado esperado no es ya un valor simple sino un objeto más complejo, convertiremos el resultado de getResponse() al tipo SoapObject, en vez de SoapPrimitive como hicimos anteriormente. Nuestro objetivo será generar un array de objetos Cliente (lo llamaremos listaClientes) a partir del resultado devuelto por la llamada al servicio.

Como sabemos que el resultado devuelto por el servicio es también un array, lo primero que haremos será crear un array local con la misma longitud que el devuelto, lo que conseguiremos mediante el método getPropertyCount(). Tras esto, iteraremos por los distintos elementos del array devuelto mediante el método getProperty(ind), donde ind será el índice de cada ocurrencia. Cada uno de estos elementos será a su vez otro objeto de tipo SoapObject, que representará a un Cliente. Adicionalmente, para cada elemento accederemos a sus propiedades (Id, Nombre, y Telefono) una vez más mediante llamadas a getProperty(), con el índice de cada atributo, que seguirá el mismo orden en que se definieron. Así, getProperty(0) recuperará el Id del cliente, getProperty(1) el nombre, y getProperty(2) el teléfono. De esta forma podremos crear nuestros objetos Cliente locales a partir de estos datos. Al final de cada iteración añadimos el nuevo cliente recuperado a nuestro array. Veamos como quedaría todo esto en el código, donde seguro que se entiende mejor:

SoapObject resSoap =(SoapObject)envelope.getResponse();

Cliente[] listaClientes = new Cliente[resSoap.getPropertyCount()];

for (int i = 0; i < listaClientes.length; i++)
{
       SoapObject ic = (SoapObject)resSoap.getProperty(i);

       Cliente cli = new Cliente();
       cli.id = Integer.parseInt(ic.getProperty(0).toString());
       cli.nombre = ic.getProperty(1).toString();
       cli.telefono = Integer.parseInt(ic.getProperty(2).toString());

       listaClientes[i] = cli;
}

En nuestra aplicación de ejemplo añadimos un nuevo botón y un control tipo lista (lo llamo lstClientes), de forma que al pulsar dicho botón rellenemos la lista con los nombres de todos los clientes recuperados. La forma de rellenar una lista con un array de elementos ya la vimos en los artículos dedicados a los controles de selección, por lo que no nos pararemos a comentarlo. El código sería el siguiente (Nota: sé que todo esto se podría realizar de forma más eficiente sin necesidad de crear distintos arrays para los clientes y para el adaptador de la lista, pero lo dejo así para no complicar el tutorial con temas ya discutidos en otros artículos):

//Rellenamos la lista con los nombres de los clientes
final String[] datos = new String[listaClientes.length];

for(int i=0; i<listaClientes.length; i++)
    datos[i] = listaClientes[i].nombre;

ArrayAdapter<String> adaptador =
    new ArrayAdapter<String>(ServicioWebSoap.this,
        android.R.layout.simple_list_item_1, datos);

lstClientes.setAdapter(adaptador);

Por último, vamos a ver cómo llamar a un método web que recibe como parámetro algún objeto complejo. Para ilustrarlo haremos una llamada al segundo método de inserción de clientes que implementamos en el servicio, NuevoClienteObjeto(). Recordemos que este método recibía como parámetro de entrada un objeto de tipo Cliente.

Para poder hacer esto, lo primero que tendremos que hacer será modificar un poco nuestra clase Cliente, de forma que ksoap sepa cómo serializar nuestros objetos Cliente a la hora de generar las peticiones SOAP correspondientes. Y para esto, lo que haremos será implementar la interfaz KvmSerializable en nuestra clase Cliente. Para ello, además de añadir la cláusula implements correspondiente tendremos que implementar los siguientes métodos:

• getProperty(int indice)
• getPropertyCount()
• getPropertyInfo(int indice, HashTable ht, PropertyInfo info)
• setProperty(int indice, Object valor)

El primero de ellos deberá devolver el valor de cada atributo de la clase a partir de su índice de orden. Así, para el índice 0 se devolverá el valor del atributo Id, para el índice 1 el del atributo Nombre, y para el 2 el atributo Teléfono.

@Override
public Object getProperty(int arg0) {

	switch(arg0)
        {
        case 0:
            return id;
        case 1:
            return nombre;
        case 2:
            return telefono;
        }

	return null;
}

El segundo de los métodos, deberá devolver simplemente el número de atributos de nuestra clase, que en nuestro caso será 3 (Id, Nombre y Telefono):

@Override
public int getPropertyCount() {
	return 3;
}

El objetivo del tercero será informar, según el índice recibido como parámetro, el tipo y nombre del atributo correspondiente. El tipo de cada atributo se devolverá como un valor de la clase PropertyInfo.

@Override
public void getPropertyInfo(int ind, Hashtable ht, PropertyInfo info) {
	switch(ind)
        {
        case 0:
            info.type = PropertyInfo.INTEGER_CLASS;
            info.name = "Id";
            break;
        case 1:
            info.type = PropertyInfo.STRING_CLASS;
            info.name = "Nombre";
            break;
        case 2:
            info.type = PropertyInfo.INTEGER_CLASS;
            info.name = "Telefono";
            break;
        default:break;
        }
}

Por último, el método setProperty() será el encargado de asignar el valor de cada atributo según su índice y el valor recibido como parámetro.

@Override
public void setProperty(int ind, Object val) {
	switch(ind)
        {
        case 0:
            id = Integer.parseInt(val.toString());
            break;
        case 1:
            nombre = val.toString();
            break;
        case 2:
            telefono = Integer.parseInt(val.toString());
            break;
        default:
            break;
        }
}

Mediante estos métodos, aunque de forma transparente para el programados, ksoap será capaz de transformar nuestros objetos Cliente al formato XML correcto de forma que pueda pasarlos como parámetro en las peticiones SOAP a nuestro servicio.

Por su parte, la llamada al servicio también difiere un poco de lo ya comentado a la hora de asociar los parámetros de entrada del método web. En este caso, construiremos en primer lugar el objeto Cliente que queremos insertar en la base de datos a partir de los datos introducidos en la pantalla de nuestra aplicación de ejemplo. Tras esto crearemos un nuevo objeto PropertyInfo, al que asociaremos el nombre, valor y tipo de nuestro cliente mediante sus métodos setName(), setValue() y setClass() respectivamente. Por último, asociaremos este cliente como parámetro de entrada al servicio llamando al metodo addProperty() igual que hemos hecho en las anteriores ocasiones, con la diferencia de que esta vez lo llamaremos pasándole el objeto PropertyInfo que acabamos de crear. Además de esto, tendremos también que llamar finalmente al método addMapping() para asociar de alguna forma nuestro espacio de nombres y nombre de clase “Cliente” con la clase real java. Veamos el código para entenderlo mejor:

Cliente cli = new Cliente();
cli.nombre = txtNombre.getText().toString();
cli.telefono = Integer.parseInt(txtTelefono.getText().toString());

PropertyInfo pi = new PropertyInfo();
pi.setName("cliente");
pi.setValue(cli);
pi.setType(cli.getClass());

request.addProperty(pi);

SoapSerializationEnvelope envelope =
    new SoapSerializationEnvelope(SoapEnvelope.VER11);
envelope.dotNet = true;

envelope.setOutputSoapObject(request);

envelope.addMapping(NAMESPACE, "Cliente", cli.getClass());

Todo esto lo haremos en un nuevo botón añadido a la aplicación de ejemplo (Enviar2), cuyo efecto tendrá que ser idéntico al que ya creamos para la llamada al método web NuevoClienteSimple(), aunque como acabamos de ver su implementación es algo diferente debido a los distintos parámetros de entrada utilizados.

Como imagen final veamos una captura de la pantalla final de nuestra aplicación de ejemplo, donde vemos los tres botones implementados, junto al resultado de la ejecución de cada uno, el mensaje “Insertado OK” de los métodos de inserción, y la lista de clientes recuperada por el método de consulta.

Espero que estos dos últimos artículos sobre servicios web SOAP y Android os sirvan para tener un ejemplo completo, tanto de la parte servidor como de la parte cliente, que os sirva de base para crear nuevos sistemas adaptados a vuestras necesidades. Como siempre, podéis descargar el código fuente completo de este artículo a través de este enlace.