Acessando um Serviço da Web em JAX-WS a partir do Android

Os serviços da Web fornecem serviços específicos para a função e são
especialmente adequados para dispositivos remotos. O projeto
KSoap2-android é uma biblioteca de SOAP para a plataforma Android. Neste
artigo, acessaremos um serviço da Web JAX-WS para o qual um WSDL é
fornecido a partir de um cliente do Android. O serviço da Web retorna
uma mensagem “Hello” em resposta a uma solicitação que contém um nome.
Criaremos um cliente de serviço da Web para o Android usando o plug-in
de ADT para Eclipse e a biblioteca KSoap2-android. Testaremos o cliente
de serviços da Web em um AVD (Android Virtual Device). A resposta do
envio de uma solicitação para um serviço da Web Hello com o nome como argumento de solicitação é apresentada em um emulador de dispositivo virtual do Androd.

Visão Geral

O artigo contém as seguintes seções:

1. Pré-requisitos
2. Criando um serviço da Web em JAX-WS
3. Instalando o plug-in de ADT do Eclipse & SDK
4. Criando um projeto Android
5. Instalando a biblioteca KSoap2-android
6. Criando o layout
7. Criando a classe Activity
8. Configurando a permissão de acesso à Internet
9. Criando um Android Virtual Device (AVD)
10. Executando o Android Client para acessar o serviço da Web

Pré-requisito

Este artigo pressupõe conhecimento prévio dos serviços da Web.
Criaremos um serviço da Web simples em JAX-WS que toma um nome como
argumento e retorna um cumprimento “Hello”. Para desenvolver um serviço
da Web, precisaríamos das seguintes estruturas de software:

1. Eclipse IDE
2. Um servidor de aplicativos que suporta serviços da Web em JAX-WS. Para
   obter um tutorial para iniciantes sobre o desenvolvimento de um serviço
   da Web em JAX-WS com o WebSphere, consulte o sub-título Recursos.

Para desenvolver um cliente Android para o serviço da Web, precisaríamos dos seguintes componentes de software:

1. Eclipse IDE
2. Android SDK
3. Plug-in de ADT para Eclipse
4. Biblioteca KSoap2-android

Criando um serviço de Web em Jax-WS

Um serviço da Web em JAX-WS consiste basicamente em uma classe Java comentada com a anotação javax.jws.WebService, o terminal do serviço da Web. Como opção, o serviço da Web pode ser
composto por uma interface de terminal em serviço que é implementada
pela sua classe. Uma classe de implementação de serviço da Web não pode
ser abstract ou final. Os métodos de
negócios da classe de implementação que serão expostos como operações
para um cliente de serviço da Web devem ser public e não podem ser static ou final. Crie uma classe de implementação de serviços da Web HelloWSImpl, comentada com a anotação @WebService que implementa a interface HelloWS . A classe de implementação contém um método hello que toma um parâmetro String como nome e retorna uma mensagem Hello que contém esse nome. A classe de implementação é apresentada na Listagem 1.

Lista 1. Classe de implementação de serviços da Web HelloWSImpl.java

package hello_webservice;
import javax.jws.*;
@WebService(portName = "HelloWSPort", serviceName = "HelloWSService", 
	targetNamespace = "http://hello_webservice/", 
	endpointInterface = "hello_webservice.HelloWS")
public class HelloWSImpl implements HelloWS {
	public String hello(String name) {
		// replace with your impl here
		 return "Hello "+name +" Welcome to Web Services!";

	}
}

A interface de terminal em serviço HelloWS contém o método hello comentado com a anotação @WebMethod e é apresentado na Listagem 2. 

Lista 2. Interface de terminal em serviço HelloWS.java

package hello_webservice;
import javax.jws.WebMethod;
import javax.jws.WebService;
@WebService(name = "HelloWS", targetNamespace = 
	"http://hello_webservice/")
public interface HelloWS {
	@WebMethod(operationName = "hello")
	public String hello(String name);
} 

Em seguida, crie um WSDL para o serviço da Web. O serviço da Web deve
ser disponibilizado para um cliente Android como WSDL. O WSDL é um
documento em formato XML para descrever um serviço da Web como uma
coleção de terminais de rede, também chamados de portas. As mensagens
são definições abstratas dos dados que estão sendo trocados, e os tipos
de porta são uma coleção abstrata de operações. A visualização Design do
WSDL para o serviço da Web HelloWSService é mostrada na Figura 1.

Figura 1. Visualização Design do WSDL

O WSDL do serviço da Web é mostrado na Figura 2.

Figura 2. WSDL do serviço da Web

Instalando o plug-in de ADT do Eclipse & SDK

O Android Development Tools (ADT) é um plug-in para o Eclipse IDE que
fornece um ambiente integrado para desenvolver aplicativos Android. O
Android SDK fornece ferramentas e bibliotecas para desenvolver
aplicativos Android. Para instalar o plug-in de ADT, selecione
Help>Install New Software… Clique em Add. Em Add Repository,
especifique um nome em Name e o local https://dl-ssl.google.com/android/eclipse/, como mostra a Figura 3. Clique em OK.

Figura 3. Criando um repositório para o plug-in de ADT

Selecione Developer Tools da maneira mostrada na Figura 4 e clique em Next.

Figura 4. Instalando Developer Tools

Clique em Next em Install Details. Aceite os termos dos contratos de
licença e clique em Finish. O plug-in de ADT é instalado. Em seguida,
instale o Android SDK. Faça o download do pacote de início do Android (installer_r09-windows.exe
para Windows). Clique no instalador para iniciar o Android SDK Tools
Setup Wizard. O JDK é necessário para instalar o Android SDK. Caso ainda
não possua o JDK 5.0/6.0 instalado, instale-o. Clique em Next.
Especifique o local de instalação (C:Program FilesAndroidandroid-sdk-windows
é o padrão) e clique em Next. Escolha uma pasta do menu Iniciar e
clique em Install. O Android SDK Tools é instalado como mostra a Figura
5. Clique em Next.

Figura 5. Instalando o Android SDK Tools

Clique em Finish. O Android SDK e o AVD Manager são iniciados. Selecione
os pacotes que devem ser instalados em Available Packages. Instale os
pacotes mostrados na Figura 6.

Figura 6. Android SDK e AVD Manager

Em seguida, configure as preferências do Android. Selecione Window >
Preferences no Eclipse. Em Preferences, selecione o nó do Android.
Especifique SDK Location como mostra a Figura 7.

Figura 7. Configurando o local do Android SDK

Criando um projeto Android

Em seguida, crie um projeto Android no qual criaremos o cliente de
serviço da Web para o Android. No Eclipse IDE, selecione File > New.
Em New, selecione Android>Android Project como mostrado na Figura 8.
Clique em Next.

Figura 8. Novo projeto do Android

Em New Android Project, especifique o nome do projeto (AndroidWSClient).
Em Build Target, selecione Android 2.2. Em Properties, especifique um
nome de aplicativo e um nome de pacote. Marque a caixa de seleção Create
Activity e especifique a classe Activity (AndroidWSClient).
Uma atividade representa uma interação com o usuário, e a classe que
estende a classe Activity cria uma janela para uma UI. Especifique a
versão mínima do SDK como 8 e clique em Next como mostrado na Figura 9.

Figura 9. Criando um novo projeto Android

Em New Android Test Project, pode-se criar um projeto de teste. Não
criaremos um projeto de teste. Clique em Finish. Um projeto de Android é
criado, como mostra a Figura 10. O projeto Android se baseia nos
seguintes componentes essenciais:

1. Uma classe de atividade (AndroidWSClient), que estende a classe Activity.
2. Um arquivo res/layout/main.xml para especificar o layout do aplicativo Android.
3. O arquivo AndroidManifest.xml
   , que contém informações essenciais sobre o aplicativo, como o nome do
   pacote, componentes do aplicativo, processos, permissões e o nível
   mínimo de API para o sistema Android.

Figura 10. Projeto Android

Instalando a biblioteca Ksoap2-android

A biblioteca Ksoap2-android é uma biblioteca de SOAP leve e eficiente para a plataforma Android. Faça o download de
ksoap2-android-assembly-2.4-jar-with-dependencies.jar a
partir do projeto ksoap2-android. Inclua o JAR de montagem
Ksoap2-android, que inclui as dependências do Java Build Path, como
mostra a Figura 11.

Figura 11. A biblioteca Ksoap2-android

Criando o layout

Em res/layout/main.xml , especifique o layout dos
componentes de UI do Android. Criaremos uma UI em que a resposta do
serviço da Web é exibida como uma mensagem de texto. Crie um LinearLayout em que os subelementos são exibidos em um layout linear de forma vertical. Inclua um elemento TextView , com resultado de ID, para exibir a resposta do serviço da Web para uma chamada de método referente a hello
. A chamada de método envia um nome como argumento e obtém uma mensagem
“Hello” como resposta. Como opção, é possível criar um elemento TextView
para um título. O layout gráfico do aplicativo cliente de serviço da
Web do Android é mostrado na Figura 12. A tela do Android fica
praticamente vazia com uma disposição para exibir uma resposta de
serviço da Web como mensagem de texto.

Figura 12. O Layout Gráfico

O arquivo de layout main.xml é apresentado na Listagem 3.

Lista 3. Arquivo de layout main.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
	android:orientation="vertical" android:layout_width="fill_parent"
	android:layout_height="fill_parent">
	<TextView android:layout_width="fill_parent"
		android:layout_height="wrap_content" android:text="" />
	<TextView android:id="@+id/result" android:layout_width="fill_parent"
		android:layout_height="wrap_content" />
</LinearLayout>

Criando a classe Activity

A classe AndroidWSClient é a classe de atividade de um aplicativo Android e estende a classe Activity . Nesta seção, iremos desenvolver a classe activity AndroidWSClient . Importe as classes necessárias de Ksoap2-android:

import org.ksoap2.SoapEnvelope;
import org.ksoap2.serialization.SoapObject;
import org.ksoap2.serialization.SoapPrimitive;
import org.ksoap2.serialization.SoapSerializationEnvelope;
import org.ksoap2.transport.HttpTransportSE;
import org.ksoap2.serialization.PropertyInfo;

Defina as constantes explicadas na Tabela 1

Tablela 1. Constantes na classe Activity

Os valores de constante são apresentados a seguir, o endereço IP da constante da URL varia:

private static final String NAMESPACE = "http://hello_webservice/";
private static String URL="http://192.168.1.68:7001/HelloWebService/HelloWSService?WSDL"; 
private static final String METHOD_NAME = "hello";
private static final String SOAP_ACTION =  "http://hello_webservice/hello";

Todas as atividades devem implementar o método onCreate para a inicialização das atividades. Defina a UI usando o método setContentView e o recurso de layout.

setContentView(R.layout.main);

Crie um objeto TextView de widget Android usando o método findViewById no elemento TextView definido em main.xml.

TextView lblResult = (TextView) findViewById(R.id.result);

Crie um objeto org.ksoap2.serialization.SoapObject para
desenvolver uma solicitação de SOAP. Especifique o namespace do objeto
SOAP e o nome de método que deve ser chamado no construtor SoapObject .

SoapObject request = new SoapObject(NAMESPACE, METHOD_NAME);

Crie um objeto org.ksoap2.serialization.PropertyInfo para
conter as informações de propriedade que devem ser enviadas com a
chamada de método SOAP. Cada propriedade requer um novo objeto PropertyInfo . O método hello toma apenas um argumento como nome. Defina o nome de propriedade como “arg0” e especifique o tipo como STRING_CLASS. Inclua o objeto PropertyInfo no SoapObject usando o método addProperty .

PropertyInfo propInfo=new PropertyInfo();
propInfo.name="arg0";
propInfo.type=PropertyInfo.STRING_CLASS;
request.addProperty(propInfo, "John Smith");

Em seguida, crie um envelope de SOAP. Use a classe SoapSerializationEnvelope , que estende a classe SoapEnvelop
, com suporte para o formato SOAP Serialization, que representa a
estrutura de uma mensagem SOAP serializado. A principal vantagem de
serialização do SOAP é a portabilidade.

SoapSerializationEnvelope envelope = new SoapSerializationEnvelope(SoapEnvelope.VER11); 

A constante SoapEnvelope.VER11 indica o SOAP versão 1.1. Designe o objeto de solicitação SoapObject para o envelope como a mensagem de saída referente à chamada de método de SOAP.

envelope.setOutputSoapObject(request);

Crie um objeto org.ksoap2.transport.HttpTransportSE que representa uma camada HttpTransport baseada em J2SE. HttpTransportSE estende a classe org.ksoap2.transport.Transport , que resume a serialização e desserialização das mensagens SOAP.

HttpTransportSE androidHttpTransport = new HttpTransportSE(URL);

Faça a chamada de SOAP usando SOAP_ACTION e o envelope de SOAP.

androidHttpTransport.call(SOAP_ACTION, envelope);

Obtenha a resposta do serviço da Web usando o método getResponse do objeto SoapSerializationEnvelope e converta o objeto de resposta para SoapPrimitive. Essa é a classe usada para resumir tipos primitivos.

SoapPrimitive  resultsRequestSOAP = (SoapPrimitive) envelope.getResponse();

Defina a mensagem de cadeia de caractere na resposta de SOAP no componente de UI TextView .

lblResult.setText(resultsRequestSOAP.toString());

A classe Activity é apresentada abaixo na Listagem 4.

package android.webservice.client;


import org.ksoap2.SoapEnvelope;
import org.ksoap2.serialization.SoapObject;
import org.ksoap2.serialization.SoapPrimitive;
import org.ksoap2.serialization.SoapSerializationEnvelope;
import org.ksoap2.transport.HttpTransportSE;
import org.ksoap2.serialization.PropertyInfo;


import android.widget.TextView;
import android.app.Activity;
import android.os.Bundle;
import android.widget.ArrayAdapter;
import android.widget.AutoCompleteTextView;


public class AndroidWSClient extends Activity {


 private static final String NAMESPACE = "http://hello_webservice/";
 private static String URL = "http://192.168.1.68:7001/HelloWebService/
	HelloWSService?WSDL"; 
 private static final String METHOD_NAME = "hello";
 private static final String SOAP_ACTION =  "http://hello_webservice/hello";

 private TextView lblResult;


 @Override
 public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.main);

  lblResult = (TextView) findViewById(R.id.result);

  SoapObject request = new SoapObject(NAMESPACE, METHOD_NAME); 


  PropertyInfo propInfo=new PropertyInfo();
  propInfo.name="arg0";
  propInfo.type=PropertyInfo.STRING_CLASS;

  request.addProperty(propInfo, "John Smith");  

  SoapSerializationEnvelope envelope = new SoapSerializationEnvelope(SoapEnvelope.VER11); 

  envelope.setOutputSoapObject(request);
 HttpTransportSE androidHttpTransport = new HttpTransportSE(URL);

  try {
   androidHttpTransport.call(SOAP_ACTION, envelope);

    SoapPrimitive  resultsRequestSOAP = (SoapPrimitive) envelope.getResponse();


   lblResult.setText(resultsRequestSOAP.toString());


  } catch (Exception e) {


  }

 }
} 

Configurando a permissão de acesso à Internet

Para acessar um serviço da Web a partir de um dispositivo Android, precisamos ativar uma permissão em AndroidManifest.xml que permita que os aplicativos abram soquetes de rede. Inclua o seguinte elemento uses-permission .

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

O AndroidManifest.xml com a permissão definida é mostrado na Figura 13.

Figura 13. Definindo a permissão INTERNET

O AndroidManifest.xml é apresentado na Listagem 5. 

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="android.webservice.client"
      android:versionCode="1"
      android:versionName="1.0">
    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".AndroidWSClient"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
    <uses-permission android:name="android.permission.INTERNET"></uses-permission>
    <uses-sdk android:minSdkVersion="8" />

</manifest>
</uses-permission>

Lista 5. AndroidManifest.xml

Criando um AVD

O Android SDK fornece um emulador de dispositivo remoto, um
dispositivo remoto virtual para desenvolver e testar aplicativos de
Android. O emulador suporta configurações do Android Virtual Device
(AVD) com as quais outras opções de dispositivo remoto virtual, como a
plataforma Android, podem ser especificadas. Para criar um AVD, clique
em Window>Android SDK e AVD Manager. Clique em Virtual devices e em
New, como mostra a Figura 14.

Figura 14. Criando um AVD

Em Create New AVD, especifique um nome em Name e selecione Target como
Android 2.2-API level 8. Especifique SD Card size como 100 MiB. Deve ser
suficiente para instalar o aplicativo de cliente da Web. A
especificação de um valor mais baixo, como 10, pode gerar o erro “No
space left on device”. Clique em Create AVD para criar um AVD, como
mostra a Figura 15.

Figura 15. Configurando o AVD

Um novo AVD é criado como mostra a Figura 16.

Figura 16. Novo AVD

Executando o cliente do Android para acessar o serviço da Web

O emulador de Android fornece várias opções de customização. Por exemplo, para escalar o emulador, especifique o valor scale com a seguinte opção:

-scale <value>

Para especificar uma opção de emulador, clique com o botão direito no aplicativo AndroidWSClient e selecione Run As..>Run Configurations. Selecione o aplicativo AndroidWSClient e especifique a opção -scale no campo Additional Emulator Command Line Options e clique em Apply, como mostra a Figura 17.

Figura 17. Definindo a opção de escala do emulador

Para instalar e executar o aplicativo AndroidWSClient no emulador, clique com o botão direito em AndroidWSClient e selecione Run As..>Android Application, como mostra a Figura 18.

Figura 18. Executando o aplicativo Android

O aplicativo AndroidWSClient é instalado no AVD como mostra a Figura 19. Clique no aplicativo para executar o cliente de serviço da Web no AVD.

Figura 19. Cliente de serviço da Web de Android instalado

O serviço da Web é chamado e a resposta do serviço da Web é exibida no emulador de Android, como mostrado na Figura 20.

Figura 20. Acessando o serviço da Web

A saída da execução do aplicativo Android é mostrada na Listagem 6.

AndroidWSClient] Android Launch!
 AndroidWSClient] adb is running normally.
 AndroidWSClient] Performing android.webservice.client.AndroidWSClient activity launch
 AndroidWSClient] Automatic Target Mode: launching new emulator with compatible AVD 
	'AndroidAVD'
 AndroidWSClient] Launching a new emulator with Virtual Device 'AndroidAVD'
 AndroidWSClient] New emulator found: emulator-5554
 AndroidWSClient] Waiting for HOME ('android.process.acore') to be launched...
 AndroidWSClient] HOME is up on device 'emulator-5554'
 AndroidWSClient] Uploading AndroidWSClient.apk onto device 'emulator-5554'
 AndroidWSClient] Installing AndroidWSClient.apk...
 AndroidWSClient] Success!
 AndroidWSClient] Starting activity android.webservice.client.AndroidWSClient on device 
	emulator-5554
 AndroidWSClient] ActivityManager: Starting: Intent { act=android.intent.action.MAIN
 cat=[android.intent.category.LAUNCHER] 
 cmp=android.webservice.client/.AndroidWSClient }

Lista 6. Saída do aplicativo Android

Quando o aplicativo Android é executado, as seguintes tarefas são realizadas:

1. Um novo emulador é ativado
2. O AndroidWSClient.apk é transferido por upload para o emulador
3. O AndroidWSClient.apk é instalado
4. A atividade android.webservice.client.AndroidWSClient é iniciada

Recursos

Aprender

• Saiba mais sobre Android Tools e a documentação sobre a criação de aplicativos de Android.
• Na zona de SOA e serviços da Web no developerWorks, obtenha os recursos de projeto necessários para melhorar as suas qualificações em serviços da Web.
• ““Develop and deploy JAX-WS Web services on WebSphere Application Server Community Edition V2.0”
  (developerWorks, setembro de 2007), um tutorial sobre o desenvolvimento
  e implementação de serviços da Web em JAX-WS com o WebSphere
  Application Server.

Obter produtos e tecnologias

• Faça o download do Android SDK.
• Faça o download da biblioteca ksoap2-android.
• Faça o download da versão mais recente do Eclipse para Java EE.