Endpoint /rest

La classe EwtRestServlet est habituellement mappée sur l'url-pattern /rest. La classe permet d'évaluer un script directement. Elle supporte les requêtes GET et POST et un payload de différentes formes:

• formulaire url-encoded
• formulaire multipart
• données brutes

Le servlet s'attend à trouver le nom de l'application et le nom du script à exécuter dans l'URL, par exemple:

/rest/sample/monscript?param1=foo&param2=bar

Dans l'exemple ci-dessus, on exécute le script monscript de l'application sample et on passe les paramètres param1 et param2 au script. Ces deux paramètres seront disponibles pour le script via la variable $$.

Le servlet reconnaît en outre deux headers (ils sont optionnels):

• x-ewt-sessionid : Ce header permet de passer l'identifiant de session; lorsque ce header est défini, cela permet au serveur de lier la requête à une session client. Cela permet d'obtenir d'utiliser des fonctionnalités liées aux dossiers ouverts, etc.
• x-ewt-context : Ce header permet de spécifier un contexte, c'est-à-dire la référence à un dossier, un tuple ou un champ sur lequel le script pourra travailler.

La variable $$ donne la liste des paramètres d'entrée et des champs de formulaires reçus:

• $$.params contient les paramètres d'URL et leur valeur
• $$.inputs contient les champs de formulaire et leur valeur, ainsi que les paramètres d'URL et leur valeur. En effet, les paramètres se retrouvent également au niveau des inputs car java ne fait pas de distinction entre les deux (cf. "For HTTP servlets, parameters are contained in the query string or posted form data.", https://docs.oracle.com/javaee/6/api/javax/servlet/ServletRequest.html#getParameter(java.lang.String))

⚠️ Attention, Ewt peut être amené à modifier les noms de certains paramètres et/ou de certains champs, notamment dans les cas suivants:

• Les paramètres ou champs dont le nom contient un "-" sont "camelisés", c'-à-d. que le "-" est supprimé et le caractère suivant est mis en majuscules. Ainsi, un paramètre my-param deviendra myParam. Pour rappel, les noms de variables sont censés ne contenir que des caractères alphanumériques ou le _.
• Les paramètres ou champs dont le nom commencent par un chiffre sont préfixés avec le caractère _.
• Le servlet supporte les champs homonymes au niveau du formulaire multipart. Toutefois les paramètres ou champs contenant un index, par exemple file[0], file[1] sont repris dans un seul paramètre file. Ce dernier sera alors un tableau de valeurs.

Exemple de contenu de la variable $$ (ici mise en forme en json):

{
    "contentType": "multipart/form-data; boundary=X-INSOMNIA-BOUNDARY",
    "contentTypeEx": "multipart/form-data",
    "method": "POST",
    "workdir": "C:/apps/apache-tomcat-9.0.64/work/Catalina/localhost/ewt/649a46e7-cdde-4ec6-9622-39265881a235",
    "payload": null,
    "inputs": {
        "field1": "1é2",
        "field2": "C:/apps/apache-tomcat-9.0.64/work/Catalina/localhost/ewt/649a46e7-cdde-4ec6-9622-39265881a235/sample.docx",
        "field3": "I'm 👍🏽.",
        "file": [
          <file1>,
          <file2>
        ],
        "other-field": "test"
    },
    "params": {
        "param1": "1é3",
        "param2": "f👍🏽o"
    }
}

Dans l'exemple ci-dessus, les éléments <file1> et <file2> désignent des fichiers.

Charset des formulaires multiparts

Les formulaires multiparts peuvent contenir des données binaires et/ou textuelles. Il n'existe pas de réelle convention concernant l'encoding des formulaires multipart : ils étaient majoritairement encodés en iso-8859-1, mais la tendance est à les encoder en utf-8 depuis quelques temps, notamment avec l'introduction de HTML5.

Ewt prévoit trois façons de traiter l'encoding des formulaires multipart:

1. Faire en sorte que la requête envoyée à Ewt utilise UTF-8 pour l'encodage des valeurs, mais également des noms de fichiers passés en headers du multipart.

2. Spécifier le charset par défaut auquel le servlet devra s'attendre.

   Cela consiste à spécifier le paramètre d'initialisation suivant au niveau du fichier web.xml. Dans ce cas ci-dessous, on indique que le servlet doit toujours s'attendre à recevoir des valeurs en iso-8859-1.

   <servlet>
     <servlet-name>EwtRestServlet</servlet-name>
     <servlet-class>ch.epilogic.ewt.servlets.EwtRestServlet</servlet-class>
     <init-param>
       <param-name>default-charset</param-name>
       <param-value>iso-8859-1</param-value>
     </init-param>
   </servlet>
   

3. Faire en sorte que l'appelant spécifie l'encoding qu'il utilise. Cela peut se faire de deux façons:

   1. Au moyen d'un paramètre d'URL _encoding_
   2. Au moyen d'un champ de formulaire nommé _encoding_

   Cette option s'inspire de la fonctionnalité mise en place dans certains navigateurs (dont Chrome et Firefox) pour permettre de spécifier le charset utilisé dans les formulaires multipart. En effet, si un formulaire HTML contient un champ caché de la forme suivante:

   <input type="hidden" name="_encoding_" value=""/>
   

   Le navigateur alimentera sa valeur avec le nom du charset utilisé. Ewt étend la fonctionnalité en autorisant ce champ à figurer en tant que paramètre d'URL.