Esta seção tem como objetivo apresentar os primeiros passos necessários para utilizar os web services MapLink utilizando as plataformas .NET, Java ou realizando o consumo das operações através de requisições XML.

Os exemplos de consumo das operações descritos na documentação da API são compatíveis com a versão do framework .NET 3.5 ou superior, utilizam a linguagem de programação C# e fazem parte de um projeto do tipo “Console Application”, onde os dados de saída da aplicação são exibidos em uma janela de linha de comando.

A seguir são descritos os procedimentos necessários para configurar o ambiente na plataforma .NET utilizando a ferramenta de desenvolvimento Visual Studio 2010. Existe uma versão gratuita deste ambiente de desenvolvimento intitulado “Express”, o qual pode ser encontrado através deste endereço: Produtos Visual Studio 2010 Express.

  1. Com o Visual Studio aberto selecione a opção do menu “File -> New -> Project” (ou use a tecla de atalho Ctrl+ Shift + N).

  2. Configuração do Ambiente .NET - Imagem 01

  3. Escolha o projeto do tipo “Windows -> Console Application” e selecione a versão do framework 3.5 ou superior. Dê um nome para o projeto e escolha o diretório onde ele será criado. Confirme a criação do projeto através da opção “OK”.

  4. Configuração do Ambiente .NET - Imagem 02

  5. Após o projeto ser criado na janela “Solution Explorer” (se ela não estiver sendo exibida, ativá-la através do menu “View -> Solution Explorer”), clicar com o botão direito sobre o projeto e selecionar a opção “Add Service Reference”.

  6. Configuração do Ambiente .NET - Imagem 03

  7. Com a janela “Add Service Reference” aberta, preencha o campo “Address” com o endereço do Web Service MapLink. É preciso definir o caminho para o WSDL do serviço, onde neste endereço existem as especificações da estrutura das entidades e operações contidas no serviço. Na imagem abaixo é utilizado o endereço do serviço “AddressFinder”. Clique na opção “Go” para que seja feito a busca pelo serviço exposto.

  8. Configuração do Ambiente .NET - Imagem 04

  9. Dê um nome para o namespace a ser utilizado nas entidades do serviço a serem criadas através do campo “Namespace”. Clica em OK para que sejam criadas as classes de acesso as operações do serviço.

  10. Configuração do Ambiente .NET - Imagem 05

  11. Crie uma nova classe e adicione a diretiva using para utilizar as entidades mapeadas através do serviço “AddressFinder”. Como o nome do projeto criado é “MaplinkAPIWebServices.Samples”, é necessário incluir a seguinte diretiva na classe usada para consumir o serviço:

  12. using MaplinkAPIWebServices.Samples.ServiceAddressFinder;


  13. Utilize os exemplos de consumo das operações do serviço AddressFinder disponíveis na documentação. O código abaixo apresenta a implementação de consumo do método FindAddress e exibição dos dados de retorno na janela de saída.
  14. Segue abaixo um exemplo de retorno da aplicação com os dados obtidos através da operação FindAddress do serviço AddressFinder.

  15. Configuração do Ambiente .NET - Imagem 06

  16. Para visualizar as implementações de consumo de outras operações, consultar a seção de descrição do serviço AddressFinder.

Referências:

Os exemplos de consumo das operações utilizando a plataforma Java descritos na documentação da API utilizam a versão JavaSE-1.7.

A seguir são descritos os procedimentos necessários para configurar o ambiente na plataforma Java utilizando a ferramenta de desenvolvimento Eclipse, versão “Java EE IDE for Web Developers – Juno Service Release”. No endereço a seguir existem informações sobre esta aplicação e o caminho para efetuar o download da mesma: Eclipse Juno Sr1 Packages.

  1. Com o Eclipse aberto selecione a opção do menu “File -> New -> Project”.

  2. Configuração do Ambiente Java - Imagem 01

  3. Escolha o projeto do tipo “Java Project e clique em “Next” para prosseguir.

  4. Configuração do Ambiente Java - Imagem 02

  5. Defina um nome para o projeto através do campo “Project name”, selecione a versão “JavaSE-1.7″ para o ambiente JRE. Escolha o diretório onde o projeto será criado ou deixe a opção “Use default location” selecionada para criar no diretório padrão do workspace. Clique na opção “Finish” para efetuar a criação do projeto.

  6. Configuração do Ambiente Java - Imagem 03

  7. Com o projeto construído é necessário criar um novo package para armazenar a classe com a implementação de consumo da operação do serviço. Clique com o botão direito sobre o nome do projeto e selecione “New -> Package”. Insira o nome do package e confirme a solicitação através do botão “Finish”.

  8. Configuração do Ambiente Java - Imagem 04Configuração do Ambiente Java - Imagem 05

  9. Para criar as entidades com a estrutura existente nas operações do serviço, clique com o botão direito sobre o projeto e selecione a opção “Other” (ou use a tecla de atalho “Ctrl + N”). Selecione “Web Services -> Web Service Client” e clique na opção “Next”.

  10. Configuração do Ambiente Java - Imagem 06

  11. Insira o endereço de acesso do serviço no campo “Service definition”. É preciso definir o caminho para o WSDL do serviço, onde neste endereço existem as especificações da estrutura das entidades e operações contidas no serviço. No campo “Client type” deixe a opção “Java Proxy” selecionada. Clique na opção “Finish” para encerrar o processo.

  12. Configuração do Ambiente Java - Imagem 07

  13. Clique com o botão direito sobre o package criado e selecione a opção “New -> Class”. Defina o nome da classe e selecione a opção “Finish”.

  14. Configuração do Ambiente Java - Imagem 08

  15. Use o comando abaixo para importar as classes geradas para o serviço mapeado (O comando está considerando o nome de package padrão criado pelo ambiente desenvolvimento. Caso o nome do package tenha sido alterado, será necessário realizar a devida customização).


    import br.com.maplink2.webservices.*;


  16. Utilize os exemplos de consumo das operações do serviço AddressFinder disponíveis na documentação. O código abaixo apresenta a implementação de consumo do método FindAddress e a exibição dos dados de retorno na janela de saída do ambiente de desenvolvimento.
  17. Segue abaixo um exemplo de retorno da aplicação com os dados obtidos através da operação FindAddress do serviço AddressFinder.

  18. Configuração do Ambiente Java - Imagem 09

  19. Para visualizar as implementações de consumo de outras operações, consultar a seção de descrição do serviço AddressFinder.

Uma alternativa para testar as operações dos Web Services disponíveis é realizar a chamada ao serviço informando o XML no padrão SOAP de forma direta, sem a intervenção de uma implementação por uma linguagem de programação. Existem alguns aplicativos que permitem se comunicar com serviços SOAP para realizar a troca de mensagens de requisição e retorno. O exemplo descrito a seguir utiliza a aplicação de código aberto SoapUI, a qual pode ser encontrada no endereço de acesso a seguir: informações, download.

  1. Após instalar o aplicativo SoapUI, clique na opção do menu “File -> New Project” (ou utilize a tecla de atalho “Ctrl + N”.

  2. Configuração do Requisição direta via XML - Imagem 01

  3. Informe o endereço de acesso do WSDL do serviço a ser mapeado através do campo “Initial WSDL/WADL”. Defina um nome para o projeto através do campo “Project Name”. Selecione “OK” para confirmar o processo.

  4. Configuração do Requisição direta via XML - Imagem 02

  5. Com o projeto criado, selecione a operação desejada e clique duas vezes sobre a opção “Request 1″.


  6. Uma tela será aberta onde haverá uma divisão entre a mensagem de envio (lado esquerdo) e retorno (lado direito). Para o XML de envio haverá a estrutura do XML SOAP necessário para se comunicar com a operação desejada.

  7. Configuração do Requisição direta via XML - Imagem 04

  8. Utilize o código de exemplo descrito na documentação da operação FindAddress para o serviço AddressFinder.
  9. Clique no ícone representado por uma seta verde – “Submit request to specified endpoint URL”. A requisição para o serviço será realizada utilizando a mensagem XML de envio adicionada na aplicação.


    Configuração do Requisição direta via XML - Imagem 05

  10. Ao término do processamento, o XML de retorno da requisição é exibida na janela do lado direito da aplicação, conforme imagem abaixo:

  11. Configuração do Requisição direta via XML - Imagem 06