====== Guide d'implémentation d'eP-WebServices ======

===== 1. Introduction =====

eP-WebServices est le module permettant l'accès à eP-Core à l'aide de web-services. Cela permet à des application externes (eP-Back par exemple) d'interroger eP-Core en utilisant des requêtes HTTP contenant du XML. De ce fait on peut ouvrir à "l'extérieur" certaines fonctionnalités bien précises d'eP-Core.


===== 2. Technologies =====
\\

{{ epws_general.png }}

>> **Figure 1** : Schématisation du fonctionnement des web-services. 
>>  - 1/ Le fournisseur fournit un document au format WSDL permettant de décrire le service proposé (adresse, arguments acceptés en entrée, type de retour etc…). 
>>  - 2/ Le client interroge le diffuseur afin de récupérer la description du service.  
>>  - 3/ Après avoir construit sa requête selon le schéma demandé le client l’envoie au fournisseur du service qui traite la demande et réexpédie la réponse.


La technologies utilisée pour implémenter les web-services est CXF. Pour plus d'information sur cette librairie et son utilisation, se reporter au chapitre [[.:cxf_web-services|suivant]] 

===== 3.  Architecture =====

Cette section décrit l’organisation des packages ainsi que les points d’interaction entre eP-WebServices et eP-Core.

==== Général ====
{{ epWS_fonctionmt.png }}

>> **Figure 2** : Fonctionnement d'eP-webservices (eP-WS). 
>> - eP-WS fonctionne comme un fournisseur de web-services normal (voir figure 1)  sauf qu'il intègre la notion de diffuseur et qu'il délègue le traitement de la requête à eP-Core. 
>> - eP-WS est donc un intermédiaire entre un utilisateur extérieur et eP-Core :il reçoit la requête SOAP, la décode, la transmet à eP-Core qui lui renvoie la réponse. eP-WS traite celle-ci en la modifiant au besoin et en la codant en SOAP, puis il l'envoie à l'utilisateur.


==== eP-WebServices ====

eP-WS est un projet Web normal intégrant une librairie particulière permettant de faire des web-services. On retrouve donc sous le répertoire WEB-INF:
  * geronimo-web.xml : intégration au serveur d'application geronimo
  * services.xml : déclaration des services pour [[ cxf_web-services|CXF]]
  * springWSAppContext.xml : fichier spring définissant le lien entre les beans d'implémentation des services et les services [[ cxf_web-services|CXF]]
  * web.xml : fichier classique d'application web, contenant également la définition pour [[ cxf_web-services|CXF]]


=== et eP-CoL  ===

Pour la partie communication, eP-WebServices utilise la librairie [[ep-col|eP-CoL]]. Cette librairie définit
    * les classes représentant tous les objets qui seront échangés entre les applications. Ces objets sont le plus souvent une vue simplifiée/condensées des objets du domaine d'eP-Core.
    * les interfaces des services qui sont proposés par eP-WebServices  


eP-WebServices contient 2 packages :
  * cea.edyp.ws.model contient l'implémentation des objets du modèle d'eP-CoL nécessaire aux services
  * cea.edyp.ws.service contient l'implémentation des services définis dans eP-CoL.

eP-WebServices étends ''IComVirtualPlate'' d'eP-CoL afin d'ajouter les fonctionnalités d'ajout et de supression d'échantillons.

==== implémentation ====

Ce paragraphe décrit les spécificités au niveau implémentation des objets et services définit dans eP-CoL.

__''IVirtualPlate & VirtualPlate'' : Classes représentant des plaques virtuelles.__ 
:!: Elles ne représentent pas le même objet que les classes IVirtualPlate et VirtualPlate d'eP-Core (dans le code les classes d'eP-Core sont “surnommé” Business Virtual Plate et celles d'eP-WebServices WS Virtual Plate. Ex la méthode businessVPlateToWsVPlate(…) qui transforme une plaque du modèle d'eP-Core en plaque du modèle d'eP-WS). Ces classes spécifiques d'eP-WebServices représentent une plaque virtuelle en associant un PlateDescriptor et une liste de RobotSample. Ces plaques virtuelles ne contiennent donc pas, à la différence des objets d'eP-Core, de liste de puits pointant vers des planning robot. Pour figurer ces puits la liste est de taille définie (nb colonnes * nb lignes de la plaque) et à chaque emplacement il y a un RobotSample pour figurer un puits remplit ou null pour un puits vide.



===== 4. Construction d'un nouveau Web-service =====

Un web-service, avec CXF, est composé d'une interface et de sa classe d'implémentation (ex : PlateStorage et IPlateStorage). L'ensemble des méthodes présentent dans l'interface constituera les méthodes disponibles pour le service. La classe d'implémentation contient ces même méthodes plus des méthodes permettant aux services de fonctionner (test de valeurs, transformation de paramètres etc...).  Cette classe d'implémentation contient aussi en tant qu'attribut un (ou des) délégué(s) qui sont les services d'eP-Core nécessaires aux traitement de la requête.

Pour construire un web-service il faut donc :
  * 1/ déterminer les méthodes nécessaire à ce service.
  * 2/ écrire l'interface du service déclarant ces méthodes dans eP-CoL !!.
  * 3/ déterminer le(s) service(s) d'eP-Core nécessaires.
  * 4/ écrire la classe d'implémentation de ce service (dans eP-WebServices) + les méthodes de fonctionnement utile (les classes d'implem peuvent étendre de classes générique tel que PlateGenericWebServices pour les services liés aux plaques de préparation robot)
  * 5/ déclarer la classe d'implem comme bean spring dans le fichier de configuration springWSAppContext.xml Voir [[.:cxf_web-services|CXF]].
  * 6/ déclarer le services comme bean dans services.xml. Voir [[.:cxf_web-services|CXF]]

Après avoir lancer l'appli il suffit d'interroger l'adresse domaine ?WSDL (ex : /PlateServices?WSDL) pour récupérer la description du services et construire une requête.