SOAP DECLARATION

O comando SOAP DECLARATION permite declarar explicitamente o tipo dos parâmetros utilizados em um método 4D publicado como serviço web.

Quando for publicado um método como serviço web, os parâmetros padrão $0, $1... $n são utilizados para descrever os parâmetros do serviço web ao mundo exterior (mais particularmente no arquivo WSDL). O protocolo SOAP necessita que os parâmetros sejam nomeados explicitamente; 4D utiliza como padrão os nomes “FourD_arg0, FourD_arg1 ... FourD_argn”.

Este funcionamento como padrão pode ser problemático pelas seguintes razões:

• Não é possível declarar $0 ou $1, $2, etc. como um array. Portanto, é necessário utilizar ponteiros; entretanto, neste caso, é necessário conhecer o tipo dos valores para a geração do arquivo WSDL.
• Depois, pode ser útil ou necessário personalizar os nomes dos parâmetros (entrada e saída).
• Pode utilizar parâmetros como as estruturas XML e referências DOM.
• Também pode ser necessário devolver os valores de um tamanho superior a 32 KB (limite dos argumentos de tipo Texto em banco de dados que estão em modo não-Unicode).
• Finalmente, este funcionamento torna impossível devolver mais de um valor por chamada RPC (em $0).

Nota: Mesmo quando esse comando for usado, é necessário declarar as variáveis 4D e arrays no método Compiler_Web utilizando os comandos do tema “Compilador”.

Em variavel, passe a variável 4D a referenciar quando chame ao serviço web.

Aviso: Pode referenciar apenas as variáveis processo ou os argumentos dos métodos 4D ($0 a $n). As variáveis locais e interprocesso não podem ser utilizados.

Como padrão, como apenas podem ser utilizados os argumento de tipo texto, as respostas do servidor SOAP estão limitadas a 32 KB. Entretanto, é possível devolver argumentos SOAP com um tamanho maior a 32 KB, utilizando BLOBs. Para exceder este limite, simplesmente necessita declarar os argumentos como BLOBs antes de chamar ao comando SOAP DECLARATION (ver exemplo 4).

Nota: Do lado do cliente, se assina este tipo de serviço web com 4D, o assistente de serviços web gerará naturalmente uma variável de tipo Texto no método proxy. Para poder utilizá-la, apenas necessita digitar novamente esta variável como um BLOB no método proxy.

Pode declarar as variáveis de tipo "estrutura XML" e "DOM reference", de entrada e saída, através das constantes Is XML e Is DOM reference. Quando os parâmetros deste tipo são definidos, não se aplica nenhum processo nem codificação e os dados são transmitidos "tal qual" (ver exemplo 5).

• Parâmetros de saída
• • Is XML  indica que o parâmetro contém uma estrutura XML,
  • Is DOM reference indica que o parâmetro contém a referência DOM de uma estrutura XML. Neste caso, a inserção da estrutura XML na mensagem SOAP é equivalente a executar o comando DOM EXPORT TO VAR.

Nota: No caso das referências DOM utilizadas como parâmetros de saída, se recomenda utilizar as referências globais, criadas, por exemplo, ao início ou ao fechamento da aplicação. De fato, uma referência DOM criada dentro do mesmo serviço web não pode ser fechada com DOM CLOSE XML, do contrário o serviço web não devolve nada. As chamadas múltiplas ao serviço web implicam portanto a criação de múltiplas referências DOM não fechadas, as quais podem provocar uma saturação da memória.

• Parâmetros de entrada
• • Is XML indica que o parâmetro deve receber um argumento XML enviado pelo cliente SOAP.
  • Is DOM reference indica que o parâmetro deve receber a referência DOM de uma estrutura XML correspondente ao argumento XML enviado pelo cliente SOAP. 

• Modificação do WSDL As estruturas XML serão declaradas por 4D como "anyType" (tipo indeterminado) no WSDL. Se desejar dar um tipo preciso a  estrutura XML, deve guardar o arquivo WSDL e adicionar manualmente o esquema de dados que deseja na seção <types> do WSDL.

Os argumentos SOAP entrantes referenciados com a ajuda de variáveis 4D (e não pelos argumentos de métodos 4D) devem ser declarados primeiro no método de projeto COMPILER_WEB. De fato, o uso de variáveis de processo nos métodos Web Services necessitam ser declaradas antes da chamada ao método. Se chama o método de projeto COMPILER_WEB, se existir, para cada petição SOAP aceitada. Como padrão, o método COMPILER_WEB não existe. Você deve criá-lo especificamente.

Note que o método COMPILER_WEB também é chamado pelo servidor web de 4D durante a recepção de petições web “convencionais” de tipo POST (ver a seção Ações URL e Formulário).

Em apelido, passe o nome do argumento que deve aparecer em WSDL e nos intercâmbios SOAP.

Aviso: este nome deve ser único na chamada RPC (parâmetros de entrada e saída), do contrário, apenas a última declaração será levada em consideração por 4D.

Nota: os nomes dos argumentos não devem começar por um número nem conter espaços. Além disso, para evitar riscos de incompatibilidade, é recomendado não utilizar caracteres estendidos (como caracteres acentuados).
Se for omitido o parâmetro apelido, 4D utilizará, como padrão, o nome da variável ou FourD_argN para os argumentos dos métodos 4D ($0 a $n).

Nota: o comando SOAP DECLARATION deve estar incluído no método publicado como serviço web. Não é possível chamá-lo desde outro método.

Este exemplo especifica um nome de parâmetro:

Este exemplo é utilizado para recuperar um array de códigos postais na forma de inteiros longos:

Este exemplo se utiliza para referenciar dois valores devolvidos sem especificar um nome de argumento:

Este exemplo permite ao servidor 4D SOAP devolver um argumento de um tamanho maior a 32 KB:

Note o tipo Is Text (e não Is BLOB). Isso permite que o argumento seja processado corretamente.

Este exemplo illustra os resultados dos diferentes tipos de declarações: