Ce service Web permet d'exécuter l'étape de merge de l'APE.

Format du message en entrée

Le format du message JSON en entrée est le suivant :

{
"jsonDataModel": {},
"locale": "string",
"mimeType": "string",
"namespace": "string",
"options": {},
"templateName": "string"
}

Lorsque le service Web s'exécute sans erreur, le code HTTP retourné est 200 et la réponse est un document XML (lors du traitement d'un template .ftlx).

En cas d'erreur, le code http retourné est soit 400 si le corps de la requête est incorrect, soit 500 lors d'une erreur dans le traitement du template. En cas d'erreur, la réponse retournée est de type JSON.

↑ Haut de page

Attributs

Le message doit représenter un objet JSON avec les attributs suivants :

templateName

Cet attribut est obligatoire et de type String. Il représente le nom du template (nom du fichier .ftlx). Cf. section "Template" dans "Apache FreeMarker Template Engine".

namespace

Cet attribut est optionnel et de type String. Il représente l'espace de noms utilisé pour la recherche du template par le moteur. Cf. section "Template loader" dans "Apache FreeMarker Template Engine".

jsonDataModel

Cet attribut est obligatoire et de type Objet. Il représente le data model qui sera utilisé par le moteur pour traiter le template. Cf. section "Data model" dans "Apache FreeMarker Template Engine.
Tableau de correspondances entre les types de données FreeMarker et les types de données JSON :

Type FreeMarker	Type JSON
String	String
Number	Number
Date	String ou Number suivant le type de transformation utilisé. Voir l'option jsonPathConv.
Time	String ou Number suivant le type de transformation utilisé. Voir l'option jsonPathConv.
Date-time	String ou Number suivant le type de transformation utilisé.Voir l'option jsonPathConv.
Boolean	Boolean
Hash	Objet
Sequence	Tableau

↑ Haut de page

locale

Cet attribut est optionnel et de type String. Il représente la locale utilisée pour rechercher et traiter le template par le moteur. Cf. section "Locale" dans "Apache FreeMarker Template Engine". Si cet attribut n'est pas spécifié, la locale par défaut de la JVM Java est utilisée. La chaîne alphanumérique représentant la locale doit être au format IETF BCP 47.

mimeType

Cet attribut est optionnel et de type String. Il représente le type MIME de la réponse du service Web.

FreeMarker est configuré pour renvoyer automatiquement un type MIME en fonction de l'extension du fichier du template exécuté :

.ftlx : réponse de type application/xml (charset=UTF-8)
.ftlh (template de document HTML) : réponse de type text/html (charset=UTF-8)
.ftlx (template de document XML) : réponse de type application/xml (charset=UTF-8)

Il n'est donc pas nécessaire de fixer une valeur pour cet attribut lors de l'exécution de templates .ftlx.

Dans le cadre d'une utilisation de ce service Web en dehors de l'APE (pour fusionner des données avec un template CSV par exemple), il est nécessaire de fixer une valeur à cet attribut ("text/csv" par exemple).

↑ Haut de page

options

Cet attribut est optionnel et de type Objet.

Il représente les paramètres supplémentaires à prendre en compte lors du traitement du template.

L'ensemble des options sont décrites dans un objet JSON dont chaque membre décrit une option, à savoir :

extOutputTransform
Option de formatage du document résultat (type JSON String)
jsonPathConv
Option de conversion de données du modèle de données avant traitement de celui-ci par le template (type JSON tableau d'Objet)
jsonGenerator
Option de production d'un modèle de données factice utilisé en lieu et place du data model lors de la phase de mise en développement du template (type JSON Objet).

↑ Haut de page

En-têtes

Il est possible d'ajouter certains en-têtes dans la requête HTTP déclenchant ce service Web. Ces en-têtes sont considérés comme des paramètres supplémentaires en entrée ou entrée/sortie  :

Nom

Type

Description

Ape-Template-Url

Entrée/Sortie

Lorsqu'il est présent dans la requête, il est retourné dans la réponse avec pour valeur l'URI du fichier template exécuté pour produire le document.

La syntaxe de l'URI dépend de la nature du chargeur de template (clé template_loader dans freemarker.properties) qui a chargé le template :

si FileTemplateLoader : la syntaxe de l'URI est file:/<URL du template>,
si ClassTemplateLoader : la syntaxe de l'URI est jar:file:/<URL du fichier jar contenant le template>!/<Chemin du template à l'intérieur du jar>,
si ZipFileTemplateLoader : la syntaxe de l'URI est jar:file:///<URL du fichier zip contenant le template>!/<Chemin du template à l'intérieur du zip>.

Remarques :

Les caractères non ASCII de l'URI sont encodés en suivant la RFC 2396 (par exemple, un espace est remplacé par la chaîne %20; le caractère é est remplacé par la chaîne %C3%A9. La fonction de la VatoolBx VaToolBxJavaDecodeURL permet de décoder l'URI.
Si le template demandé est localisé, l'URI du fichier pointera vers celui correspondant à la locale demandée. Par exemple, si le paramètre "templateName" du message JSON est "foo.ftlx" et que le paramètre "locale" est "it", s'il existe un fichier "foo_it.ftlx", l'URI pointera vers ce fichier (sinon elle pointera vers le fichier "foo.ftlx").
En cas d'erreur, la chaîne alphanumérique retournée est vide.

Ape-Template-Loader

Entrée/Sortie

Description au format JSON du chargeur de template ayant chargé le template. L'objet JSON a plusieurs propriétés qui dépendent de la nature du chargeur de template :

si FileTemplateLoader :

{
 "classname":"com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader", 
"baseDir":"file:/<URL absolue du paramètre baseDir présent dans la clé template_loader>", 
"disableCanonicalPathCheck":<true ou false : valeur du paramètre disableCanonicalPathCheck présent dans la clé template_loader> 
}

Les caractères non ACSII de la propriété baseDir sont encodés en suivant la RFC 2396 (voir plus haut).

si ClassTemplateLoader :

{ 
"classname":"com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader", 
"resourceLoaderClass":"<valeur du paramètre resourceLoaderClass présent dans la clé template_loader>", 
"basePackagePath":"<valeur du paramètre basePackagePath présent dans la clé template_loader>" 
}

si ZipFileTemplateLoader :

{ 
"classname":"com.hardis.adelia.mergedocengine.freemarker.conf.ZipFileTemplateLoader",
"schemeFileURI":"<valeur du paramètre schemeFileURI présent dans la clé template_loader>", 
"basePackagePath":"<valeur du paramètre basePackagePath présent dans la clé template_loader>", 
"useCache":<true ou false : valeur du paramètre useCache présent dans la clé template_loader> 
}

Les caractères non ASCII des propriétés schemeFileURI et basePackagePath sont encodés en suivant la RFC 2396 (voir plus haut).

Remarque : en cas d'erreur, la valeur JSON retournée est la valeur "null".

↑ Haut de page