Guide d’utilisation d’Apache Wink étape par étape [Eng]

Guide d’utilisation d’Apache Wink étape par étape

...

Introduction à Apache Wink

Apache Wink 1.1 est une solution Java complète pour l'implémentation et la consommation de services Web basés sur REST. L'objectif de la structure Wink est de fournir un ensemble de classes et d'interfaces réutilisables et extensibles qui servira de base sur laquelle un développeur peut efficacement construire des applications.

Wink se compose d'un module serveur permettant de développer des services REST et d'un module client destiné à l'utilisation de services REST. Il sépare clairement les aspects de protocole de bas niveau des aspects d'application. Par conséquent, pour implémenter et utiliser les services Web REST, le développeur doit uniquement se concentrer sur la logique métier de l'application et non sur les détails techniques de bas niveau.

Le Guide du développeur Wink fournit au développeur une compréhension rudimentaire du cadre Wink et des blocs de construction qui le composent.

Bienvenue sur Apache Wink

Wink est un cadre pour la mise en œuvre et la consommation simples de services Web REST. REST est un acronyme qui signifie REpresentational State Transfer. Les services Web REST sont des "ressources" identifiées par des URI uniques. Ces ressources sont accessibles et manipulées à l’aide d’un ensemble de «méthodes uniformes». Chaque ressource a une ou plusieurs "représentations" qui sont transférées entre le client et le service lors d'un appel de service Web.

Les caractéristiques centrales qui distinguent le style architectural REST des autres styles basés sur le réseau sont l'accent mis sur une interface uniforme, des représentations multiples et une introspection des services.

Wink facilite le développement et la consommation de services Web REST en fournissant les moyens de modéliser le service en fonction du style architectural REST. Wink fournit l'infrastructure nécessaire à la définition et à la mise en œuvre des ressources, représentations et méthodes uniformes composant un service.

Architecture REST

Pour une compréhension détaillée de l'architecture REST, reportez-vous à la description de Roy Fielding dans son mémoire, La conception des architectures logicielles basées sur le réseau. En particulier, le chapitre 5 du REST (Representational State Transfer) décrit les principes de l'architecture.

Service Web REST

Figure 1: Structure de conception du service Web REST

 La figure 1 présente les principes de conception et les composants d'un service Web REST. Wink reflète ces principes de conception dans la mise en œuvre des services Web.

Apache Wink Open Development

Ce document fournit des informations détaillées sur Wink 1.1 et décrit les fonctionnalités supplémentaires fournies par le moteur d’exécution Apache Wink 1.1 en plus de la spécification du service Web JAX-RS Java API pour REST.

Outre la description des fonctionnalités, ce document fournit également des informations sur les problèmes spécifiques à la mise en œuvre.

Ce document fournit au développeur une compréhension rudimentaire du cadre Wink 1.1 afin de mettre en évidence les concepts et préceptes sous-jacents qui le composent afin de créer une base pour la compréhension, la coopération et le développement ouvert de Wink.

Document de spécification JAX-RS

Pour plus d'informations sur la fonctionnalité JAX-RS, reportez-vous au document de spécification JAX-RS, disponible à l'emplacement suivant:

Conformité JAX-RS

Apache Wink 1.1 vise à être une implémentation entièrement conforme de la spécification JAX-RS v1.1.

JAX-RS est une API Java pour les services Web RESTful. Il s'agit d'une API de langage de programmation Java qui prend en charge la création de services Web conformément au style architectural REST (Representational State Transfer). JAX-RS utilise des annotations, introduites dans Java SE 5, pour simplifier le développement et le déploiement de clients de service Web et de points de terminaison.

2 blocs de construction Apache Wink

Cette page a été modifiée pour la dernière fois le 20 avril 2010 par bluk.

Blocs de construction Apache Wink

Afin de tirer pleinement parti d'Apache Wink, il est nécessaire de connaître les éléments constitutifs qui le composent et leur intégration fonctionnelle. La section suivante fournit une introduction aux concepts de base et aux blocs de construction d'Apache Wink. Pour acquérir une compréhension approfondie des blocs de construction, reportez-vous à la table des matières où ces concepts sont développés et des exemples supplémentaires sont utilisés pour illustrer davantage les technologies Apache Wink et JAX-RS SDK.

Cette section contient les rubriques suivantes:

Blocs de mise en œuvre de services

• Ressource
• Fournisseurs
• Envoi d'URI
• Les atouts
• annotations
• Gestion des URL
• Méthodes HTTP - GET, POST, PUT, DELETE et OPTIONS
• Paramètres de requête URL de base
• Résumé des blocs de construction Apache Wink

Composants clients

• Classe RestClient
• interface de ressources
• Interface ClientRequest
• Interface ClientResponse
• Classe ClientConfig
• Interface ClientHandler
• Interface InputStreamAdapter
• Interface OutputStreamAdapter
• Classe EntityType

Le temps d'exécution Apache Wink

• Processeur de demande
• Configuration de déploiement
• Chaînes de manutention

Présentation du bloc de création de services

Comme indiqué dans la section "Introduction à Apache Wink", Apache Wink reflète les principes de conception d'un service Web REST. Pour ce faire, il fournit au développeur un ensemble de classes java qui permettent la mise en oeuvre de "Ressources", "Représentations" et l'association entre elles. Wink permet également au développeur de définir l'URI de la ressource et les "méthodes uniformes" applicables à la ressource.

Ressource

Une "ressource" représente un composant réparable qui permet de récupérer et de manipuler des données. Une "classe de ressources" est utilisée pour implémenter une ressource en définissant les "méthodes de ressources" qui traitent les demandes en implémentant la logique applicative. Une ressource est liée ou ancrée à un espace URI en annotant la classe de ressource avec l'annotation @Path.

Fournisseurs

Un fournisseur est une classe annotée avec l'annotation @Provider et implémentant une ou plusieurs interfaces définies par la spécification JAX-RS. Les fournisseurs ne sont liés à aucune ressource spécifique. Le fournisseur approprié est automatiquement sélectionné par le moteur d'exécution Apache Wink conformément à la spécification JAX-RS. Apache Wink fournit de nombreux fournisseurs. Cependant, les développeurs d'applications peuvent fournir leurs propres fournisseurs, qui priment sur tous les fournisseurs du runtime par défaut.

Il existe trois types de fournisseurs définis par la spécification JAX-RS:

• Fournisseurs d'entrée
• Fournisseurs de contexte
• Fournisseur de mappage d'exceptions

Entité Fournisseur

Un "fournisseur d'entité" est une classe qui convertit les données du serveur dans un format spécifique demandé par le client et / ou convertit une requête transmise par le client en données de serveur. Par exemple, un fournisseur d'entité String peut transformer les entités de requête (corps du message) en réseau en un type Java (.String). Les fournisseurs d'entités peuvent également transformer les types Java natifs, tels que .String, en une entité de réponse appropriée. Un fournisseur d'entité peut être limité pour prendre en charge un ensemble limité de types de support à l'aide des annotations .Produces et .Consumes. Un fournisseur d'entité est configuré pour gérer un type de données de serveur spécifique en implémentant les interfaces .MessageBodyWriter et / ou .MessageBodyReader.

Figure 2: Schéma du fournisseur d'entité

Fournisseur de contexte

Les fournisseurs de contexte sont utilisés pour fournir des contextes aux classes de ressources et aux autres fournisseurs en implémentant l'interface .ContextResolver. Par exemple, si un JAXBContext personnalisé est requis pour sérialiser ou désérialiser des objets JAXB, une application peut fournir un ContextResolver qui renverra une instance spécifique d'un JAXBContext. Les fournisseurs de contexte peuvent restreindre les types de média qu'ils prennent en charge à l'aide de l'annotation .Produces. Figure 3: Schéma du fournisseur de contexte

Fournisseur de mappage d'exception

Les fournisseurs de mappage d'exceptions mappent les exceptions dans une instance d'un .Response en implémentant l'interface .ExceptionMapper. Les objets Réponse peuvent contenir des informations de réponse, telles que des codes d'état, des en-têtes HTTP et une entité de réponse (corps du message). Lorsqu'une méthode de ressource lève une exception, le moteur d'exécution essaie de trouver un ExceptionMapper approprié pour "traduire" l'exception en un objet Response approprié.

Envoi d'URI

La conception d'un service Web REST efficace nécessite que le développeur de l'application comprenne les ressources qui le composent, comment identifier au mieux les ressources et les relations entre elles.

Les ressources RESTful sont identifiées par les URI. Dans la plupart des cas, les ressources associées ont des URI qui partagent des éléments de chemin communs.

Figure 5: Flux logique Apache Wink

Flux logique Apache Wink

La figure 5 illustre le flux logique Apache Wink. La requête HTTP envoyée par le client appelle le "Servlet Apache Wink REST". Le servlet REST utilise le "Processeur de demande" et l'URI de la demande afin de rechercher, faire correspondre et appeler la méthode de ressource correcte.

Exemple de signets

Tout au long de ce document, divers exemples de projets sont utilisés afin de décrire les fonctionnalités et les processus qui composent Apache Wink.

Afin d'expliquer les principes de conception REST utilisés dans Apache Wink, ce guide du développeur fait référence à l'exemple de projet "Signet" figurant dans le dossier d'exemples situé dans la distribution Apache Wink.

Reportez-vous au code (en utilisant une application IDE) dans l'exemple en conjonction avec les explications et illustrations suivantes de ce guide du développeur.

Serveur Apache Wink et processeur de requêtes

Figure 6: Servlet Apache Wink REST et processeur de requêtes pour les services de signet

Serveur et processeur de requêtes

La figure 6 illustre le concept de servlet et de processeur de requêtes Apache Wink dans le contexte du serveur d'applications. Dans l'exemple "Signets" de la figure 6, il y a deux ressources, la première ressource est associée à l'URI / mybookmarks et gère la collection de signets, la deuxième ressource est associée aux ressources / mybookmarks / {bookmark} et gère un signet individuel dans la collection.

Les ressources définies par le service Web et gérées par Apache Wink sont appelées "espace URI". L'espace Ressources est la collection de tous les URI existant dans le même contexte. La figure 6 illustre l'espace URI contenant / mybookmarks et / mybookmarks / {bookmarks}.

Espace URI

L'espace URI du service Signets comprend les éléments d'espace URI suivants et des descriptions détaillées sur leur contexte et leurs fonctionnalités.

Tableau 1: Gestion des adresses URI

Espace URI

La description

/ Signet / reste

Cet URI est le contexte racine du service de signet et le point d'entrée de l'espace URI du service. Une requête HTTP GET à cet URI renvoie un "document de service" généré automatiquement par Apache Wink. Le document de service fournit des informations sur toutes les collections disponibles dans l'espace URI.

/ Signet / reste / mybookmarks

Cet URI est associé à une collection de ressources de signets. Les clients utilisent la méthode HTTP GET afin de récupérer une représentation de la collection et la méthode HTTP POST afin de créer un nouvel élément dans la collection.

/ Marque-page / reste / mybookmarks /

{signet}

Ce modèle d'URI est associé à une ressource de signet unique. Les clients utilisent la méthode HTTP GET afin de récupérer une représentation de la ressource, la méthode HTTP PUT est utilisée pour mettre à jour la ressource et la méthode HTTP DELETE est utilisée pour supprimer la ressource.

Les atouts

Les actifs sont des classes contenant la "logique métier de service Web" implémentée par le développeur. Chaque actif est associé à un ou plusieurs URI. Le répartiteur Apache Wink appelle l'actif, qui est associé à l'URI trouvé dans la requête HTTP.

Une classe d'actif peut implémenter une ou plusieurs méthodes, chaque méthode étant associée à une seule méthode HTTP (GET, HEAD, POST, PUT, DELETE, etc.). Les méthodes peuvent être associées à un type MIME d’une représentation produite. Les méthodes qui gèrent les verbes HTTP des requêtes avec un corps (tel que PUT, POST) sont également associées au type MIME de la requête HTTP.

La classe d'actif peut être enregistrée dans Apache Wink à l'aide du "Spring contexte xml" ou à l'aide d'une API d'enregistrement.

Configuration du contexte printanier

Pour plus d'informations sur le contexte Spring, voir 5.5 Intégration Spring dans la section 5 Apache Wink Server.

Annotations

Les annotations sont des notations de texte spéciales, ou métadonnées, ajoutées à Java version 1.5. Les annotations dans le code source Java peuvent affecter le comportement à la compilation et à l'exécution des classes Java résultantes.

JAX-RS est implémenté à l'aide des annotations définies dans la spécification JAX-RS. Apache Wink fournit un ensemble d’annotations supplémentaires qui enrichissent les fonctionnalités de l’application compatible JAX-RS.

Le tableau suivant décrit les annotations Apache Wink supplémentaires:

Annotation

Précède

La description

@Workspace

Ressource

Associer une "ressource de collection" à un élément d'espace de travail et à des éléments de collection dans un document de service APP

@Portée

Ressource / Fournisseur

Définit le comportement de cycle de vie par défaut pour les ressources et les fournisseurs, ainsi que l'option de contrôle du cycle de vie via la classe .Application

@Parent

Ressource

Permet de définir un URI de modèle de base pour l'URI spécifié dans une annotation Ressources @Path

@Atout

Classe

Utilisé par le moteur d'exécution Apache Wink pour identifier une entité en tant qu'actif

Gestion des URL

Apache Wink reçoit les requêtes HTTP, puis envoie une requête HTTP intégrée à la méthode Resource appropriée.

La demande HTTP correspond à la méthode Resource en fonction des paramètres de la requête HTTP, des définitions de la méthode Resource et du type MIME.

Figure 7: Traitement des demandes d'URL

 Demande de traitement

La figure 7 illustre le chemin de requête du client HTTP vers le répartiteur d'URI. Une fois que le répartiteur a reçu la demande, la correspondance est établie en fonction de la méthode HTTP, de l'URL et du type MIME et enfin de la définition du registre Resource.

Méthodes HTTP - GET, POST, PUT, DELETE et OPTIONS

Les méthodes HTTP 1.1 communes pour Apache Wink sont définies dans la section suivante. Cet ensemble de méthodes peut être développé.