XML-RPC - Guia rápido

RPC significa Remote Procedure Call. Como o próprio nome indica, é um mecanismo para chamar um procedimento ou função disponível em um computador remoto. RPC é uma tecnologia muito mais antiga que a web. Efetivamente, o RPC oferece aos desenvolvedores um mecanismo para definir interfaces que podem ser chamadas em uma rede. Essas interfaces podem ser tão simples como uma única chamada de função ou tão complexas como uma grande API.

O que é XML-RPC?

XML-RPC está entre as abordagens de serviço da Web mais simples e infalíveis que torna mais fácil para os computadores chamarem procedimentos em outros computadores.

XML-RPC permite que os programas façam chamadas de função ou procedimento em uma rede.
XML-RPC usa o protocolo HTTP para passar informações de um computador cliente para um computador servidor.
XML-RPC usa um pequeno vocabulário XML para descrever a natureza das solicitações e respostas.
O cliente XML-RPC especifica um nome de procedimento e parâmetros na solicitação XML e o servidor retorna uma falha ou uma resposta na resposta XML.
Os parâmetros XML-RPC são uma lista simples de tipos e conteúdo - structs e arrays são os tipos mais complexos disponíveis.
XML-RPC não tem noção de objetos e nenhum mecanismo para incluir informações que usam outro vocabulário XML.
Com o XML-RPC e os serviços da Web, no entanto, a Web se torna uma coleção de conexões procedurais em que os computadores trocam informações ao longo de caminhos estreitamente limitados.
XML-RPC surgiu no início de 1998; foi publicado pela UserLand Software e inicialmente implementado em seu produto Frontier.

Por que XML-RPC?

Se você precisa integrar vários ambientes de computação, mas não precisa compartilhar estruturas de dados complexas diretamente, você descobrirá que o XML-RPC permite estabelecer comunicações com rapidez e facilidade.

Mesmo se você trabalhar em um único ambiente, poderá descobrir que a abordagem RPC facilita a conexão de programas que possuem diferentes modelos de dados ou expectativas de processamento e que pode fornecer acesso fácil à lógica reutilizável.

XML-RPC é uma excelente ferramenta para estabelecer uma ampla variedade de conexões entre computadores.
XML-RPC oferece aos integradores a oportunidade de usar um vocabulário e abordagem padrão para a troca de informações.
O campo de aplicação mais óbvio do XML-RPC é conectar diferentes tipos de ambientes, permitindo que Java se comunique com Perl, Python, ASP e assim por diante.

Visão geral técnica XML-RPC

XML-RPC consiste em três partes relativamente pequenas:

XML-RPC data model : Um conjunto de tipos para uso na passagem de parâmetros, valores de retorno e falhas (mensagens de erro).
XML-RPC request structures : Uma solicitação HTTP POST contendo informações de método e parâmetro.
XML-RPC response structures : Uma resposta HTTP que contém valores de retorno ou informações de falha.

Estudaremos todos esses três componentes nos próximos três capítulos.

A especificação XML-RPC define seis tipos de dados básicos e dois tipos de dados compostos que representam combinações de tipos.

Tipos de dados básicos em XML-RPC

Tipo	Valor	Exemplos
int ou i4	Inteiros de 32 bits entre - 2.147.483.648 e 2.147.483.647.	<int> 27 </int> <i4> 27 </i4>
em dobro	Números de ponto flutuante de 64 bits	<double> 27,31415 </double> <double> -1,1465 </double>
boleano	verdadeiro (1) ou falso (0)	<boolean> 1 </boolean> <boolean> 0 </boolean>
corda	Texto ASCII, embora muitas implementações suportem Unicode	<string> Olá </string> <string> maluco! @ </string>
dateTime.iso8601	Datas no formato ISO8601: CCYYMMDDTHH: MM: SS	<dateTime.iso8601> 20021125T02: 20: 04 </dateTime.iso8601> <dateTime.iso8601> 20020104T17: 27: 30 </dateTime.iso8601>
base64	Informações binárias codificadas como Base 64, conforme definido na RFC 2045	<base64> SGVsbG8sIFdvcmxkIQ == </base64>

Esses tipos básicos estão sempre incluídos em elementos de valor . Strings (e apenas strings) podem ser incluídos em um elemento de valor , mas omitem o elemento string . Esses tipos básicos podem ser combinados em dois tipos mais complexos, arrays e structs. Arrays representam informações sequenciais, enquanto structs representam pares nome-valor, bem como hashtables, arrays associativos ou propriedades.

As matrizes são indicadas pelo elemento da matriz , que contém um elemento de dados que contém a lista de valores. Como outros tipos de dados, o elemento da matriz deve ser incluído em um elemento de valor . Por exemplo, a seguinte matriz contém quatro strings:

<value>
   <array>
      <data>
         <value><string>This </string></value>
         <value><string>is </string></value>
         <value><string>an </string></value>
         <value><string>array.</string></value>
      </data>
   </array>
</value>

A seguinte matriz contém quatro inteiros:

<value>
   <array>
      <data>
         <value><int>7</int></value>
         <value><int>1247</int></value>
         <value><int>-91</int></value>
         <value><int>42</int></value>
      </data>
   </array>
</value>

Os arrays também podem conter misturas de diferentes tipos, conforme mostrado aqui:

<value>
   <array>
      <data>
         <value><boolean>1</boolean></value>
         <value><string>Chaotic collection, eh?</string></value>
         <value><int>-91</int></value>
         <value><double>42.14159265</double></value>
      </data>
   </array>
</value>

Criar matrizes multidimensionais é simples - basta adicionar uma matriz dentro de uma matriz:

<value>
   <array>
      <data>
		
         <value>
            <array>
               <data>
                  <value><int>10</int></value>
                  <value><int>20</int></value>
                  <value><int>30</int></value>
               </data>
            </array>
         </value>
			
         <value>
            <array>
               <data>
                  <value><int>15</int></value>
                  <value><int>25</int></value>
                  <value><int>35</int></value>
               </data>
            </array>
         </value>
			
      </data>
   </array>
</value>

Uma estrutura simples pode ser semelhante a:

<value>
   <struct>
      <member>
         <name>givenName</name>
         <value><string>Joseph</string></value>
      </member>
		
      <member>
         <name>familyName</name>
         <value><string>DiNardo</string></value>
      </member>
		
      <member>
         <name>age</name>
         <value><int>27</int></value>
      </member>
   </struct>
</value>

Dessa forma, você pode implementar quase todos os tipos de dados suportados por qualquer linguagem de programação.

As solicitações XML-RPC são uma combinação de conteúdo XML e cabeçalhos HTTP. O conteúdo XML usa a estrutura de tipagem de dados para passar parâmetros e contém informações adicionais que identificam qual procedimento está sendo chamado, enquanto os cabeçalhos HTTP fornecem um wrapper para passar a solicitação pela web.

Cada solicitação contém um único documento XML, cujo elemento raiz é um elemento methodCall . Cada methodCall elemento contém um methodName elemento e um params elemento. O elemento methodName identifica o nome do procedimento a ser chamado, enquanto o elemento params contém uma lista de parâmetros e seus valores. Cada elemento params inclui uma lista de elementos param que, por sua vez, contêm elementos de valor .

Por exemplo, para passar uma solicitação para um método chamado circleArea , que usa um parâmetro Double (para o raio), a solicitação XML-RPC seria semelhante a:

<?xml version="1.0"?>
<methodCall>
   <methodName>circleArea</methodName>
      <params>
         <param>
            <value><double>2.41</double></value>
         </param>
      </params>
</methodCall>

Os cabeçalhos HTTP para essas solicitações refletirão os remetentes e o conteúdo. O modelo básico é o seguinte:

POST /target HTTP 1.0
User-Agent: Identifier
Host: host.making.request
Content-Type: text/xml
Content-Length: length of request in bytes

Por exemplo, se o método circleArea estava disponível em um servidor XML-RPC ouvindo em / xmlrpc , a solicitação pode ser semelhante a:

POST /xmlrpc HTTP 1.0
User-Agent: myXMLRPCClient/1.0
Host: 192.168.124.2
Content-Type: text/xml
Content-Length: 169

Montado, todo o pedido ficaria assim:

POST /xmlrpc HTTP 1.0
User-Agent: myXMLRPCClient/1.0
Host: 192.168.124.2
Content-Type: text/xml
Content-Length: 169
<?xml version="1.0"?>
<methodCall>
   <methodName>circleArea</methodName>
      <params>
         <param>
            <value><double>2.41</double></value>
         </param>
      </params>
</methodCall>

É uma solicitação HTTP comum, com uma carga útil cuidadosamente construída.

As respostas são muito parecidas com pedidos, com algumas variações extras. Se a resposta for bem-sucedida - o procedimento foi encontrado, executado corretamente e retornou resultados - então a resposta XML-RPC se parecerá muito com uma solicitação, exceto que o elemento methodCall é substituído por um elemento methodResponse e não há elemento methodName :

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><double>18.24668429131</double></value>
      </param>
   </params>
</methodResponse>

Uma resposta XML-RPC pode conter apenas um parâmetro.
Esse parâmetro pode ser uma matriz ou uma estrutura, portanto, é possível retornar vários valores.
É sempre necessário retornar um valor em resposta. Um "valor de sucesso" - talvez um Booleano definido como verdadeiro (1).

Como as solicitações, as respostas são empacotadas em HTTP e têm cabeçalhos HTTP. Todas as respostas XML-RPC usam o código de resposta 200 OK, mesmo se houver uma falha na mensagem. Os cabeçalhos usam uma estrutura comum semelhante à das solicitações, e um conjunto típico de cabeçalhos pode ser assim:

HTTP/1.1 200 OK
Date: Sat, 06 Oct 2001 23:20:04 GMT
Server: Apache.1.3.12 (Unix)
Connection: close
Content-Type: text/xml
Content-Length: 124

XML-RPC requer apenas suporte HTTP 1.0, mas HTTP 1.1 é compatível.
O Content-Type deve ser definido como text / xml.
O cabeçalho Content-Length especifica o comprimento da resposta em bytes.

Uma resposta completa, com cabeçalhos e uma carga útil de resposta, seria assim:

HTTP/1.1 200 OK
Date: Sat, 06 Oct 2001 23:20:04 GMT
Server: Apache.1.3.12 (Unix)
Connection: close
Content-Type: text/xml
Content-Length: 124

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><double>18.24668429131</double></value>
      </param>
   </params>
</methodResponse>

Depois que a resposta é entregue do servidor XML-RPC para o cliente XML-RPC, a conexão é fechada. As solicitações de acompanhamento precisam ser enviadas como conexões XML-RPC separadas.

As falhas XML-RPC são um tipo de resposta. Se houver um problema no processamento de uma solicitação XML-RPC, o elemento methodResponse conterá um elemento de falha em vez de um elemento params. O elemento de falha, como o elemento params , tem apenas um único valor que indica que algo deu errado. Uma resposta de falha pode ser semelhante a:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value><string>No such method!</string></value>
   </fault>
</methodResponse>

Uma falha também terá um código de erro. XML-RPC não padroniza códigos de erro em tudo. Você precisará verificar a documentação de pacotes específicos para ver como eles lidam com as falhas.

Uma resposta de falha também pode ser semelhante a:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>code</name>
               <value><int>26</int></value>
            </member>
				
            <member>
               <name>message</name>
               <value><string>No such method!</string></value>
            </member>
				
         </struct>
      </value>
   </fault>
</methodResponse>

Para demonstrar XML-RPC, vamos criar um servidor que usa Java para processar mensagens XML-RPC e vamos criar um cliente Java para chamar procedimentos nesse servidor.

O lado Java da conversa usa o Apache XML-RPC do Projeto Apache XML, disponível em http://xml.apache.org/xmlrpc/

Coloque todos os arquivos .jar no caminho apropriado e vamos criar um cliente e um pequeno servidor XML-RPC usando JAVA.

Cliente XML-RPC

Vamos escrever um cliente XML-RPC para chamar uma função chamada função soma . Esta função recebe dois parâmetros e retorna sua soma.

import java.util.*;
import org.apache.xmlrpc.*;

public class JavaClient 
{
   public static void main (String [] args) 
   {
      try {

         XmlRpcClient client = new XmlRpcClient("http://localhost/RPC2"); 
         Vector params = new Vector();
         params.addElement(new Integer(17));
         params.addElement(new Integer(13));

         Object result = server.execute("sample.sum", params);

         int sum = ((Integer) result).intValue();
         System.out.println("The sum is: "+ sum);

      } catch (Exception exception) {
         System.err.println("JavaClient: " + exception);
      }
   }
}

Vamos ver o que aconteceu no cliente de exemplo acima.

O pacote Java org.apache.xmlrpc contém classes para clientes XML-RPC Java e servidor XML-RPC, por exemplo, XmlRpcClient.
O pacote java.util é necessário para a classe Vector.
A função server.execute (...) envia a solicitação para o servidor. A soma do procedimento (17,13) é chamada no servidor como se fosse um procedimento local. O valor de retorno de uma chamada de procedimento é sempre um objeto.
Aqui, "amostra" denota um manipulador que é definido no servidor.
Observe que todos os parâmetros da chamada de procedimento são sempre coletados em um Vetor.
A classe XmlRpcClient é construída especificando o "endereço da web" da máquina do servidor seguido por / RPC2.
- localhost - significa a máquina local
- Você pode especificar um número de IP em vez de localhost, por exemplo, 194.80.215.219
- Você pode especificar um nome de domínio como xyz.dyndns.org
- Você pode especificar um número de porta junto com o nome de domínio como xyz.dyndns.org:8080. A porta padrão é 80
Observe que o resultado da chamada de procedimento remoto é sempre um objeto e deve ser convertido para o tipo apropriado.
Quando ocorrem problemas (sem conexão, etc.), uma Exceção é lançada e deve ser capturada usando a instrução catch .

Devido à chamada acima, um cliente envia a seguinte mensagem ao servidor. Observe que isso é tratado por server.execute (...) internamente e você não tem nada a ver com isso.

<?xml version="1.0" encoding="ISO-8859-1"?>
<methodCall>
   <methodName>sample.sum</methodName>
   <params>
      <param>
         <value><int>17</int></value>
      </param>
		 
      <param>
         <value><int>13</int></value>
      </param>
   </params>
</methodCall>

Servidor XML-RPC

A seguir está o código-fonte do XML-RPC Server escrito em Java. Ele usa classes integradas disponíveis em org.apache.xmlrpc. *

import org.apache.xmlrpc.*;

public class JavaServer 
{ 

   public Integer sum(int x, int y) 
   {
      return new Integer(x+y);
   }

   public static void main (String [] args) 
   {
      try {

         System.out.println("Attempting to start XML-RPC Server...");
         WebServer server = new WebServer(80);
         server.addHandler("sample", new JavaServer());
         server.start();
         System.out.println("Started successfully.");
         System.out.println("Accepting requests. (Halt program to stop.)");
      } catch (Exception exception) 
      {
         System.err.println("JavaServer: " + exception);
      }
   }
}

Vamos ver o que fizemos no servidor de exemplo acima.

O pacote org.apache.xmlrpc contém a classe WebServer para uma implementação de servidor XML-RPC.
A soma do procedimento que é chamada remotamente é implementada como um método público em uma classe.
Uma instância da mesma classe de servidor é então associada a um manipulador que pode ser acessado pelo cliente.
O servidor é inicializado pelo número da porta (aqui: 80).
Quando ocorrem problemas, uma exceção é lançada e deve ser detectada usando a instrução catch .

Para a chamada mencionada no cliente de exemplo fornecido, o servidor envia a seguinte resposta de volta ao cliente:

<?xml version="1.0" encoding="ISO-8859-1"?>
<methodResponse>
   <params>
      <param>
         <value><int>30</int></value>
      </param>
   </params>
</methodResponse>

Agora seu servidor está pronto, compile-o e execute-o no prompt da seguinte maneira:

C:\ora\xmlrpc\java>java JavaServer
Attempting to start XML-RPC Server...
Started successfully.
Accepting requests. (Halt program to stop.)

Agora, para testar a funcionalidade, faça uma chamada para este servidor da seguinte maneira:

C:\ora\xmlrpc\java>java JavaClient
30

Neste tutorial, você aprendeu o que é XML-RPC e por que precisamos do XML-RPC. Discutimos sobre seu modelo de dados, bem como o formato da mensagem de solicitação e resposta a ser trocada entre o cliente e o servidor. Demos um exemplo para demonstrar como o cliente e o servidor XML-RPC funcionam para trocar informações.

XML-RPC é um conceito muito simples com um conjunto limitado de recursos. Essas limitações são, em muitos aspectos, o recurso mais atraente do XML-RPC, pois reduzem substancialmente a dificuldade de implementar o protocolo e testar sua interoperabilidade.

Embora XML-RPC seja simples, a aplicação criativa de ferramentas simples pode criar arquiteturas sofisticadas e poderosas. Nos casos em que uma ampla variedade de sistemas diferentes precisam se comunicar, XML-RPC pode ser o denominador comum mínimo mais apropriado.