Neste artigo
continuarei a falar sobre o assunto Web Services. Para quem leu o artigo do mês
passado com o título “Criando um Web Service utilizando o Eclipse Juno” veremos
que neste mês daremos uma continuação no que foi visto, utilizando como
ferramenta o Android com o auxílio de uma biblioteca de terceiros chamada
“KSOAP2”. Este artigo será bem prático, não envolvendo conceitos já citados em
outros artigos. Para ficar mais interessante iremos consumir um Web Service gratuito
para consulta de CEPS e Logradouros do Brasil. Então chega de papo e vamos por
a mão na massa.
Cadastrando no site
Iremos usar
como base para conhecimento o seguinte site:
O Serviço de consulta a
CEP é de uso livre. Sendo que atualmente trabalha com a base de CEP dos
Correios e contém mais de 811.000 logradouros cadastrados. A única
tarefa que devemos realizar seria um pequeno cadastro. Para isto, clique na
região superior direita “Área Usuário” e localize a opção “Criar Novo Usuário”.
Ver Imagem 01.
Figura 01: Criando o
usuário e senha.
Depois de
efetivar o cadastro, em alguns minutos receberá um e-mail para ativação de sua
conta. No primeiro contato ao entrar em sua área específica, receberá um aviso
idêntico aos dizeres a seguir:
“Para Utilizar os
serviços ByJG, você precisa ativar um serviço, selecione no menu acima o
serviço que deseja ativar”.
Localize no
menu acima a região chamada “Serviços CEP – CEP” e clique sobre a mesma.
Deveremos informar mais alguns dados adicionais para concluir e ativar o
serviço de Web Service. Ver Imagem 02
Figura 02:
Ativar Web Service de consulta de CEP.
Possuímos
diversos recursos como: Pesquisas (CEP e Logradouro), gráfico de utilização
entre outros.
Importante: O usuário e
senha serão utilizados ao decorrer do artigo.
Dados do Serviço
O endereço
do serviço é
Possuímos os
seguintes métodos ativos:
- string obterVersao( )
- Retorna a versão do WebService.
- string obterLogradouroAuth( string , string , string )
- Retorna o nome do logradouro à partir do CEP fornecido. Esse método
requer autenticação do usuário.
- string[] obterCEPAuth( string , string , string , string , string )
- Retorna o CEP à partir do nome do logradouro, localidade e unidade
federativa. Esse método requer autenticação de usuário. Se autenticado,
retorna as 20 primeiras linhas encontradas.
O endereço do
descritor do serviço WSDL é:
Adquirindo o framework “Ksoap2”
O framework
“Ksoap2” seria a ferramenta necessária para processar as mensagens SOAP. Ela
pode ser baixada diretamente pelo site:
Neste artigo recomendo utilizar a versão “2.5.8”.
Principais Classes
O framework
“Ksoap2” nos fornece todos os recursos necessários para consumir um Web Service.
Abaixo irei dar uma breve descrição das características destas classes.
1) org.ksoap2.serialization.SoapObject
Se caracteriza por ser um
objeto dinâmico simples que pode ser usado para construir as chamadas do
Ksoap2. Essencialmente, esta classe utiliza dois parâmetros, sendo: o
“namespace” (geralmente o endereço do WebService) e o “name” (o nome do método
a ser utilizado).
Exemplo de
utilização:
SoapObject soap = new SoapObject (namespace, name);
Os métodos:
- (SoapObject) envelope.bodyIn: Obter a resposta do serviço Web.
- getPropertyAsString(): Transformar
o resultado em variáveis do tipo Texto.
2) org.ksoap2.serialization.PropertyInfo
Essa classe é usada para
armazenar informações sobre cada propriedade do método a ser consumido do
webservice. Os métodos são:
- setName(): Nome da variável que
irá ser passada como parâmetro.
- setValue(): Valor que deverá ser
passado para a variável declarada anteriormente.
- setType(): Tipo de dados utilizado
na variável.
Para adicionar estas propriedades em nossa classe “SoapObject” criada
anteriormente deveremos implementar o método “addProperty()”.
Exemplo de
utilização:
PropertyInfo cepProp =new
PropertyInfo();
cepProp.setName("cep");
cepProp.setValue("18999999");
cepProp.setType(String.class);
soap.addProperty(cepProp);
3) org.ksoap2.serialization.SoapSerializationEnvelope
É uma classe 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.
Exemplo
de utilização:
SoapSerializationEnvelope envelope = new
SoapSerializationEnvelope(SoapEnvelope.VER11);
A constante “SoapEnvelope.VER11” indica o SOAP versão
1.1. Faremos o uso de alguns métodos e propriedades, sendo:
- setOutputSoapObject (soap): Método responsável por
designar o objeto de solicitação “SoapObject” para o envelope como a
mensagem de saída referente à chamada de método de SOAP.
- dotNet: propriedade booleana para
definir a compatibilidade com o padrão de codificação .Net.
Exemplo de utilização:
envelope.dotNet
= true;
envelope.setOutputSoapObject(soap);
4) org.ksoap2.transport.HttpTransportSE
A classe “HttpTransportSE” representa uma camada “HttpTransport” baseada em “J2SE. HttpTransportSE”,ela estende a classe “org.ksoap2.transport.Transport” , que resume a serialização e
desserialização das mensagens SOAP. Ao criar o objeto passamos como parâmetro a
URL, que seria o endereço para consumir o Web Service.
Exemplo de utilização:
HttpTransportSE androidHttpTransport = new HttpTransportSE(URL);
Os métodos são:
- Call(SOAP_ACTION, envelope): responsável pela chamada usando como parâmetro o endereço do WebService + Método e o envelope SOAP.
Exemplo de utilização:
androidHttpTransport.call(SOAP_ACTION, envelope);
Criando o exemplo
No exemplo
deste artigo iremos envolver todos os conceitos aprendidos anteriormente. O
funcionamento deste exemplo será bem simples. Informaremos o CEP para nos
retornar o Endereço, Bairro, Cidade, Estado e Código IBGE. Para isto
descreverei todos os passos daqui pra frente.
Inicie uma aplicação do Zero clicando em “File/New/Android Project...” criando
uma classe chamada “ConsumindoWSActivity” para estender (extends) para a
interface “Activity” (Nesta classe é onde chamaremos a classe principal mais
adiante). Clique sobre o pacote e com o botão direito escolha “New/Class”
escolhendo o nome como CEP. (nesta classe onde criaremos todos os métodos
responsáveis pela consulta do CEP).
De imediato
teremos duas classes. Ver Figura 03 para maiores detalhes.
Figura 03: Classes do Projeto.
Importando a Biblioteca “Ksoap2”
Depois de ter conhecido um pouco sobre
este framework e de ter realizado o download, recomendo criar uma pasta chamada
“Libs” no projeto para melhor organização. É ali onde armazenaremos nossas
bibliotecas, que no caso seria apenas uma, a “ksoap2-android-assembly-2.5.8-jar-with-dependencies.jar”.
Para importá-la clique com o botão direito escolhendo a opção “Properties”. Em
“Java Build Path” localize a aba “Libraries”. Clique em “Add JARs...” para
adicioná-la ao projeto em questão. Ver Imagem 04.
Figura 04: Adicionado a Biblioteca
Ksoap2.
Teremos todas as classes necessárias
adicionadas ao projeto.
Classe “Cep.java”
O primeiro passo é importar as classes
utilizadas ao decorrer do desenvolvimento, veja abaixo:
package pct.ConsumindoWS;
import org.ksoap2.SoapEnvelope;
import org.ksoap2.serialization.PropertyInfo;
import org.ksoap2.serialization.SoapObject;
import org.ksoap2.serialization.SoapSerializationEnvelope;
import org.ksoap2.transport.HttpTransportSE;
public class Cep
{
private static final String NAMESPACE =
"http://www.byjg.com.br/";
private static String URL = "http://www.byjg.com.br/site/webservice.php/ws/cep";
private static final String SOAP_ACTION =
"http://www.byjg.com.br/obterLogradouroAuth";
Teremos
três constantes, sendo:
NAMESPACE: O endereço do site que contém o Web Service.
URL: O endereço do serviço Web Service.
SOAP_ACTION: O endereço do site +
método utilizado.
public String[] ObterLogradouro(String Cep)
{
SoapObject soap = new SoapObject(NAMESPACE,
"obterLogradouroAuth");
String usuario = "usuario";
String senha = "senha";
PropertyInfo cepProp =new PropertyInfo();
cepProp.setName("cep");
cepProp.setValue(Cep);
cepProp.setType(String.class);
soap.addProperty(cepProp);
PropertyInfo usuarioProp =new PropertyInfo();
usuarioProp.setName("usuario");
usuarioProp.setValue(usuario);
usuarioProp.setType(String.class);
soap.addProperty(usuarioProp);
PropertyInfo
senhaProp =new PropertyInfo();
senhaProp.setName("senha");
senhaProp.setValue(senha);
senhaProp.setType(String.class);
soap.addProperty(senhaProp);
SoapSerializationEnvelope envelope = new SoapSerializationEnvelope(SoapEnvelope.VER11);
envelope.dotNet = true;
envelope.setOutputSoapObject(soap);
HttpTransportSE
androidHttpTransport = new HttpTransportSE(URL);
try
{
androidHttpTransport.call(SOAP_ACTION, envelope);
SoapObject result =
(SoapObject) envelope.bodyIn;
return result.getPropertyAsString(0).split(",");
}
catch (Exception e)
{
return null;
}
}
}
O método ObterLogradouro() tem como
parâmetro de entrada o Cep, uma variável do tipo String, e de saída uma
variável do tipo “Array of strings”, pois a mesma nos retorna os dados de
Endereço, Bairro, Cidade, Estado e Código IBGE. Instancie a classe “SoapObject”
passando como parâmetros as constantes (NAMESPACE e ObterLogradouroAuth).
Deixaremos como estático também as variáveis de autenticação Usuário e Senha
(Lembrando que estas informações foram adquiridas no início do artigo).
Criaremos três objetos do tipo “PropertyInfo” , sendo o CEP, Usuário e Senha.
Estas variáveis estão presentes no método “ObterLogradouroAuth()” . O método
“soap.AddProperty” está incluindo todos estes dados na classe “SoapObject”. O
Objeto “SoapSerializationEnvelope” representa a estrutura do SOAP, utilizaremos
ele para serializar os dados. Ao criar o objeto “HttpTransportSE” passamos como
parâmetro a URL, que seria o endereço para consumir o WebService comentado anteriormente.
Dentro do bloco “Try...Catch” obtemos o resultado transformado em um Vetor de
String.
Configurações no “AndroidManifest.xml”
A única alteração que não podemos esquecer-nos
de programar neste arquivo seria a permissão para acesso a internet. Veremos a
seguir o código necessário.
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="pct.ConsumindoWS"
android:versionCode="1"
android:versionName="1.0">
<uses-sdk android:minSdkVersion="8" />
<uses-permission android:name="android.permission.INTERNET"/>
<application android:icon="@drawable/icon" android:label="@string/app_name">
<activity android:name=".ConsumindoWSActivity"
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>
</manifest>
Criando o “Lay-Out”
Usaremos 6
EditTexts, 6 TextViews e 1 Button para esta tela. Ver Imagem 05 uma sugestão
para nossa interface gráfica.
Figura 05: Lay-Out
Proposto.
O XML
correspondente:
<?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"
>
<LinearLayout android:layout_width="match_parent"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout01">
<LinearLayout android:layout_width="185dp"
android:orientation="vertical"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout02">
<TextView android:layout_width="wrap_content"
android:text="CEP"
android:textAppearance="?android:attr/textAppearanceMedium"
android:layout_height="wrap_content"
android:id="@+id/txtCep">
</TextView>
<EditText android:id="@+id/edtCep"
android:layout_width="168dp"
android:layout_height="wrap_content"
android:inputType="number"
android:maxLength="8">
</EditText>
</LinearLayout>
<LinearLayout android:layout_width="match_parent"
android:orientation="vertical"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout03">
<TextView android:layout_width="wrap_content"
android:text=" "
android:textAppearance="?android:attr/textAppearanceMedium"
android:layout_height="wrap_content"
android:id="@+id/TextView02">
</TextView>
<Button android:id="@+id/btnBuscar"
android:layout_width="90dp"
android:text="Buscar"
android:layout_height="wrap_content"
android:onClick="Buscar">
</Button>
</LinearLayout>
</LinearLayout>
<LinearLayout android:layout_width="match_parent"
android:orientation="vertical"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout04">
<TextView android:layout_width="wrap_content"
android:text="Endereço:"
android:textAppearance="?android:attr/textAppearanceMedium"
android:layout_height="wrap_content"
android:id="@+id/TextView04">
</TextView>
<EditText android:id="@+id/edtEndereco"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:editable="false"
android:enabled="false">
</EditText>
</LinearLayout>
<LinearLayout android:layout_width="match_parent"
android:orientation="vertical"
android:layout_height="wrap_content"
android:id="@+id/linearLayout05">
<TextView android:layout_width="wrap_content"
android:text="Bairro:"
android:textAppearance="?android:attr/textAppearanceMedium"
android:layout_height="wrap_content"
android:id="@+id/txtBairro">
</TextView>
<EditText android:id="@+id/edtBairro"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:enabled="false">
</EditText>
</LinearLayout>
<LinearLayout android:orientation="vertical"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout06"
android:layout_width="248dp">
<TextView android:layout_width="wrap_content"
android:text="Cidade"
android:textAppearance="?android:attr/textAppearanceMedium"
android:layout_height="wrap_content"
android:id="@+id/txtCidade">
</TextView>
<EditText android:id="@+id/edtCidade"
android:layout_height="wrap_content"
android:layout_width="236dp"
android:enabled="false">
</EditText>
</LinearLayout>
<LinearLayout android:layout_width="match_parent"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout07">
<LinearLayout android:orientation="vertical"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout08"
android:layout_width="154dp">
<TextView android:layout_width="wrap_content"
android:text="Estado"
android:textAppearance="?android:attr/textAppearanceMedium"
android:layout_height="wrap_content"
android:id="@+id/txtEstado">
</TextView>
<EditText android:id="@+id/edtEstado"
android:layout_height="wrap_content"
android:layout_width="110dp"
android:enabled="false">
</EditText>
</LinearLayout>
<LinearLayout android:layout_width="match_parent"
android:orientation="vertical"
android:layout_height="wrap_content"
android:id="@+id/LinearLayout09">
<TextView android:layout_width="wrap_content"
android:text="Cód.
IBGE"
android:textAppearance="?android:attr/textAppearanceMedium"
android:layout_height="wrap_content"
android:id="@+id/txtCodIBGE">
</TextView>
<EditText android:id="@+id/edtCodIBGE"
android:layout_height="wrap_content"
android:layout_width="110dp"
android:enabled="false">
</EditText>
</LinearLayout>
</LinearLayout>
</LinearLayout>
Codificando o exemplo (“ConsumindoWSActivity.java”)
Este é o
momento onde usaremos a classe CEP criada anteriormente. Importaremos algumas
bibliotecas básicas.
package pct.ConsumindoWS;
import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.EditText;
public class ConsumindoWSActivity extends Activity
{
public EditText edtCep, edtEndereco, edtBairro,
edtCidade, edtEstado, edtCodIBGE;
Armazenaremos
o resultado nestas variáveis do tipo públicas.
@Override
public void onCreate(Bundle
savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
InicializaListeners();
}
public void InicializaListeners()
{
edtCep = (EditText) findViewById(R.id.edtCep);
edtEndereco = (EditText) findViewById(R.id.edtEndereco);
edtBairro = (EditText) findViewById(R.id.edtBairro);
edtCidade = (EditText) findViewById(R.id.edtCidade);
edtEstado = (EditText) findViewById(R.id.edtEstado);
edtCodIBGE = (EditText) findViewById(R.id.edtCodIBGE);
}
No
método “OnCreate()” Inicializaremos os “listeners“ atribuindo corretamente para
as variáveis. Recomendo sempre criar uma função para realizar este
procedimento.
public void Buscar(View v)
{
if (edtCep.getText().toString().length() == 8)
{
Cep cep = new Cep();
String[] resultado = cep.ObterLogradouro(edtCep.getText().toString());
try
{
edtEndereco.setText(resultado[0]);
edtBairro.setText(resultado[1]);
edtCidade.setText(resultado[2]);
edtEstado.setText(resultado[3]);
edtCodIBGE.setText(resultado[4]);
}
catch (Exception e)
{
edtBairro.setText("");
edtCidade.setText("");
edtEstado.setText("");
edtCodIBGE.setText("");
}
}
}
}
No método Buscar,
chamaremos o evento “Click” do Botão. Instancie a classe CEP e logo em seguida
invoque o método “ObterLogradouro()”. Passaremos como parâmetro o CEP
informado. Trataremos também o resultado dentro de um bloco Try..Catch. Teremos um resultado idêntico ao da Figura 06.
Exemplo em “Run-Time”
Figura 06:
Consulta de CEPs.
Referências
Conclusão
Aprendemos
neste artigo quais são as etapas para consumir um Web Service utilizando a
plataforma Android utilizando o Framework “Ksoap2”. Este WebService é
totalmente gratuito e possui outros métodos que podem ser consumidos, como por
exemplo: o ObterCepAuth(), que retorna o Cep a partir do logradouro,
localidade ou unidade federativa. Fiquem a vontade para usá-lo caso ache
necessário.
Espero que
tenham gostado um forte abraço e até o mês que vem!
