|
VADELIA |
|
|
EADELIA |
(B) (C) |
(B) (C) |
Contexte d'utilisation
Production d'un service Web SOAP ou REST
Paragraphe d'utilisation
DECLARATION du programme
DECLARATION d'une procédure publique
Syntaxe
SW_CONFIGURER Portée ElemConfig
Portée |
→ |
*SERVICE | *OPERATION |
ElemConfig |
→ |
AttributValeur | XmlExtrait |
AttributValeur |
→ |
NomAttribut ValeurAttribut |
NomAttribut |
→ |
'ConstanteAlpha' |
ValeurAttribut |
→ |
'ConstanteAlpha' |
XmlExtrait |
→ |
*XML_MEM(XmlMem) | *XML_FIC(XmlFic) |
XmlMem |
→ |
'ConstanteAlpha' |
XmlFic |
→ |
NomRessourceAdelia |
Description
Cet ordre permet de configurer le comportement d'un service Web SOAP (de style DOCUMENT ou DOCUMENT_JAXWS) ou REST produit avec Adélia Studio. Les éléments de configuration se rapportent soit au service Web soit à l'une de ses opérations (l'opération contenant l'ordre en question).
Pour un service Web SOAP, les éléments de configuration sont ajoutés au fichier "services.xml" inclus dans l'archive <NomService.aar> regroupant l'ensemble des éléments constitutifs du service Web de type DOCUMENT/Literal.
Pour un service Web REST, les éléments de configuration sont pris en compte dans la génération du source L3G, pour la plupart sous forme d'annotations java.
L'ajout d'un élément de configuration se fait de deux façons :
Ajout d'une paire NomAttribut / ValeurAttribut
Certains noms prédéfinis d'attributs permettent de configurer aisément les options les plus courantes :
NomAttribut |
Portée |
Description |
Type |
target_namespace |
*SERVICE |
Redéfinition du target_namespace du service. |
SOAP |
schema_namespace |
*SERVICE |
Définition d'un schema_namespace spécifique pour les éléments du schéma XML produit. |
SOAP |
scope |
*SERVICE |
Définition de la portée du service ('request', 'soapsession', 'transportsession', 'application') ; 'request' est la portée par défaut. 'soapsession' et 'transportsession' sont des portées spécifiques au type de service SOAP. |
SOAP ou REST |
elementFormDefault |
*SERVICE |
Fixe l'information elementFormDefault à qualified (par défaut) ou unqualified pour la génération du schéma XML dans le fichier WSDL produit. |
SOAP |
attributeFormDefault |
*SERVICE |
Fixe l'information attributeFormDefault à qualified (par défaut) ou unqualified pour la génération du schéma XML dans le fichier WSDL produit. |
SOAP |
schemaDisableNillableElem |
*SERVICE |
Désactive (true) les éléments "nillable", pour la génération du schéma XML dans le fichier WSDL produit. |
SOAP |
schemaDisableOptionalElem |
*SERVICE |
Désactive (true) les éléments optionnels (attribut "minoccurs=0") pour la génération du schéma XML dans le fichier WSDL produit. |
SOAP |
action_mapping |
*OPERATION |
Ajout d'un action_mapping spécifique pour l'opération. |
SOAP |
async |
*SERVICE | *OPERATION |
Permet de déclarer un service asynchrone (true | false). |
SOAP |
module |
*SERVICE | *OPERATION |
Permet d'engager un module. |
SOAP |
enableMTOM |
*SERVICE |
Activation de l'optimisation MTOM pour le transfert des binaires en direction du client. (true | false) Les binaires ne sont alors plus sérialisés sous la forme d'une chaine encodée en base64 mais sous la forme de messages mime optimisés MTOM. |
SOAP |
@Path |
*SERVICE | *OPERATION |
Attribution d'une URI à un programme (ressource racine) ou à une procédure publique (ressource). Si l'URI contient des variables {var}, ces dernières, pour être exploitées, doivent être déclarées sous forme de paramètres. |
REST |
@GET @PUT @POST @DELETE @OPTIONS @HEAD |
*SERVICE | *OPERATION |
Attribution d'une opération HTTP à une procédure publique (ressource). |
REST |
@Consumes |
*SERVICE | *OPERATION |
Définition des formats acceptés par une ressource. Le format est celui du corps de la requête HTTP. |
REST |
@Produces |
SERVICE | *OPERATION |
Définition des formats produits par une ressource. Le format est celui du corps de la réponse HTTP. |
REST |
_init_pgm_as_method |
*SERVICE |
Définition du comportement du pavé INIT_PGM. (true | false) Par défaut (true), le pavé INIT_PGM est traité comme une procédure publique dans le but de devenir ressource. Si l'attribut est fixé à "false", le pavé INIT_PGM n'est plus une ressource mais un pavé d'initialisation du service. Ceci est utile dans le cas d'un service avec une portée "application". |
SOAP ou REST |
_root_result_name |
*OPERATION |
Permet, pour le processus de sérialisation, de nommer un ensemble construit à partir de plusieurs paramètres résultats de nature content. |
SOAP ou REST |
_swag_description |
*SERVICE | *OPERATION |
Ajout d'une description swagger à une procédure publique (ressource). |
REST |
|
_swag_tags |
*SERVICE | *OPERATION |
Dans le cas d'une portée *SERVICE, permet de définir les groupes/tags du service. La virgule est le caractère de séparation. |
REST |
_swag_notes |
*OPERATION |
Ajout d'une description swagger étendue à une procédure publique (ressource). |
REST |
_swag_desc_param |
*OPERATION |
Ajout d'une description swagger propre à un paramètre entrant de nature path, query, header ou form. Par défaut : utilisation du nom externe du paramètre s'il existe, du nom interne le cas échéant. La valeur de l'attribut est composée de deux parties séparées par le caractère ':'. La première partie est le nom du paramètre, la seconde partie est la description. Exemple : sw_configurer *OPERATION '_swag_desc_param' 'idPers:identifiant d''une personne' |
REST |
_swag_response |
*OPERATION |
Permet de présenter les codes HTTP de retour possibles. La valeur de l'attribut est composée de deux parties séparées par le caractère ':'. La première partie est le code HTTP, la seconde partie est la description. Exemple : sw_configurer *OPERATION '_swag_response' '404:la ressource demandée n'a pas été trouvée' |
REST |
_swag_extdoc_url |
*SERVICE |
Permet d'ajouter un lien vers une documentation externe. Pour faire afficher ce lien, il est obligatoire d'ajouter une description à l'aide de l'attribut _swag_extdoc_desc. Exemple : sw_configurer *SERVICE '_swag_extdoc_url' 'http://www.hardis-group.com' |
REST |
_swag_extdoc_desc |
*SERVICE |
Permet d'ajouter une description qualifiant le lien vers une documentation externe. Exemple : sw_configurer *SERVICE '_swag_extdoc_desc' 'Hardis Group' |
REST |
@DeclareRoles |
*SERVICE |
Déclare un ensemble de rôles utiles à la gestion sécurisée par annotation des ressources (la virgule est le caractère de séparation). |
REST |
@PermitAll |
*SERVICE | *OPERATION |
Accorde l'accès à la ressource à tous les rôles définis via l'annotation @DeclareRoles. |
REST |
@RolesAllowed |
*SERVICE | *OPERATION |
Accorde l'accès à la ressource à tous les rôles précisés dans l'annotation (la virgule est le caractère de séparation) : les rôles saisis doivent appartenir à l'ensemble de rôles déclarés via l'annotation @DeclareRoles. |
REST |
@DenyAll |
*SERVICE | *OPERATION |
Interdit l'accès à la ressource à tous les rôles. |
REST |
Remarque : dans le cas des services REST, l'auto-complétion propose des constantes prédéfinies (_WS_REST_FMT_*) pour les formats d'échange les plus courants ; ces constantes doivent être utilisées avec les attributs @Produces ou @Consumes.
- Pour un service Web SOAP, les autres noms d'attributs ont pour effet la génération d'un élément XML de configuration de nom 'parameter' : <parameter name="NomAttribut">ValeurAttribut</parameter>.
Ajout d'un extrait XML depuis une constante ALPHA (*XML_MEM) ou une ressource Adélia (*XML_FIC) (SOAP uniquement).
Les fonctionnalités d'Axis2 sur lequel s'appuie Adélia Studio, sont extensibles à l'aide de modules qui sont des implémentations des différentes spécifications standardisées liées aux services Web (WS-*). Par exemple, le module "rampart" est une implémentation de la spécification WS-SECURITY en charge de la sécurité des services Web.
Pour chacun de ces modules il faut se référer à la documentation disponible sur internet pour connaître les éléments de configuration disponibles et insérables dans le fichier services.xml de configuration du service.
Les directives *XML_MEM et *XML_FIC permettent d'ajouter in extenso des éléments de configuration dans le fichier services.xml.
Par exemple
SOAP
SW_CONFIGURER *SERVICE 'target_namespace' 'http://mondomain.com'
Redéfinition du target_namespace du service.
SW_CONFIGURER *SERVICE 'module' 'addressing'
Engagement du module d'adressage (WS-ADDRESSING).
SW_CONFIGURER *SERVICE 'scope' 'application'
Déclaration d'un service de portée 'application'.
SW_CONFIGURER *SERVICE 'enableMTOM' 'true'
Activation de l'optimisation MTOM pour l'envoi de binaires par le service.
SW_CONFIGURER *SERVICE *XML_FIC(SecPolicy)
Ajout d'un extrait XML à partir d'une ressource Adélia nommée SecPolicy.
REST
Une ressource (procédure publique) d'un service REST est adressable via une URI et une action (méthode HTTP).
L'URI est définie à l'aide de l'attribut @Path ; les méthodes HTTP sont définies à l'aide des attributs @GET, @PUT, @POST, @DELETE, @HEAD, @OPTIONS.
SW_CONFIGURER *SERVICE '@Path' '/cars'
SW_CONFIGURER *SERVICE _WS_REST_A_PATH '/cars'
Définition d'une annotation @Path pour le programme (ou service ; définition de la ressource racine).
SW_CONFIGURER *OPERATION '@Path' '/{numberPlate}'
SW_CONFIGURER *OPERATION _WS_REST_A_PATH '/{numberPlate}'
Définition d'une annotation @Path pour une procédure publique (ressource).
L'URI peut contenir des parties variables (une variable est placée entre des accolades) ; pour être exploitables, ces variables doivent correspondre à des paramètres locaux de la procédure publique.
SW_CONFIGURER *OPERATION '@GET' *BLANK
SW_CONFIGURER *OPERATION _WS_REST_A_GET *BLANK
Définition d'une action @GET (méthode HTTP) pour une procédure publique (ressource).
SW_CONFIGURER *OPERATION '@Consumes' 'application/xml;charset=utf-8'
SW_CONFIGURER *OPERATION _WS_REST_A_CONSUMES _WS_REST_FMT_APP_XML
Définition d'un format accepté pour la gestion du corps/contenu de la requête HTTP.
SW_CONFIGURER *OPERATION '@Produces' 'application/json'
SW_CONFIGURER *OPERATION _WS_REST_A_PRODUCES _WS_REST_FMT_APP_JSON
Définition d'un format produit pour la gestion du corps/contenu de la réponse HTTP.
Une même ressource peut retourner du contenu sous plusieurs formats afin de s'adapter aux préférences du client (exprimées via le header HTTP accept).
Gestion des autorisations
SW_CONFIGURER *SERVICE '@DeclareRoles' 'role1,role2,role3'
SW_CONFIGURER *SERVICE _WS_REST_A_DECLARE_ROLES 'role1,role2,role3'
Déclaration des rôles utilisés dans la gestion des autorisations.
SW_CONFIGURER *OPERATION '@RolesAllowed' 'role1'
SW_CONFIGURER *OPERATION _WS_REST_A_ROLES_ALLOWED 'role1,role3'
Définition des rôles autorisés à accéder à la ressource.
SW_CONFIGURER *OPERATION '@PermitAll' *BLANK
SW_CONFIGURER *OPERATION _WS_REST_A_PERMIT_ALL *BLANK
Donne l'accès à la ressource à tous les rôles déclarés via l'annotation @DeclareRoles.
SW_CONFIGURER *OPERATION '@DenyAll' *BLANK
SW_CONFIGURER *OPERATION _WS_REST_A_DENY_ALL *BLANK
Supprime l'accès à la ressource à tous les rôles.
Swagger
SW_CONFIGURER *SERVICE '_swag_extdoc_url' 'http://www.doc.externe'
SW_CONFIGURER * SERVICE _WS_REST_SWAG_EXTERNAL_DOC_URL 'http://www.doc.externe '
Ajout d'un lien vers une documentation externe.
SW_CONFIGURER * SERVICE '_swag_extdoc_desc' 'Lien vers une documentation externe'
SW_CONFIGURER * SERVICE _WS_REST_SWAG_EXTERNAL_DOC_DESC 'Lien vers une documentation externe'
Ajout d'une description qualifiant le lien vers une documentation externe.
SW_CONFIGURER *SERVICE '_swag_tags' Groupe1,Groupe2'
SW_CONFIGURER *SERVICE _WS_REST_SWAG_TAGS 'Groupe1,Groupe2'
Déclaration des groupes utilisés pour présenter les ressources du service.
SW_CONFIGURER *SERVICE '_swag_description' 'Description Groupe1,Description Groupe2'
SW_CONFIGURER *SERVICE _WS_REST_SWAG_DESCRIPTION 'Description Groupe1,Description Groupe2'
Déclaration des descriptions des groupes utilisés pour présenter les ressources du service.
SW_CONFIGURER *OPERATION '_swag_tags' Groupe1'
SW_CONFIGURER *OPERATION _WS_REST_SWAG_TAGS 'Groupe1'
Affectation de la ressource au groupe nommé Groupe1.
SW_CONFIGURER *OPERATION '_swag_description' 'Description de la ressource'
SW_CONFIGURER *OPERATION _WS_REST_SWAG_DESCRIPTION 'Description de la ressource'
Association d'une description à la ressource.
SW_CONFIGURER *OPERATION '_swag_notes' 'Description étendue de la ressource'
SW_CONFIGURER *OPERATION _WS_REST_SWAG_NOTES 'Description étendue de la ressource'
Association d'une description étendue à la ressource.
SW_CONFIGURER *OPERATION '_swag_desc_param' 'NomParam1:Description du param1'
SW_CONFIGURER *OPERATION '_swag_desc_param' 'NomParam2:Description du param2'
SW_CONFIGURER *OPERATION _WS_REST_SWAG_DESC_PARAM 'NomParam1:Description du param1'
SW_CONFIGURER *OPERATION _WS_REST_SWAG_DESC_PARAM 'NomParam2:Description du param2'
Association d'une description à un paramètre en entrée de la ressource.
SW_CONFIGURER *OPERATION '_swag_response' '404:Ressource non trouvée'
SW_CONFIGURER *OPERATION '_swag_response' '403:Accès à la ressource non autorisé'
SW_CONFIGURER *OPERATION _WS_REST_SWAG_RESPONSE '404:Ressource non trouvée'
SW_CONFIGURER *OPERATION _WS_REST_SWAG_RESPONSE '403:Accès à la ressource non autorisé'
Donne une description des codes HTTP possibles liées à la ressource.