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 du script, comme c'est le cas pour les évaluations de scripts via l'action script. Dans le cas d'un appel rest, les paramètres passés au script sont les paramètres d'URL.

La variable $$$ est spécifique au servlet rest et contient deux propriétés:

• $$$.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))
• $$$.payload contient le payload lorsque la requête rest envoie des données brutes à la place d'un formulaire.

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

{
    "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"
    }
}

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.

Paramètres du servlet

Il est possible de spécifier les paramètres suivants lors de la déclaration du servlet dans le fichier web.xml:

file-limit-max-bytes

Taille maximale des fichiers envoyés via le servlet, en bytes. La valeur par défaut est 10485760 (10 Mo).

file-limit-size-mode

Mode de contrôle de la taille de fichier. Deux modes sont supportés:

default

Dans ce mode, le contrôle de taille est effectué en amont: le moteur alloue une taille de buffer max, charge le fichier, et génère une erreur si le volume de données à charger dépasse du buffer alloué.

afterwards

Dans ce mode, le contrôle de taille est effectué après le téléchargement. Ce mode est censé résoudre un problème qui peut arriver avec tomcat lorsque l'on upload depuis certains navigateurs et qui empêche d'afficher l'alerte de dépassement

L'image ci-dessus illustre le cas d'erreur qui peut se produire. Le browser envoie le fichier à Ewt. Ce dernier commence à traiter la requête et le gestionnaire de multipart génère une exception dès que le file-limit-max-bytes est dépassé. Ewt répond alors un message d'erreur, sauf qu'entre temps le browser continue d'envoyer des données. Le serveur d'application accepte encore du data dans la limite du maxSwallowSize (c'est un paramètre de tomcat). Une fois cette limite dépassée, tomcat retourne un CONNECTION_RESET et en voyant ça, le browser décide de renvoyer les datas non encore acknowledgées. Au final le browser affiche une erreur CONNECTION_RESET une fois que tout le payload a pu être envoyé. L'utilisateur final reçoit donc une erreur technique à la place du message d'erreur généré par Ewt.