Web services REST
Introdução
O servidor XTEND coloca à disposição dos programadores de aplicações AJAX dois tipos de web services REST que podem ser invocados diretamente a partir do navegador web por um pedido HTTP.
- Chamada de um web service SOAP X3 via um interface XTEND.
- Chamada de um script serveur
Estes serviços não estão acessíveis que às aplicações XTEND.
O motor não toma em conta que os pedidos REST que têm uma sessão XTEND assoicado via o cookie (ou para o parâmetro de URL) JSESSIONID.
Os serviços REST XTEND não estão disponíveis que sobre o servidor XTEND
Eles "encapsulam" a chamada dos web services SOAP X3
As estruturas dos dados REST trocadas pela passagem dos parâmetros (chaves e dados) e a devolução do resultado (dados e mensagens) são idênticos aquela dos serviços SOAP.
Apenas o protocolo de troca com o cliente é diferente.
Lembrança sobre os web services SOAP X3
Este parágrafo apresenta de maneira geral os Web services SOAP X3 disponíveis assim que a estrutura de dados associados.
O conhecimento dos web service SOAP X3 está indispensável para utilizar os serviços REST de XTEND.
Parâmetros de chamada
Parâmetros obrigatórios
- O contexto de chamada CAdxCallContext callContext
Contém as informações de login X3 e sobre a pool de conexão que vai tratar o pedido - O nome de publicação do web service String publicName definido no momento da publicação
public CAdxCallContext {
//Código língua X3
String codeLang;
//Código utilizador X3
String codeUser;
//Palavra chave X3
String password;
//Alias da "pool" de conexão sobre o servidor de web services
String poolAlias;
//Parâmetros de configuração (query string)
String requestConfig;
}
Os parâmetros adxwss.optreturn=JSON/XML da query string requestConfig indica o tipo de resultado (XML por defeito).
O servidor de web service detecta automáticamente o formato XML ou JSON em entrada.
Opções JSON
O formato JSON propõe as opções para filtrar os dados reenviados pelo web service.
As opções são passadas :
- seja na query string requestConfig via o parâmertro adxwss.optjson
requestConfig=adxwss.optreturn=JSON&adxwss.optjson={"OPTIONS":"noGoups"} - seja nos parâmetros JSON de objeto ou do sub-programa via o campo "_JSONOPT"
Ver exemplo de parâmetros de chamada JSON
A opção JSON é um objeto JSON que comporta pelo menos um dos campos a seguir.
{
OPÇÕES:["nolabels","noclobs","nogroups","norows"],
LANG:"FRA",
EXCLUDEGRP:["GRP1","GRP2"],
INCLUDEGRP:["GRP1","GRP2"],
EXCLUDEFLD:["FLD1","FLD2"],
INCLUDEFLD:["FLD1","FLD2"]
}
OPÇÕES
noGroups
Sem grupos de publicação em retorno
Cada parâmetro do sub-programa ou campo de objeto é um quadro de String.
noRows
Sem linhas no quadros com dim>1
Cada parâmetro do sub-programa ou campo do objeto é um quadro de String
noLabels
Sem labels para os menus locais
noClobs
Os campos clob não são reenviados
O campo OPÇÃO aceita seja um quadro de parâmetro seja um único parâmetro (String)
EXCLUDEGRP
Exclui os grupos mencionados
INCLUDEGRP
Inclui os grupos contidos mencionados
EXCLUDEFLD
Exclui os campos mencionados
INCLUDEFLD
Inclui os campos mencionados
Os campos INCLUDE* e EXCLUDE* aceitam seja um quadro de Strings seja uma String
Parâmetros chave de objeto X3
O parâmetro CAdxParamKeyValue objectKeys para os métodos dos objetos X3 que necessitam das chaves (Read/Query...).
Trata-se de um quadro codeChamp/valeur.
public class CAdxParamKeyValue{
private String key;
private String value;
}
Parâmetros dados
O parâmetro String objectXml para um objeto X3 ou String inputXml contém os dados de objeto ou os parâmetros do sub-programa ao formato XML ou JSON.
O formato JSON foi acrescentado para as necessidades das aplicações AJAX.
Exemplo de formato de chamada do web service de login AXTDLOGIN do estabelecimento ASAMPLE.
Param JSON
Opção JSON nos parâmetros de chamada : nogroups, norows
{
_JSONOPT:{OPTIONS:["nogroups", "norows"]},
AXPARCOD:["SITCOD", "USRLANG"],
AXPARVAL:["FDBTEST", "FRA"],
AXUSERCODE:"DIS001",
AXPWD:"adonix"
}
Param XML
<PARAM>
<TAB ID="AX_PAR">
<LIN NUM="1">
<FLD NAME="AXPARCOD">SITCOD</FLD>
<FLD NAME="AXPARVAL">FDBTEST</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AXPARCOD">USRLANG</FLD>
<FLD NAME="AXPARVAL">FRA</FLD>
</LIN>
</TAB>
<GRP ID="AXLOG_PAR">
<FLD NAME="AXUSERCODE">DIS001</FLD>
<FLD NAME="AXPWD">adonix</FLD>
</GRP>
</PARAM>
Estrutura parâmetro dados sub-programa
Os campos <FLD NAME="FieldName"> representam os parãmetros do sub-programa e seu anexamento ao grupo de publicação.
Os grupod de publicações são definidas na ficha Web service associado à ficha do sub-programa.
São representados pelos nós <GRP ID="IdGroup"> para os parâmetros de dimensão 1 e <TAB ID="IdGroup"> para os parâmetros de dimenção > 1.
Os nós <LIN> reagrupa os campos de um mesmo grupo quadro tendo o mesmo índice.
Os parâmetrosJSON retoma a mesma estrutura mas não é obrigado de utilizar os grupos de publicação
Sub Programa XML
<PARAM>
<GRP ID=’GRP1’>
<FLD NAME=’CHAMP’>Valeur</FLD>
</GRP>
<TAB ID=’GRP2’>
<LIN>
<FLD NAME=’CHAMP1’>Valeur1</FLD>
<FLD NAME=’CHAMP2’>Valeur1</FLD>
</LIN>
<LIN>
<FLD NAME=’CHAMP1’>Valeur1</FLD>
<FLD NAME=’CHAMP2’>Valeur2</FLD>
</LIN>
</TAB>
</PARAM>
Sub Programa JSON
/*--- Sem os grupos ---*/
{
CHAMP:"Valeur",
CHAMP1:["Valeur1","Valeur2"],
CHAMP2:["Valeur1","Valeur2"]
}
/*--- Com os grupos ---*/
{
GRP1:{
CHAMP:"Valeur"
},
GRP2:[
{
CHAMP1:"Valeur1",
CHAMP2:"Valeur1"
},
{
CHAMP1:"Valeur2",
CHAMP2:"Valeur2"
}
]
}
Estrutura parãemetro dados Objeto X3
Mesma estrutura que os sub-programas mas os nomes de grupos são codificados em função do local do bloco no ecrã.
Em modo JSON não está obrigatório de especificar os nomes dos grupos.
É deixado ao programador a iniciativa de especificar o nome de umgrupo no caso onde se deseja utilizar um campo de objeto X3 cujo nome apenas não permite de identificar
Pode ter vários campos de mesmo nome num objeto X3
Exemplo para a encomenda SOH
SOH4_1 (linhas da encomenda) corresponde ao 1º bloco do 4º ecrã
Objeto XML
<PARAM>
<GRP ID="SOH0_1">
<FLD NAME="BPCORD">DIS001</FLD>
<FLD NAME="SOHTYP">WEB</FLD>
<FLD NAME="SALFCY">ASN</FLD>
</GRP>
<GRP ID="SOH2_1">
<FLD NAME="STOFCY">ASN</FLD>
</GRP>
<TAB ID="SOH4_1">
<LIN>
<FLD NAME="ITMREF">CUB100</FLD>
<FLD NAME="QTY">50</FLD>
</LIN>
<LIN>
<FLD NAME="ITMREF">CD100</FLD>
<FLD NAME="QTY">10</FLD>
</LIN>
</TAB>
</PARAM>
Objeto JSON
{
BPCORD:"DIS001",
SOHTYP:"WEB",
SALFCY:"ASN",
STOFCY:"ASN",
ITMREF:["CUB100","CD100"],
ITMREF:["50","10"]
}
Serviços
/*--------------- Chamada de um SUB-PROGRAMA ---------------*/
public CAdxResultXml run(
CAdxCallContext callContext,
String publicName,
String inputXml) throws Exception;
/*--------------- Chamada de um SUB-OBJET X3---------------*/
public CAdxResultXml save(
CAdxCallContext callContext,
String publicName,
String objectXml) throws Exception;
//------------------------------------------
public CAdxResultXml delete(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml read(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml query(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys,
int listSize) throws Exception;
//------------------------------------------
public CAdxResultXml modify(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys,
String objectXml) throws Exception;
//------------------------------------------
public CAdxResultXml actionObject(
CAdxCallContext callContext,
String publicName,
String actionCode,
CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml actionObject(
CAdxCallContext callContext,
String publicName,
String actionCode
String objectXml) throws Exception;
}
Resultado
A chamada d um web service reenvia sempre um objeto resultado CAdxResultXml que contém :
- os dados de objeto ou parâmetros do sub-programa ao formato XML ou JSON
String resultXml - as mensagens aplicação de tipo erro, aviso ou informação
CAdxMessage messages - informações técnicas sobre a execução do sub-programa
CAdxTechnicalInfos technicalInfos
Os erros aplicativos X3 não são reenviados como excepções.
O formato JSON ignora os parâmetros de tipo BLOB que contêm binário
public class CAdxResultXml{
public CAdxMessage[] messages;
public String resultXml;
public int status;
public CAdxTechnicalInfos technicalInfos;
}
public class CAdxMessage {
public String message;
//"1":Information - "2":Warning - "3":Erro
public String type;
}
Exemplo de resultado seguinte à chamada do web service de login AXTDLOGIN do estabelecimento ASAMPLE.
Resultado JSON
Opções JSON norows e nogroups
{
AXPARCOD:["SITCOD","USRLANG"],
AXPARVAL:["FDBTEST","FRA"]
AXUSERCODE:"DIS001",
AXPWD:"adonix",
AXUSERPROF:"B2B",
AX3SOL:["SOLPAIE","X3V5","XTENDV2"],
AX3FLDR:["PAIE","X3TESTV5","DEMOFRA"],
AX3LANG:["FRA","FRA","FRA"],
AX3USER:["XTEND","JPJ1","OG"],
AXLOGCOD:["NAME","FIRSTNAME","EMAIL","PHONE"],
AXLOGVAL:["DALBO","Frédéric","../FCT/mailto:fdb@sg.com","0001020304"]
SHIPADR1:["Sage Lyon new","Sage MGE","Sage PARIS"],
SHIPCITY:["LYON","Echirolles","PARIS"],
SHIPZIP:["69443","38130","75834"]
}
Resultado XML
<RESULT>
<TAB DIM="20" ID="AX_PAR" SIZE="2">
<LIN NUM="1">
<FLD NAME="AXPARCOD" TYPE="Char">SITCOD</FLD>
<FLD NAME="AXPARVAL" TYPE="Char">FDBTEST</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AXPARCOD" TYPE="Char">USRLANG</FLD>
<FLD NAME="AXPARVAL" TYPE="Char">FRA</FLD>
</LIN>
</TAB>
<GRP ID="AXLOG_PAR">
<FLD NAME="AXUSERCODE" TYPE="Char">DIS001</FLD>
<FLD NAME="AXPWD" TYPE="Char">adonix</FLD>
<FLD NAME="AXUSERPROF" TYPE="Char">B2B</FLD>
</GRP>
<TAB DIM="10" ID="AXLOG_X3" SIZE="3">
<LIN NUM="1">
<FLD NAME="AX3SOL" TYPE="Char">SOLPAIE</FLD>
<FLD NAME="AX3FLDR" TYPE="Char">PAIE</FLD>
<FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
<FLD NAME="AX3USER" TYPE="Char">XTEND</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AX3SOL" TYPE="Char">X3V5</FLD>
<FLD NAME="AX3FLDR" TYPE="Char">X3TESTV5</FLD>
<FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
<FLD NAME="AX3USER" TYPE="Char">JPJ1</FLD>
</LIN>
<LIN NUM="3">
<FLD NAME="AX3SOL" TYPE="Char">XTENDV2</FLD>
<FLD NAME="AX3FLDR" TYPE="Char">DEMOFRA</FLD>
<FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
<FLD NAME="AX3USER" TYPE="Char">OG</FLD>
</LIN>
</TAB>
<TAB DIM="50" ID="AXLOG_RES" SIZE="4">
<LIN NUM="1">
<FLD NAME="AXLOGCOD" TYPE="Char">NAME</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">DALBO</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AXLOGCOD" TYPE="Char">FIRSTNAME</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">Frédéric</FLD>
</LIN>
<LIN NUM="3">
<FLD NAME="AXLOGCOD" TYPE="Char">EMAIL</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">fdb@sg.com</FLD>
</LIN>
<LIN NUM="4">
<FLD NAME="AXLOGCOD" TYPE="Char">PHONE</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">0001020304</FLD>
</LIN>
</TAB>
<TAB DIM="20" ID="LOGINSHIP" SIZE="3">
<LIN NUM="1">
<FLD NAME="SHIPADR1" TYPE="Char">Sage Lyon new</FLD>
<FLD NAME="SHIPCITY" TYPE="Char">LYON</FLD>
<FLD NAME="SHIPZIP" TYPE="Char">69443</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="SHIPADR1" TYPE="Char">Sage MGE</FLD>
<FLD NAME="SHIPCITY" TYPE="Char">Echirolles</FLD>
<FLD NAME="SHIPZIP" TYPE="Char">38130</FLD>
</LIN>
<LIN NUM="3">
<FLD NAME="SHIPADR1" TYPE="Char">Sage PARIS</FLD>
<FLD NAME="SHIPCITY" TYPE="Char">PARIS</FLD>
<FLD NAME="SHIPZIP" TYPE="Char">75834</FLD>
</LIN>
</TAB>
</RESULT>
Web services REST XTEND
Princípio de funcionamemento
Eis as diferentes etapas de tratamento de um pedido REST:
1. Receção do pedido HTTP por servlet ajax do servidor XTEND
2. Pesquisa da sessão XTEND associado.
Via o cookie ou o parâmetro do pedido JSESSIONID
-> Erro se nenhuma sessão não foi encontrada
3. Análise de URL para deduzir as coordenadas do estabelecimeto XTEND e o tipo de serviço
Vários estabelecimentos podem ser abertos simultâniamente por uma sessão XTEND
-> Erro se estabelecimento não encontrado
4. Execução do script servidor ou chamada do web service SOAP X3
Tratamento do script servidor
1. Leitura do caminho de acesso na URL
2. Leitura e compilação do script JavaScript
3. Execução do script
- O script tem a capacidade de aceder aos dados da sessão e de chamar os web services SOAP X3
- A instrução print do script está utilizado para reenviar a resposta (XML, JSON, HTML...)
Tratamento da chamada do web service SOAP X3
1. Leitura do codigo de interface XTEND em URL.
O interface faz referência a um web service SOAP
-> Erro se interface não declarado no estabelecimento.
2. Constituição dos parâmetros de chamada.
- Os dados XML ou JSON são lidos no corpo do pedido.
- As chaves são lidas na "Query String"
- O tipo de resultado pede XML ou JSON é lido no "header" HTTP xtd-accept
3. Constituição do contexto de chamada do web service SOAP
- O ponto de entrada (URL) está dado pelo estabelecimento XTEND (Pool web service ou da interface)
- O código utilizador X3, Expressão de passe em língua são dados pela sessão XTEND
4. Chamada do web service SOAP
5. Constituição do resultado
- As mensagens transmitiram no cabeçalho HTTP
xtd-msg-error, xtd-msg-warning,xtd-msg-info - Os dados XML/JSON reenviadas pelo web service SOAP são transmitidos sem modificação no corpo do pedido.
Formato de URL
http://host:port/xtend/ajax/x3sol/x3folder/xtdsite/type/id[/méthode][?Paramètres]
Método HTTP POST ou GET
x3sol
Código solução X3
x3folder
Código dossier X3
xtdsite
Código estabelecimento XTEND
type
INT para uma chamada de uma interface XTEND
SCRIPT para chamada de um script server XTEND
id
Código de interface
ou
Caminho de acesso do script por relação ao directório dos scripts do servidor do estabelecimento XTEND.
método
Código do método de objecto X3
QUERY, R Read, S Save, M Modify,D Delete
Parâmetros
Query string que pode conter :
- Os campos chaves de um objeto X3
- Os parâmetros de uma lista esquerda
- As opções JSON via a chave _JSONOPT se eles não sao passados nos parâmetros dados.
Exemples:
Script
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/SCRIPT/ajaxTest1.js
Sub-programa
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/AXTDLOGIN
Objeto X3 - Read
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/R?FRMCOD=0901000002
&_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D
Lista esquerda objeto X3
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/QUERY?_COUNT=10&FRMCOD=09*
&_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D
Envia os dados
Os parâametros de tipo dados outro que aqueles da query string são passadas no corpo do pedido HTTP.
O formato dos parâmetros de chamada de uma interface XTEND são dados para o ContentType do pedido HTTP:
- aplicação/json
A estrutura dos dados deve ser conforme aos formato esperado - application/xml
Os dados XML devem estar conforme aos formatos esperados - application/x-www-form-urlencoded
Neste caso considera-se que a lista dos campos/valores constitui um objeto JSON conforme ao formato esperado
O ContentType por defeito está application/json.
O formato dos dados para uma chamada de um script server está obrigatoriamente application/json.
Resultado
No momento de chamada de uma interface XTEND pode-se pedir um formato de devolução XML (application/xml) ou JSON (application/json) em valorizando o cabeçalho HTTP dedicado xtd-Accept.
O mesmo tipo por defeito é application/xml.
O pedido reenvia os parâmetros do sub-programa ou os dados do objecto X3 ao formato pedido.
O formato dos dados reenviado por chamada de um script está livre.
Mensagens aplicativas
As mensagens aplicativas são reenviadas nos três cabeçalhos HTTP específicos.
xtd-msg-error
Contém as mensagens de erro
xtd-msg-warning
Contem as mensagens de aviso (warning)
xtd-msg-info
Contém as mensagens de informação
Um erro aplicativo X3 está tratado como uma exceção.
Exceções
Os erros aplicativos X3 e erros de compilação/execução dos scripts serveur são reenviados sob a forma de um erroHTTP de código 600.
As exceções JAVA são reenviadas sob a forma de um erro HTTP de código 500.
O corpo do pedido contém uma descrição (ContentType=texto/pleno) de erro que depende do tipo de exceção.
No caso de um erro X3 o cabeçalho HTTP xtd-msg-error contém as mesagens de erro.