Téléchargement des produits


Version anglaise


 


      

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. Par défaut, la valeur est celle fixée dans les attributs du domaine ou de l'environnement au niveau du champ Espace de noms de l'onglet Java/Services Web.

SOAP

schema_namespace

*SERVICE

Définition d'un namespace (espace de noms) spécifique pour les éléments du schéma XML produit. Par défaut, la valeur est celle fixée dans les attributs du domaine ou de l'environnement au niveau du champ Espace de noms de l'onglet Java/Services Web.

SOAP

xsd_schema_namespace *SERVICE Définition d'un namespace (espace de noms) secondaire spécifique pour les éléments complexes du schéma XML produit. Par défaut, ce namespace est construit à partir du package java des programmes 'services web' définis dans les attributs du domaine ou de l'environnement. 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

jaxws_itemlist_name *SERVICE

Mode DOCUMENT_JAXWS. Renommage de l'élément wrapper des items de liste d'un paramètre en entrée ou en sortie de type LISTE.

Le pattern '<list>' est substitué par le nom de la liste ou le nom externe de la liste s'il a été défini.
Exemple :

Code Adélia
SW_CONFIGURER *SERVICE 'jaxws_itemlist_name' 'item_<list>'
LISTE lst z1 z2
PARAM lst,i,listeIn
Fragement XML correspondant (option de génération NoWrapperSingleListParam cochée)
<listeIn>
   <item_listeIn><z1>value</z1><z2>value</z2></item_listeIn>
   <item_listeIn><z1>value</z1><z2>value</z2></item_listeIn>
   ...
</listeIn>

SOAP

jaxws_noextra_s_wrapper_name *SERVICE

Mode DOCUMENT_JAXWS. Suppression du "s" terminal de l'élément wrapper englobant pour les paramètres en entrée et les paramètres en sortie de type LISTE.

Un paramètre en entrée de type LISTE ou un paramètre non unique en sortie - sans aucune option de génération cochée (NoWrapperParamWithList ou NoWrapperSingleListParam) - produit dans le <body> de l'enveloppe SOAP un fragment XML semblable à celui-ci :

Code Adélia
LISTE lst z1 z2
PARAM lst,i,mylist
Fragment XML (attribut jaxws_noextra_s_wrapper_name=false)
<mylist>
   <mylists>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      ...
   </mylists>
<mylist> 


Fixer l'attribut jaxws_noextra_s_wrapper_name à la valeur "true" supprimera le "s" terminal de l'élément englobant <mylists>.

Fragment XML (attribut jaxws_noextra_s_wrapper_name=true)
<mylist>
   <mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      ...
   </mylist>
<mylist> 
SOAP
jaxws_gen_list_wrapper_out_class *SERVICE

Mode DOCUMENT_JAXWS. Fixer à la valeur "false" permet, conjointement à l'option de génération [NoWrapperParamWithList] de supprimer l'élément wrapper des items de liste des paramètres en sortie de type LISTE - quand le paramètre en sortie n'est pas unique (en cas de paramètre unique, aucun élément wrapper n'est utilisé dès lors que l'option de génération NoWrapperSingleListParam est cochée).

Code Adélia - Un seul paramètre en sortie de type LISTE
ALPHA(15) p1
LISTE lst z1 z2
PARAM p1,o,palp lst,o,mylist 
Fragment XML (option NoWrapperParamWithList cochée et attribut jaxws_gen_list_wrapper_out_class=true)
<palp>value</palp>
<mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   ...
<mylist> 


Fixer l'attribut jaxws_gen_list_wrapper_out_class à la valeur "false" supprimera l'élément <mylist> englobant.

Fragment XML (option NoWrapperParamWithList cochée et attribut jaxws_gen_list_wrapper_out_class=false)
<palp>value</palp>
<mylist><z1>value</z1><z2>value</z2></mylist>
<mylist><z1>value</z1><z2>value</z2></mylist>
...
SOAP
jaxws_gen_list_wrapper_in_class *SERVICE

Mode DOCUMENT_JAXWS. Fixé à la valeur 'false' permet, conjointement à l'option de génération [NoWrapperSingleListParam] de supprimer l'élément wrapper des items de liste des paramètres en entrée de type LISTE.

Code Adélia
LISTE lst z1 z2
PARAM lst,i,mylist 
Fragment XML (option NoWrapperSingleListParam cochée et attribut jaxws_gen_list_wrapper_in_class=true)
<mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   ...
<mylist> 


Fixer l'attribut jaxws_gen_list_wrapper_in_class à la valeur "false" supprimera l'élément <mylist> englobant.

Fragment XML (option NoWrapperSingleListParam cochée et attribut jaxws_gen_list_wrapper_in_class=false)
<mylist><z1>value</z1><z2>value</z2></mylist>
<mylist><z1>value</z1><z2>value</z2></mylist>
...
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).
Dans le cas d'une portée *SERVICE (ressource racine), la désignation du programme Adélia est utilisée par défaut. Définit un groupe/tag commun à toutes les opérations/apis du service.
Utilisé conjointement avec l'attribut _swag_tags, donne une description aux différents groupes/tags (la virgule est le caractère de séparation).
Dans le cas d'une portée *OPERATION, donne une description de l'opération/api, le nom de la procédure Adélia est utilisé par défaut.

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.
Dans le cas d'une portée *OPERATION, permet d'affecter l'opération/l'api à une liste de groupes/tags. Par défaut, l'opération/l'api est affectée à tous les groupes/tags déclarés par le service.

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 trois parties séparées par le caractère ':'.
La première partie est, au choix :

    • le nom d'une variable portant le modèle résultat à afficher.
    • *NONE pour n'afficher aucun modèle résultat.
    • Rien pour un modèle résultat par défaut, celui correspondant à la variable paramètre portant la définition o[content].

La deuxième partie partie est le code HTTP.
La troisième partie est la description.

Exemples :

sw_configurer *OPERATION '_swag_response' 'VarPerson:200:la personne a été identifiée'
sw_configurer *OPERATION '_swag_response' 'VarError:500:Erreur de service'
sw_configurer *OPERATION '_swag_response' '404:la ressource demandée n'a pas été trouvée'
sw_configurer *OPERATION '_ swag_response ' '*NONE:401:Utilisateur non autorisé'

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


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

  • Aucune étiquette