Tecnologia, Desenvolvimento de Software, TV Digital, Internet e Linux

O NCLua SOAP é um módulo escrito totalmente em Lua, que permite o acesso a Web Services SOAP a partir de aplicações de TV Digital. O módulo está em fase beta e implementa as versão 1.1 e 1.2 do protocolo SOAP.

O projeto facilita a convergência entre Web e TV, permitindo o consumo de diferentes serviços, construídos em diferentes linguagens.

Justificativa

Consumir WebService SOAP a partir de uma aplicação NCL/Lua para TV Digital tem sido um desejo de muitos, como tenho acompanhado nos fóruns que participo. Os WebServices são bastante utilizados para integração de aplicações, heterogêneas ou não, pois utilizam um protocolo padronizado pela W3C, baseado em XML e trafegando por HTTP, sem sofrer problemas com firewalls (pelo bloqueio de portas). Eles permitem a criação de aplicações distribuídas, retirando das aplicações clientes, parte da carga de processamento. Na área de aplicações de TV Digital, os WebServices permitem ainda, a integração de tais aplicações com serviços já implementados, sem necessidade de retrabalho, permitindo uma maior convergênica entre TV Digital e Web. Existe um projeto chamado LuaSoap com objetivo semelhante, porém, o mesmo depende de bibliotecas escritas em C/C++, e utiliza, de forma direta, as funções da LuaSocket. Sendo que estas bibliotecas não fazem parte das normas do Sistema Brasileiro de TV Digital (SBTVD), não se pode chamar suas funções diretamente a partir de uma aplicação interativa, pois isso faria com que a mesma não possa ser executada em todos os conversores de TV Digital compatíveis com o Ginga, o middleware do SBTVD. Logo, tais módulos são incompatíveis com o SBTVD, não podendo ser utilizados para desenvolvimento de aplicações de TV Digital. Sabe-se que na versão 0.11.2 da implementação de referência do Ginga, disponível no Portal do Software Público, está sendo utilizada a biblioteca LuaSocket para implementar o módulo tcp, (definido em norma ABNT) para aplicações NCLua. No entanto, esta biblioteca é apenas usada como camada subjacente ao módulo tcp, sendo que suas funções não devem ser utilizadas pelas aplicações desenvolvidas. Deve-se considerar apenas a interface disponibilizada pelo módulo tcp. Com isto, devido ao meu trabalho de mestrado e necessidade de tal recurso, desenvolvi o NCLua SOAP, um módulo escrito completamente em Lua, para ser utilizado em aplicações NCLua para TV Digital.

Outros módulos utilizados (já inclusos no projeto)

O módulo utiliza a biblioteca LuaXML (que foi adaptada para Lua 5) e o módulo NCLua HTTP desenvolvido por mim.

Pré-Requisitos

É recomendado a utilização do Ginga Virtual STB 0.11.2 rev 23 ou superior. A versão anterior do Ginga VSTB possuia algumas dificuldades para acesso à rede a partir da VM, normalmente necessitando de configurações na interface de rede da mesma. Antes de usar o NCLua SOAP na VM, verifique se a mesma está acessando a rede local/internet (usando ping, telnet, wget, curl ou qualquer comando similar). Para isto, fundamentalmente, na tela inicial da VM deve ser exibido o IP da mesma. Caso não esteja conseguindo acesso à rede, tente alterar o modo da interface de rede da VM de bridge para NAT ou vice-versa (é necessário reiniciar a VM após tal alteração).

Artigo Publicado

O Artigo NCLua SOAP: Acesso à Web Services em Aplicações de TVDi foi publicado no Workshop de Computação Aplicada em Governo Eletrônico (WCGE 2011), disponível aqui. Caso o link esteja quebrado, o artigo é disponibilizado na página de download, no fim desta página. Para trabalhos acadêmicos e projetos que utilizem o NCLua SOAP, favor referenciar o artigo publicado. Para referenciar o artigo em documentos Latex, utilize o código bibtex deste link.

Utilizando o NCLua SOAP

Para usar o NCLua SOAP, basta adicionar a linha require “ncluasoap” ao seu script lua. A função principal do módulo é a call (ncluasoap.call), que gera e envia um requisição SOAP e obtém o XML de retorno, que é convertido para uma tabela lua (com o módulo LuaXML) para facilitar o acesso aos dados de retorno da chamada do método remoto. O principal parâmetro da função ncluasoap.call é o msgTable, que deve ser uma tabela lua contendo os dados para acesso ao método no WebService. Na documentação e nos exemplos, é explicado com mais detalhes como isso funciona. Mas veja a seguir a estrutura que deve ter esse parâmetro:

msgTable = {
  address = "url do serviço (não é o endereço do wsdl)",
  namespace = "namespace, exatamente como informado no wsdl",
  operationName = "método remoto que deseja-se acessar",
 
  --Parâmetros de entrada, como definidos no WSDL
  params = {
      paramName1=value1,
      paramName2=value2,
      paramNameN=valueN
  }
}

A função call ainda aceita uma função callback, que é explicado em mais detalhes na documentação do NCLua SOAP e principalmente no módulo http, motivo da necessidade de uso de tais funções. O arquivo lua da sua aplicação deve estar no mesmo diretório do arquivo ncluasoap.lua.

Exemplos

Foram disponibilizadas algumas aplicações de exemplo, que consomem WebServices variados. Para testar os diversos WebServices usados na segunda aplicação de exemplo, basta descomentar uma chamada a ncluasoap.call, dentro da função handler do arquivo exemplo2.lua, comentando o anterior (por motivos de clareza). As aplicações não possuem interface gráfica, logo, todo o resultado é mostrado em mensagens no console. Leia os comentários existentes nos exemplos, pois alguns serviços requerem configurações extras para funcionar (como cadastro/login e senha). Um exemplo completo, mostrando como consumir um WebService de contação de moedas, é exibido abaixo, mostrando a simplicidade do uso do módulo.

---Exemplo simples, mas completo, de uso do NCLua SOAP
require "ncluasoap"
---Função para processar a resposta da requisição SOAP enviada ao WS
--@param xmlTable Tabela lua,
--gerada a partir do XML da resposta à requisição SOAP,
--contendo os dados retornados pelo método remoto do WS
local function getResponse(xmlTable)
  --O nome do elemento que contém o retorno é obtido no WSDL ou no XML de retorno
  print("Cotação do Dolar em Reais:", xmlTable.ConversionRateResult)
end
 
--Cria uma table contendo os dados para envio da requisição SOAP ao WS
local msgTable = {
  address = "http://www.webservicex.net/CurrencyConvertor.asmx",
  --Namespace exatamente como especificado no WSDL, neste caso, terminando com /
  namespace = "http://www.webserviceX.NET/",
  operationName = "ConversionRate",
  params = {
    FromCurrency = "USD", --Dólar
    ToCurrency = "BRL" --Real
  }
}
 
--Executa o método remoto, definido dentro da msgTable,
--gerando uma requisição SOAP, enviando ao WS e obtendo o resultado.
--getResponse é uma função de callback que será executada
--automaticamente, assim que a resposta da chamada remota for obtida.
ncluasoap.call(msgTable, getResponse)
 
--Esta linha é executada automaticamente após a chamada de ncluasoap.call
--A chamada a ncluasoap.call retorna imediatamente, pois é uma chamada
--assíncrona, devido a particularidades do módulo TCP de NCLua.
--Assim, NÃO é possível obter o retorna do método remoto
--fazendo algo como retorno = ncluasoap.call(msgTable).
--Tal instrução não funciona.
print("---------------------------Chamou ncluasoap.call")

Observe que dentro da função getResponse, que recebe uma tabela lua, gerada a partir do XML da resposta à requisição SOAP, o valor retornado pelo WS é obtido por meio do acesso ao elemento ConversionRateResult do parâmetro xmlTable. Por padrão, a tag XML que conterá o valor retornado é formada pelo nome do método, seguido da palavra Result. Assim, para cada WS, o resultado estará em uma tag diferente, podendo ser retornada uma tag composta de várias outras tags com valores. Alguns WSs mostram exemplos das mensagens SOAP trocadas entre os clientes e o servidor. Nestes exemplos você pode verificar qual a estrutura do valor retornado (que pode ser um valor simples: como do exemplo; ou um valor composto: contendo várias tags internas). Os exemplos disponibilizados com o NCLua-SOAP mostram uma forma de exibir todos os valores retornados, por meio de uso de um laço for. A chamada a ncluasoap.call possui ainda um terceiro parâmetro opcional, que indica a versão do protocolo SOAP que deve ser utilizada na comunicação com o WS. Se omitido, é assumido o valor “1.2″. Alguns WebServices suportam tanto a versão 1.1 como 1.2 do SOAP (como os WebServices ASP.NET, as páginas asmx). Outros suportam apenas a 1.1 (como alguns WebServices em PHP), e podem haver outros que só suportem a versão 1.2. Assim, o desenvolvedor precisa atentar à versão do SOAP suportada pelo WS, informação que normalmente pode ser encontrado na página do WebService (a mesma página informada na tabela passada à função call do módulo ncluasoap). OBSERVAÇÃO: O namespace deve ser exatamente como definido no documento WSDL. Se o mesmo terminar com barra, deve ser incluída a barra. Se não terminar, não deve-se incluir. Alguns serviços podem não funcionar (exibindo uma mensagem de erro indicando o correto namespace a ser utilizado) caso não esteja exatamente como apresentado no WSDL.

Tutoriais

Se você tiver exemplos, compartilhe conosco. Entre em contato aqui.

FAQ

1. Porque ocorre o erro “HTTP 415: Media Unsupported”? Este erro pode ocorrer devido à versão da requisição SOAP enviada não ser suportada pelo Web Service. Verifique a documentação da função call do módulo NCLua SOAP para saber como especificar a versão do SOAP a ser utilizada pelo módulo. Se não souber qual versão do protocolo SOAP o Web Service reconhece, teste os valores listados na documentação da função call do módulo.
2. Porque ocorre o erro “unprotected error in call to Lua API (tcp.lua:xx: /usr/local/lib/lua/5.1/tcp_event.lua:xx: assertion failed!)”? Este erro pode ocorrer devido a aplicação, rodando no Ginga Virtual STB, não ter acesso à Internet/LAN. Tal problema era comum na versão anterior a 0.11.2 do Ginga Virtual STB. Verifique a seção de pré-requisitos para mais informações.

Contribua com o FAQ. Entre em contato aqui.

Fórum de Discussão

Para tirar dúvidas, relatar bugs, propor melhorias e quaisquer outros assuntos relacionados a Web Services em aplicações NCLua para TV Digital, acesse o Fórum NCLua SOAP no Google Groups.

Participe do grupo NCLua SOAP

E-mail:

Visitar este grupo

Download

O módulo implementa as versões 1.1 e 1.2 do protocolo SOAP, e está em fase beta, podendo conter bugs e inconsistências com o padrão. Assim, use por sua conta e risco! Dúvidas, críticas, sugestões e, principalmente, relatos de problemas com algum WebService, são bem vindos, basta entrar em contato aqui.

Download

Acesse a página do projeto no GitHub para download.

Licença

Doações

Suporte o desenvolvimento e melhorias no projeto. Faça uma doação.

Outros Projetos

Veja outros projetos de TV Digital aqui.

• Reduzindo mensagens geradas no terminal ao executar aplicações #NCL/#Lua no #Ginga Virtual STB. #TVD
• #Ginga.ar 2.0 disponibilizado. #TVD #GingaNCL
• Controle de foco entre aplicação #NCL e aplicação #Lua. #TVD #GingaNCL #in
• Redimensionando e restaurando um vídeo em aplicação #NCL - Parte 2. #TVD #in
• Redimensionando e restaurando um vídeo em aplicação #NCL - Parte 1. #TVD #in
VN:F [1.9.20_1166]
por favor, aguarde...
Rating: 6.0/10 (2 votes cast)
NCLua SOAP: Acesso a Web Services em Aplicações de TVD, 6.0 out of 10 based on 2 ratings
Nenhuma tag para este post.