SW_CONFIGURER

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

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 :

SW_CONFIGURER *SERVICE 'jaxws_itemlist_name' 'item_<list>'
LISTE lst z1 z2
PARAM lst,i,listeIn

<listeIn>
   <item_listeIn><z1>value</z1><z2>value</z2></item_listeIn>
   <item_listeIn><z1>value</z1><z2>value</z2></item_listeIn>
   ...
</listeIn>

LISTE lst z1 z2
PARAM lst,i,mylist

<mylist>
   <mylists>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      ...
   </mylists>
<mylist> 

<mylist>
   <mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      ...
   </mylist>
<mylist> 

ALPHA(15) p1
LISTE lst z1 z2
PARAM p1,o,palp lst,o,mylist 

<palp>value</palp>
<mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   ...
<mylist> 

<palp>value</palp>
<mylist><z1>value</z1><z2>value</z2></mylist>
<mylist><z1>value</z1><z2>value</z2></mylist>
...

LISTE lst z1 z2
PARAM lst,i,mylist 

<mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   ...
<mylist> 

<mylist><z1>value</z1><z2>value</z2></mylist>
<mylist><z1>value</z1><z2>value</z2></mylist>
...

Remarques :

• • • Dans le cas des services REST, l'autocomplé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>.

Mise en garde :

• • • SOAP/DOCUMENT_JAXWS - fixer les attributs target_namespace et schema_namespace avec des valeurs différentes peut aboutir à un résultat incomplet lors de l'inscription automatique du service web : l'élément réponse ('<Operation>Return') d'une opération peut alors être anormalement présenté comme un élément terminal.

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é'

SW_CONFIGURER  *OPERATION '_ swag_response ' 'VarPerson:200:La personne a été correctement identifiée'
SW_CONFIGURER  *OPERATION '_ swag_response ' 'VarError:500:Erreur lors de l'exécution du service'
SW_CONFIGURER  *OPERATION '_ swag_response ' '*NONE:401:Utilisateur non autorisé'
Donne une description des codes HTTP possibles liées à la ressource.

Voir aussi la liste des ordres L4G par thème

↑ Haut de page