Web Application Description Language (WADL) est un langage de description
pour les applications basées sur HTTP. Actuellement un World Wide
Web Consortium (W3C) Member Submission. WADL peut être utilisé par les programmes
pour donner des informations sur le service dans une méthode traitable par la machine.
Par exemple, vous pouvez utiliser un document XSLT (Extensible Stylesheet Transformation)
pour transformer la documentation WADL en utilisant un processeur
XSLT et un XSLT personnalisés.
Pourquoi et quand exécuter cette tâche
Par défaut, un document WADL peut être demandé pour une ressource particulière
en appelant une demande HTTP OPTIONS pour toute URL Java™ API for RESTful Web Services (JAX-RS).
Vous pouvez émettre une demande OPTIONS avec la plupart des clients HTTP. Le document WADL
renvoyé de la demande décrit la ressource à l'aide des informations
des annotations JAX-RS.
WADL est une norme de développement qui aide à décrire le services disponible aux utilisateurs. Les documents WADL sont écrits en XML. A l'aide d'analyseurs XSTL ou XML, les développeurs peuvent générer la documentation pour
le service. Dans certains cas, les utilisateurs peuvent développer la compréhension dynamique client
du service RESTful en inspectant le document WADL.
A l'aide de IBM® JAX-RS, les développeurs peuvent générer
une représentation JAXB XML d'un document WADL décrivant toutes les
ressources disponibles dans l'application. La représentation JAXB peut être renvoyée
à partir d'une méthode de ressource JAX-RS.
La ressource de document WADL est alors
traitée comme toute autre ressource JAX-RS ; elle peut être utilisée
par les clients.
- Configurez l'environnement de développement.
- Avant de développer des applications JAX-RS, vous devez configurer l'environnement de déploiement en ajoutant les bibliothèques JAX-RS dans le chemin d'accès aux classes.
- Définissez les ressources dans les applications Web JAX-RS.
- Les ressources sont les principaux blocs fonctionnels d'un service RESTful. Les ressources peuvent contenir des données statiques ou mises à jour dynamiquement.
Un manuel, une commande et une collection d'utilisateurs sont des exemples de ressources d'une application de librairie en ligne. En identifiant les ressources dans l'application, vous améliorez l'utilité du service et facilitez son développement.
- Configurez l'application JAX-RS.
Vous pouvez configurer les applications JAX-RS de plusieurs façons, selon vos besoins.
Pour tirer parti de la fonctionnalité
Java EE (Java Platform, Enterprise Edition) 6, vous pouvez
utiliser les fonctions d'analyse des annotations.
L'analyse des annotations permet d'ignorer une sous-classe JAX-RS
javax.ws.rs.core.Application ou de disposer d'une sous-classe javax.ws.rs.core.Application à définition minimale. Sinon, vous pouvez aussi spécifier le servlet ou le filtre IBM JAX-RS si vous préférez utiliser la fonction qu'ils contiennent.
En employant l'une des méthodes de configuration JAX-RS version 1.1, vous pouvez ignorer une sous-classe javax.ws.rs.core.Application dans votre application ou disposer d'une sous-classe javax.ws.rs.core.Application qui renvoie un ensemble vide de classes pour informer
l'environnement d'exécution JAX-RS qu'il doit détecter et utiliser toutes les classes JAX-RS de l'application. Cette méthode vous évite de
devoir ajouter manuellement chaque classe JAX-RS appropriée à une sous-classe javax.ws.rs.core.Application lors du développement de
l'application.
En indiquant le servlet ou le filtre IBM JAX-RS spécifique, vous pouvez bénéficier d'un comportement IBM JAX-RS particulier et le garantir. Par exemple, l'utilisation du filtre IBM JAX-RS peut faciliter le développement d'une application Web faisant appel à un mélange de ressources JAX-RS et de fichiers JSP (JavaServer Pages) avec les mêmes modèles d'URL.
Bien qu'une méthode de configuration JAX-RS version 1.1 prenne en charge le fichier web.xml facultatif, ce dernier est
obligatoire pour indiquer des contraintes ou des rôles de sécurité ou pour tirer parti de fonctions activées avec un fichier web.xml.
Choisissez l'une des trois méthodes suivantes pour configurer votre application JAX-RS :
- Configuration
d'applications JAX-RS selon les méthodes JAX-RS 1.1
Utilisez cette méthode
pour employer les fonctions d'analyse des annotations ou les méthodes de configuration JAX-RS 1.1. Vous pouvez
utiliser les fonctions d'analyse des annotations pour promouvoir la portabilité de l'application, réduire la quantité de code de
configuration ou modifier l'application dynamiquement sans changer son code.
- Configurez le fichier web.xml pour les servlets JAX-RS
Utilisez cette
méthode pour indiquer des fonctions activées à l'aide des paramètres d'initialisation du servlet, afin d'obtenir un changement de
comportement et le servlet IBM JAX-RS. Lorsque vous utilisez des servlets, vous pouvez définir un chemin de servlet dans le fichier web.xml qui est ajouté à l'URL de base.
- Configuration du fichier web.xml pour les filtres JAX-RS
Utilisez cette méthode pour employer le filtre lorsque vous avez des fichiers JSP, d'autres servlets et filtres ainsi que des ressources
JAX-RS incluant plusieurs masques d'URL. Vous pouvez configurer le fichier web.xml pour définir les filtres qui indiquent les adresses
URL sur lesquelles ils peuvent être appelés.
- Utilisez WADL pour générer la documentation du service. Vous pouvez également créer
votre propre document WADL en utilisant le org.apache.wink.common.model.wadl.WADLGenerator.
WADLGenerator crée un modèle d'objet annoté Java Architecture
for XML Binding (JAXB) pour que vous puissiez facilement le renvoyer en
réponse d'entité dans une méthode de ressource @OPTIONS.
- Assemblez les applications Web JAX-RS.
- Après avoir développé les fichiers de classe Java de l'application Web JAX-RS et modifié le fichier web.xml pour activer le servlet JAX-RS, vous pouvez assembler l'application.
Assemblez l'application Web dans un package WAR (archive Web). Vous pouvez assembler le package WAR dans un package EAR (archive d'entreprise), le cas échéant.
- Déployez les applications Web JAX-RS.
- Après avoir assemblé l'application Web JAX-RS, vous devez déployer le package WAR (Web
archive) ou EAR (enterprise archive) sur le serveur d'applications.
Résultats
Vous avez ajouté un document de service WADL à votre application
pour que les clients puissent extraire une représentation de votre service. Par défaut,
vous pouvez également émettre des demandes OPTIONS à vos ressources pour
extraire une représentation WADL de la ressource individuelle. Si vous avez choisi de ce faire,
vous pouvez désactiver la génération automatique d'un document
WADL pour les demandes OPTIONS.