Web service REST 

Introduzione

Il server XTEND mette a disposizione degli sviluppatori di applicazioni AJAX due tipi di web service REST che possono essere richiamati direttamente partendo dal browser web mediante una richiesta HTTP.

Questi servizi sono accessibili solo alle applicazioni XTEND.

Il motore considera solo le richieste REST che hanno una sessione XTEND associata per mezzo del cookie (oppure il parametro dell'URL) JSESSIONID.

I servizi REST XTEND sono disponibili solo sul server XTEND.

Essi 'incapsulano' la chiamata dei web service SOAP X3.

Le strutture dei dati REST scambiate per il passaggio dei parametri (chiave e dati) e la restituzione del risultato (dati e messaggi) sono identiche a quelle dei servizi SOAP.

Solo il protocollo di scambio con il client è diverso.

Richiamo sui web service SOAP X3

Questo paragrafo presenta in maniera generale i Web service SOAP X3 disponibili en anche le strutture di dati associati.

La conoscenza dei web service SOAP X3 è indispensabile per utilizzare i servizi REST di XTEND.

Parametri di chiamata

Parametri obbligatori
  • Il contesto di chiamata CAdxCallContext callContext
    Contiene le informazioni di login X3 e sul pool di connessione che elaborerà la richiesta
  • Il nome di pubblicazione del web service String publicName definito al momento della pubblicazione

public CAdxCallContext {
    //Codice lingua X3
    String codeLang;
    //Codice utente X3
    String codeUser;
    //Password X3
    String password;
    //Alias del pool di connessione sul server di web service
    String poolAlias;
    //Parametri di configurazione (query string)
    String requestConfig;
}

Il parametro adxwss.optreturn=JSON/XML della query string requestConfig indica il tipo di risultato (XML di default).

Il server di web service individua automaticamente il formato XML o JSON in input.

Opzioni JSON

Il formato JSON propone delle opzioni per filtrare i dati restituiti dal web service.

Le opzioni sono trasferite:

  • sia nella query string requestConfig mediante il parametro adxwss.optjson
    requestConfig=adxwss.optreturn=JSON&adxwss.optjson={"OPTIONS":"noGoups"}
  • che nei parametri JSON dell'oggetto o del sotto programma mediante il campo "_JSONOPT"
    Vedere esempio dei parametri di chiamata JSON

L'opzione JSON è un oggetto JSON che implica almeno uno dei campi qui in basso.
{
    OPTIONS:["nolabels","noclobs","nogroups","norows"],
    LANG:"ITA",
    EXCLUDEGRP:["GRP1","GRP2"],
    INCLUDEGRP:["GRP1","GRP2"],
    EXCLUDEFLD:["FLD1","FLD2"],
    INCLUDEFLD:["FLD1","FLD2"]
}

OPZIONI

noGroups
    Nessun gruppo di pubblicazione in restituzione
    Ogni parametro del sotto-programma o del campo dell'oggetto è un riquadro di String

noRows
    Nessuna riga nei riquadri con dim>1
    Ogni parametro del sotto-programma o dei campi dell'oggetto è un riquadro di String

noLabels
    Nessun titolo per i menù locali

noClobs
    I campi clob non sono restituiti

Il campo OPTION accetta sia un riquadro di parametri che un solo parametro (String)

EXCLUDEGRP
    Esclude i gruppi menzionati

INCLUDEGRP
    Include i gruppi contenuti menzionati

EXCLUDEFLD
    Esclude i campi menzionati

INCLUDEFLD
    Include i campi menzionati

I campi INCLUDE* e EXCLUDE* accettano sia un riquadro di String che una String

Parametri chiave dell'oggetto X3

Il parametro CAdxParamKeyValue objectKeys per i metodi degli oggetti X3 che necessitano delle chiavi (Read/Query...).

Si tratta del riquadro codiceCampo/valore.

public class CAdxParamKeyValue{
    private String key;
    private String value;
}

Parametri dati

Il parametro String objectXml per un oggetto X3 o String inputXml contiene i dati dell'oggetto o i parametri del sotto-programma in formato XML o JSON.

Il formato JSON è stato aggiunto per le esigenze delle applicazioni AJAX.

Esempio di formato della chiamata del web service di login AXTDLOGIN del sito ASAMPLE.

Param JSON

Opzione JSON nei parametri di chiamata: 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">ITA</FLD>
        </LIN>
    </TAB>
    <GRP ID="AXLOG_PAR">
        <FLD NAME="AXUSERCODE">DIS001</FLD>
        <FLD NAME="AXPWD">adonix</FLD>
    </GRP>
</PARAM>

Struttura parametro dati sotto-programma

I campi <FLD NAME="FieldName"> rappresentano i parametri del sotto-programma e sono collegati al gruppo di pubblicazione

I gruppi di pubblicazione sono definiti nella scheda Web service associata alla scheda del sotto-programma.

Sono rappresentati dai nodi <GRP ID="IdGroup"> per i parametri di dimensione 1 e <TAB ID="IdGroup"> per i parametri di dimensione > 1.

Il nodo <LIN> raggruppa i campi di uno stesso gruppo riquadro che ha lo stesso indice.

I parametri JSON riprendono la stessa struttura ma non si è obbligati ad utilizzare i gruppi di pubblicazione.

Sotto Programma XML

<PARAM>
    <GRP ID=’GRP1’>
        <FLD NAME=’CAMPO’>Valore</FLD>
    </GRP>
    <TAB ID=’GRP2’>
        <LIN>
            <FLD NAME=’CAMPO1’>Valore1</FLD>
            <FLD NAME=’CAMPO2’>Valore1</FLD>
        </LIN>
        <LIN>
            <FLD NAME=’CAMPO1’>Valore1</FLD>
            <FLD NAME=’CAMPO2’>Valore2</FLD>
        </LIN>
    </TAB>
</PARAM>

Sotto Programma JSON

/*--- Senza i gruppi ---*/
{
    CAMPO:"Valore",
    CAMPO1:["Valore1","Valore2"],
    CAMPO2:["Valore1","Valore2"]
}
/*---Con i gruppi ---*/
{
    GRP1:{
        CAMPO:"Valore"
    },   
    GRP2:[
        {
            CAMPO1:"Valore1",
            CAMPO2:"Valore1"          
        },
        {
            CAMPO1:"Valore2",
            CAMPO2:"Valore2"       
        }
    ]
}

Struttura parametro dati Oggetto X3

Stessa struttura del sotto-programma ma i nomi dei gruppi sono codificati in funzione della posizione del blocco nella videata.

In modalità JSON non è obbligatorio specificare i nomi dei gruppi.

Viene lasciata allo sviluppatore l'iniziativa di specificare il nome del gruppo, nel caso in cui desideri utilizzare un campo dell'oggetto X3, il cui solo nome non permette di identificarlo.

E' possibile avere più campi con lo stesso nome in un oggetto X3.

Esempi per l'ordine SOH
    SOH4_1 (righe dell'ordine) corrisponde al 1° blocco della 4° videata

Oggetto 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>

Oggetto JSON

{
    BPCORD:"DIS001",
    SOHTYP:"WEB",
    SALFCY:"ASN",
    STOFCY:"ASN",
    ITMREF:["CUB100","CD100"],
    ITMREF:["50","10"]
}

Servizi

/*--------------- Chiamata di un SOTTO-PROGRAMMA ---------------*/
public CAdxResultXml run(
    CAdxCallContext callContext,
    String publicName,
    String inputXml) throws Exception;
   
/*--------------- Chiamata di un sotto OGGETTO 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;
}

Risultato

La chiamata di un web service restituisce sempre un oggetto risultato CAdxResultXml che contiene:

  • i dati dell'oggetto o i parametri del sotto-programma in formato XML o JSON
    String resultXml
  • i messaggi applicativi di tipo errore, warning o informazione
    CAdxMessage messages
  • delle informazioni tecniche sull'esecuzione del sotto programma
    CAdxTechnicalInfos technicalInfos

Gli errori applicativi X3 non vengono inviati come eccezioni.

Il formato JSON ignora i parametri di tipo BLOB che contengono dati binari.

public class CAdxResultXml{
    public CAdxMessage[] messages;
    public String resultXml;
    public int status;
    public CAdxTechnicalInfos technicalInfos;
}
public class CAdxMessage {
    public String message;
    //"1":Informazione - "2":Warning - "3":Errore
    public String type;
}

Esempio di risultato in seguito alla chiamata del web service di login AXTDLOGIN del sito ASAMPLE.

Risultato JSON

Opzioni 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"]
}

Risultato 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 service REST XTEND

Principio di funzionamento

Ecco le varie fasi di elaborazione di una richiesta REST:

1. Ricevimento della richiesta HTTP dal servlet ajax del server XTEND

2. Ricerca della sessione XTEND associata

Mediante il cookie o il parametro della richiesta JSESSIONID
-> Errore se non è stata trovata nessuna sessione

3. Analisi dell'URL per ricavare le coordinate del sito XTEND ed il tipo di servizio

Più siti possono essere aperti simultaneamente da una sessione XTEND
-> Errore se sito non trovato

4. Esecuzione dello script server o chiamata del web service SOAP X3

Elaborazione dello script server

1. Lettura del percorso di accesso nella URL

2. Lettura e compilazione dello script JavaScript

3. Esecuzione dello script

      • Lo script ha la capacità di accedere ai dati della sessione e di richiamare i web service SOAP X3
      • L'istruzione print dello script è utilizzata per trasmettere la risposta (XML, JSON, HTML...)
Elaborazione della chiamata del web service SOAP X3

1. Lettura del codice dell'interfaccia XTEND nell'URL

L'interfaccia fa riferimento ad un web service SOAP
-> Errore se interfaccia non dichiarata nel sito

2. Costituzione dei parametri di chiamata

      • I dati XML o JSON sono letti nel corpo della richiesta
      • Le chiavi sono lette nella 'Query String'
      • Il tipo di risultato richiesto XML o JSON è letto nell'header HTTP xtd-accept

3. Costituzione del contesto di chiamata del web service SOAP

      • L'entry point (URL) è dato dal sito XTEND (Pool web service del sito o dell'interfaccia)
      • Il codice utente X3, Password e lingua sono dati dalla sessione XTEND

4. Chiamata del web service SOAP

5. Costituzione del risultato

      • I messaggi sono trasmessi nell'header HTTP
        xtd-msg-error, xtd-msg-warning,xtd-msg-info
      • I dati XML/JSON inviati dal web service SOAP sono trasmessi senza modifica nel corpo della richiesta

Formato dell'URL

http://host:port/xtend/ajax/x3sol/x3folder/xtdsite/type/id[/metodo][?Parametri]

Metodo HTTP POST o GET

x3sol
    Codice soluzione X3

x3folder
    Codice dossier X3

xtdsite
    Codice sito XTEND

type
    INT per la chiamata di una interfaccia XTEND
    SCRIPT per la chiamata di uno script server XTEND

id
    Codice dell'interfaccia
    o
    Percorso di accesso allo script in relazione alla directory degli script server del sito XTEND

metodo
    Codice del metodo dell'oggetto X3
    QUERY, R Read, S Save, M Modify,D Delete

Parametri
    Query string che può contenere:

    • I campi chiave di un oggetto X3
    • I parametri di una lista di selezione
    • Le opzioni JSON mediante la chiave _JSONOPT se non sono trasferite nei parametri dati
Esempi

Script
    http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/SCRIPT/ajaxTest1.js

Sotto-programma
    http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/AXTDLOGIN

Oggetto X3 - Read
    http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/R?FRMCOD=0901000002
    &_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D

Lista di selezione oggetto X3
    http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/QUERY?_COUNT=10&FRMCOD=09*
    &_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D

Invio dei dati

I parametri di tipo dati diversi da quelli della query string vengono trasferiti nel corpo della richiesta HTTP.

Il formato dei parametri di chiamata di una interfaccia XTEND sono forniti dal ContentType della richiesta HTTP:

  • application/json
    La struttura dei dati deve essere conforme al formato atteso
  • application/xml
    I dati XML devono essere conformi al formato atteso
  • application/x-www-form-urlencoded
    In questo caso si considera che l'elenco dei campi/valori constituisca un oggetto JSON conforme al formato atteso

Il ContentType di default è application/json.

Il formato dei dati per la chiamata di uno script server è obbligatoriamente application/json.

Risultato

Durante la chiamata di una interfaccia XTEND si può richiedere un formato di restituzione XML (application/xml) o JSON (application/json) valorizzando l'Header HTTP dedicato xtd-Accept.

Il mime-type di default è application/xml.

La richiesta restituisce i parametri del sotto-programma oppure i dati dell'oggetto X3 nel formato richiesto.

Il formato dei dati restituiti dalla chiamata di uno script server è libero.

Messaggi applicativi

I messaggi applicativi sono restituiti in tre header HTTP specifici.

xtd-msg-error

Contiene i messaggi di errore

xtd-msg-warning

Contiene i messaggi warning

xtd-msg-info

Contiene i messaggi di informazione

Un errore applicativo X3 viene trattato come un'eccezione

Eccezioni

Gli errori applicativi X3 e errori di compilazione/esecuzione degli script server sono restituiti sotto forma di un erroreHTTP di codice 600.

Le eccezioni JAVA sono rinviate sotto forma di un errore HTTP di codice 500.

Il corpo della richiesta contiene una descrizione (ContentType=text/plain) dell'errore che dipende dal tipo di eccezione.

Nel caso di un errore X3 l' header HTTP xtd-msg-error contiene i messaggi di errore