SOA – Services Web REST

Développer des Services Web REST

avec Java : JAX-RS
 Licence

Creative Commons
Contrat Paternité
Partage des Conditions Initiales à l'Identique
2.0 France

[Link]

2
 Plan du cours

Généralités JAX-RS

Premier service Web JAX-RS

Rappels HTTP (Requête et Réponse)

Développement Serveur

Chemin de ressource @Path

Paramètres des requêtes

Gestion du contenu, Response et UriBuilder

Déploiement

Développement Client

Outils
3
 Déroulement du cours

Pédagogie du cours

Illustration avec de nombreux exemples qui sont disponibles à
l’adresse [Link]

Des bulles d’aide tout au long du cours

Survol des principaux concepts en évitant une présentation exhaustive

Logiciels utilisés

Navigateur Web, Eclipse 3.6, Tomcat 6, Maven 3

Exemples « Mavenisés » indépendant de l’environnement de dév.

Pré-requis
Ceci est une astuce

Schema XML, JAXB, Introduction Services Web

Remerciements Ceci est une alerte

Djug 4
 Ressources

Billets issus de Blog

[Link]/blog:1

[Link]/JAX-RS-le-specification-Java-pour-implementer-les-services-REST

[Link]/enterprisetechtips/entry/consuming_restful_web_services_with

[Link]/2008/04/25/jsr-311-jax-rs-rest-une-histoire-de-restaurant/

[Link]/2010/12/[Link]

[Link]/sandoz

Articles

[Link]/technetwork/articles/javase/[Link]

[Link]/display/Jersey/Overview+of+JAX-RS+1.0+Features

[Link]/nonav/releases/1.1/[Link]

[Link]/wiki/JAX-RS

[Link]/Java/Article/42873

[Link]/en/jsr/summary?id=311

[Link]/articles/REST/[Link]

[Link]/articles/rest-introduction

[Link]/javaee/6/tutorial/doc/[Link]

[Link]/app/docs/doc/820-4867/820-4867 5
 Ressources (suite)

Articles (suite)

[Link]/nonav/documentation/latest/[Link]

[Link]/developer/technicalArticles/WebServices/jax-rs/[Link]

[Link]/documentation/[Link]

[Link]/documentation/[Link]

[Link]/documentation/[Link]

Présentations

[Link]/caroljmcdonald/td09restcarol

[Link]/linkedin/building-consistent-restful-apis-in-a-highperformance-environment

[Link]/jugtoulouse/rest-nicolas-zozol-jug-toulouse-20100615

[Link]/learning/javaoneonline/2008/pdf/[Link]

Cours

[Link]/nonav/documentation/latest/[Link]

6
 Ressources : Bibliothèque

RESTful Java

Auteur : Bill Burke

Éditeur : Oreilly

Edition : Nov. 2009 - 320 pages - ISBN : 0596158041

Beginning JavaEE6 Platform With GlassFish 3

Auteur : Antonio Goncalves

Éditeur : Apress

Edition : Août 2010 - 536 pages - ISBN : 143022889X

RESTful Java Web Services

Auteur : Jose Sandoval

Éditeur : PACKT Publishing

Edition : Nov. 2009 - 256 pages - ISBN : 1847196462

7
Généralités - Développement de Services Web REST

Nous nous intéressons dans ce cours au développement des

services Web de type REST

Côté Serveur : code pour le traitement du service Web

Côté Client : code qui permet d’appeler un service Web

La majorité des langages de programmation orientés Web

supportent le développement de services Web REST

Java, PHP, C#, C++, …

Nous nous limitons au langage Java dans ce cours

Différents frameworks de développement de Services Web

Ceux qui respectent la spécification JAX-RS (détailler après)

Autres …

AXIS 2 Apache ([Link]/axis2)
8
 Généralités JAX-RS : la spécification

JAX-RS est l’acronyme Java API for RESTful Web Services

Décrite par la JSR 311 ([Link]/en/jsr/summary?id=311)

Version courante de la spécification est la 1.1

Depuis la version 1.1, JAX-RS fait partie intégrante de la

spécification Java EE 6 au niveau de la pile Service Web

Cette spécification décrit uniquement la mise en œuvre de

services Web REST côté serveur

Le développement des Services Web REST repose sur

l’utilisation de classes Java et d’annotations
9
 Généralités JAX-RS : les implémentations

Différentes implémentations de la spécification JAX-RS sont

disponibles

JERSEY : implémentation de référence fournie par Oracle

Site projet : [Link]

CXF : fournie par Apache, la fusion entre XFire et Celtix

Site projet : [Link]

RESTEasy : fournie par JBoss

Site projet : [Link]/resteasy

RESTlet : un des premiers framework implémentant REST

pour Java

Site projet : [Link]
10
 Généralités JAX-RS : les implémentations

Comparaisons sur les performances des implémentations

[Link]/articles/jax-rs-vendor-comparisons-part

[Link]/news/2008/10/jaxrs-comparison

Comme la spécification JAX-RS ne décrit pas la couche
cliente, chaque implémentation fournit une API spécifique

Dans la suite du support de cours nous utiliserons l’implé-
mentation de référence JERSEY

Version actuelle 1.4 respectant la spécification JAX-RS 1.1

Intégrée dans Glassfish et l’implémentation Java EE 6

Outils supportés dans Netbeans

Description Maven (partie serveur)

groupId : [Link]

artifactId : jersey-server

version : 1.4 11
 Généralités JAX-RS : fonctionnement

Développement de
Description du Service Web permettant
clients dans des
de générer la partie cliente
langages différents

WADL
.NET

Servlet JAX-RS
PHP HTTP

Approche Bottom / Up
JAVA Serveur
Web Conteneur Java
Classes JAVA annotées
implémentant le
Différentes APIs service web
possibles pour la gestion
du client en Java
Utilisation du Service
Web par envoie /
Couche Cliente Couche Serveur
réception de contenu
HTTP 12
 Généralités JAX-RS : Développement

Le développement de Services Web avec JAX-RS est basé

sur des POJO (Plain Old Java Object) en utilisant des

annotations spécifiques à JAX-RS

Pas description réquise dans des fichiers de configuration

Seule la configuration de la Servlet « JAX-RS » est requise

pour réaliser le pont entre les requêtes HTTP et les classes

Java annotées

Un Service Web REST est déployé dans une application Web

13
 Généralités JAX-RS : Développement

Contrairement aux Services Web étendus il n’y a pas de

possibilité de développer un service REST à partir du fichier
de description WADL

Seule l’approche Bottom / Up est disponible

Créer et annoter un POJO

Compiler, Déployer et Tester

Possibilité d’accéder au document WADL

Le fichier de description WADL est généré automatiquement

par JAX-RS (exemple : [Link]

Plus tard nous verrons comment utilisé WADL pour
générer la couche cliente
14
 Le Premier Service Web JAX-RS

Exemple : Service Web REST « HelloWorld »

Définition d’un chemin de ressource pour

associer une ressource hello à une URI

Lecture de la ressource
HelloWorld via une requête HTTP
@Path("/hello")
de type GET
public class HelloWorldResource {

@GET
@Produces("text/plain")
public String getHelloWorld() {
return "Hello World from text/plain";
}
}
Le type MIME de la réponse est
de type text/plain

[Link] du projet
HelloWorldRestWebService
15
 Le Premier Service Web JAX-RS

Exemple (suite) : Service Web REST « HelloWorld »

Envoie d’une requête HTTP de type
GET demandant la lecture de la
ressource hello

Plus tard, nous utiliserons des

outils qui facilitent l’écriture de
requêtes HTTP plus complexes
Le retour est directement interprétable (POST, PUT, …)
depuis la navigateur puisqu’il s’agit d’un
type MIME reconnu

16
 Le Premier Service Web JAX-RS

Exemple (suite) : Service Web REST « HelloWorld »

Structure d’une application
[Link] Le rôle du fichier [Link] est de
Web classique Java
déclarer la servlet JERSEY

WEB-INF [Link]

[Link]
classes [Link]

[Link]
[Link]
lib
[Link]
…

Les bibliothèques ne sont pas

Cette application Web contient obligatoires dans le cas où le serveur
un service Web REST d’application les intègre

17
 Le Premier Service Web JAX-RS

Exemple (suite) : Service Web REST « HelloWorld »

Servlet fournie par Jersey pour le
traitement des requêtes HTTP

<?xml version="1.0" encoding="UTF-8"?>

<web-app version="2.5" ...>
<display-name>HelloWorldRestWebService</display-name>
<servlet>
<servlet-name>HelloWorldServletAdaptor</servlet-name>
<servlet-class>[Link]</servlet-class>
<init-param>
<param-name>[Link]</param-name>
<param-value>[Link]</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>HelloWorldServletAdaptor</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app> Dans la partie Déploiement
nous montrerons deux types
de configuration
[Link] du projet
HelloWorldRestWebService
18
 Exemple file rouge : une bibliothèque

Utilisation d’un exemple représentatif pour la présentation

des concepts de JAX-RS : une Bibliothèque

Mise en place d’un système de CRUD

Bibliothèque et livre sont des ressources

Description de l’exemple

Une bibliothèque dispose de livres

Possibilité d’ajouter, de mettre à jour ou de supprimer un livre

Recherche d’un livre en fonction de différents critères (ISBN, nom, …)

Récupération de données de types simples (String, Long, …) ou

structurées

Différents formats de données (JSON, XML, …)

19
 Protocole HTTP : généralités

Hyper Text Transfer Protocol v1.1

Protocole Client/Serveur sans état

Impossibilité de conserver des informations issu du client

La conversation HTTP est initialisée lorsque l’URL est saisie

dans le navigateur
1 - le client ouvre la connexion avec le
serveur

2 - le client émet une requête HTTP

3 - le serveur répond au client

4 - la connexion est fermée

Serveur Web

Client WEB
20
 Protocole HTTP : requête

Requête envoyée par le client (navigateur) au serveur WWW

Document demandé. Protocole HTTP

Le type de méthode
Fichier HTML, une avec la version :
de la requête GET,
image, ... 1.0 ou 1.1
POST, ...

<Méthode> <URI> HTTP/<Version> La ligne blanche

[<Champ d’en-tête>:<Valeur>] est obligatoire
...
Ligne blanche
[corps de la requête pour la méthode Post]

Différentes informations
concernant le navigateur, Le corps de la requête uniquement si la méthode
l’utilisateur, ... est de type POST. Sont fournis les valeurs des
paramètres envoyées par un formulaire

21
 Protocole HTTP : en-têtes de requête

Correspond aux formats de documents et aux paramètres

pour le serveur

Accept = types MIME acceptés par le client (text/html, text/plain, …)

Accept-Encoding = codage acceptées (compress, x-gzip, x-zip)

Accept-Charset = jeu de caractères préféré du client

Accept-Language = liste de langues (fr, en, de, …)

Authorization = type d’autorisation

BASIC nom:mot de passe (en base64)

Transmis en clair, facile à décrypter

Cookie = cookie retourné

From = adresse email de l’utilisateur

... 22
 Protocole HTTP : type de méthodes

Lorsqu’un client se connecte à un serveur et envoie une

requête, cette requête peut-être de plusieurs types, appelés
méthodes

Requête de type GET

Pour extraire des informations (document, graphique, …)

Intègre les données de formatage à l’URL (chaîne d’interrogation)

[Link]/hello?key1=titi&key2=raoul&…

Requête de type POST

Pour poster des informations secrètes, des données graphiques, …

Transmis dans le corps de la requête
<Méthode> <URI> HTTP/<Version>
[<Champ d’en-tête>:<Valeur>]
...
Ligne blanche
[corps de la requête pour la méthode Post]
23
 Protocole HTTP : réponse

Réponse envoyée par le serveur WWW au client (navigateur)

Statuts des réponses Donne des

Protocole HTTP HTTP. Liées à une erreur informations sur
avec la version : ou à une réussite : 200 le statut : OK
1.0 ou 1.1

HTTP/<Version><Status><Commentaire Status>
Content-Type:<Type MIME du contenu>
[<Champ d’en-tête>:<Valeur>]
... La ligne blanche
Ligne blanche est obligatoire
Document

Type de contenu qui sera

retourné : text/html, Le document peut
Différentes informations
text/plain, contenir du texte non
concernant le serveur, ...
application/octet-stream formaté, du code HTML,
...

24
 Protocole HTTP : en-têtes de réponse

Correspond aux informations concernant le serveur WWW

Accept-Ranges = accepte ou refus d’une requête par intervalle

Age = ancienneté du document en secondes

Server = information concernant le serveur qui retourne la réponse

WWW-Authenticate = système d’authentification. Utiliser en couple

avec l’en-tête requête Authorization

ETag = …

Location = …

…
25
 Protocole HTTP : statuts des réponses

Réponse du serveur au client <Status><Commentaire>

100-199 : Informationnel

100 : Continue (le client peut envoyer la suite de la requête), …

200-299 : Succès de la requête client

200 : OK, 204 : No Content (pas de nouveau corps de réponse)

300-399 : Re-direction de la requête client

301 : Redirection, 302 : Moved Temporarily

400-499 : Erreur client

401 : Unauthorized, 404 : Not Found (ressource non trouvée)

500-599 : Erreur serveur

503 : Service Unavailable (serveur est indisponible)
26
 @Path

Une classe Java doit être annotée par @path pour qu’elle
puisse être traitée par des requêtes HTTP

L’annotation @path sur une classe définit des ressources
appelées racines (Root Resource Class)

La valeur donnée à @path correspond à une expression URI
relative au contexte de l’application Web

[Link]

Adresse du Contexte de URI de la

Port ressource
Serveur l'application WEB

Des informations sur la mise en place du

contexte d’une application Web sont
disponibles dans le cours sur les Servlets
27
 @Path

L’annotation @path peut également annoter des méthodes

de la classe (facultatif)

L’URI résultante est la concaténation de l’expression du
@path de la classe avec l’expression du @path de la méthode

Exemple
@Path("/books")
public class BookResource {
Requêtes HTTP @GET

de types GET /books public String getBooks() {

...
}

/books/borrowed @GET
@Path("/borrowed")
public String getBorrowedBooks() {
...
Serveur Web }
}

[Link] du projet Conteneur de Servlets

LibraryRestWebService 28
 @Path : Template Parameters

La valeur définie dans @path ne se limite pas seulement aux

expressions constantes

Possibilité de définir des expressions plus complexes appelées

Template Parameters

Pour distinguer une expression complexe dans la valeur du

@path, son contenu est délimité par { … }

Possibilité également de mixer dans la valeur de @path des

expressions constantes et des expressions complexes

Les Template Parameters peuvent également utiliser des

expressions régulières 29
 @Path : Template Parameters

Exemple : Récupérer un livre par son identifiant

/books/123
@Path("/books")
public class BookResource {
...

@GET
@Path("{id}")
public String getBookById(@PathParam("id") int id) {
return "Java For Life " + id;
}

@GET
@Path("name-{name}-editor-{editor}")
public String getBookByNameAndEditor(@PathParam("name") String name,
@PathParam("editor") String editor)
return "Starcraft 2 for Dummies (Name:" + name + " - Editor:" + editor + ")";
}
}

/books/name-sc2-editor-oreilly
[Link] du projet
LibraryRestWebService
30
 @Path : Template Parameters

Exemple (bis) : Récupérer un livre par son identifiant

/books/123/path1/path2/editor

@Path("/books")
public class BookResource {
...

@GET
@Path("{id : .+}/editor")
public String getBookEditorById(@PathParam("id") String id) {
return "OReilly";
}

@GET
@Path("original/{id : .+}")
public String getOriginalBookById(@PathParam("id") String id) {
return "Java For Life 2";
}
}

/books/original/123/path1/path2
[Link] du projet
LibraryRestWebService
31
 @Path : Sub-resource locator

Une sub-resource locator est une méthode qui doit respec-

ter les exigences suivantes

Annotée avec @Path

Non annotée avec @GET, @POST, @PUT, @DELETE

Retourne une sous ressource (un type Object)

L’intérêt d’utiliser une méthode sub-resource locator est

de pouvoir déléguer vers une autre classe ressource

Le développement d’une sous ressource suit un schéma
classique, pas d’obligation de placer une ressource racine

Une méthode sub-resource locator supporte le
polymorphisme (retourne des sous types)
32
 @Path : Sub-resource locator

Exemple : Appeler une méthode Sub-resource locator

[Link] du projet
LibraryRestWebService

@Path("/books")
public class BookResource {
...
@Path("specific")
public SpecificBookResource getSpecificBook() {
return new SpecificBookResource();
}
}

Méthode Sub-resource locator dont la sous

ressource est définie par SpecificBookResource
public class SpecificBookResource {
@GET
@Path("{id}")
public String getSpecificBookById(@PathParam("id") int id) {
return ".NET platform is Bad";
}
}

[Link] du projet /books/specific/123

LibraryRestWebService 33
 @GET, @POST, @PUT, @DELETE : Méthodes HTTP

L’annotation des méthodes Java permet de traiter de

requêtes HTTP suivant le type de méthode (GET, POST, …)

Les annotations disponibles par JAX-RS sont les suivantes

@GET, @POST, @PUT, @DELETE et @HEAD

Ces annotations ne sont utilisables que sur des méthodes Java

Le nom des méthodes Java n’a pas d’importance puisque
c’est l’annotation employée qui précise où se fera le traitement

Possibilité d’étendre les annotations disponibles pour gérer
différents type de méthode HTTP

Protocole WebDav (extension au protocole HTTP pour la gestion de
documents)

Méthodes supportées : PROPFIND, COPY, MOVE, LOCK, UNLOCK, …
JAX-RS - M. Baron - Page 34
 @GET, @POST, @PUT, @DELETE : Méthodes HTTP

La spécification JAX-RS, n’impose pas de respecter les conven-

tions définies par le style REST

Possibilité d’utiliser une requête HTTP de type GET pour effectuer une
suppression d’une ressource

Des opérations CRUD sur des ressources sont réalisées au

travers des méthodes HTTP
/books
GET : récupère la liste de tous les livres
POST : créer un nouveau livre

Requêtes HTTP /books/{id}

GET : récupère un livre
GET,
PUT : mise à jour d’un livre
POST,
DELETE : effacer un livre
PUT et Serveur Web
DELETE Conteneur de Servlets

35
 @GET, @POST, @PUT, @DELETE : Méthodes HTTP

Exemple : CRUD sur la ressource Livre

@Path("/books")
public class BookResource { Récupère la liste de tous les livres
@GET
public String getBooks() {
return "Cuisine et moi / JavaEE 18";
}
@POST
Créer un nouveau livre
public String createBook(String livre) {
return livre;
}
@GET
@Path("{id}") Récupère un livre
public String getBookById(@PathParam("id") int id) {
return "Java For Life " + id;
}
@PUT
@Path("{id}") Mise à jour d’un livre
public void updateBookById(@PathParam("id") int id) {
...
}
@DELETE
@Path("{id}") Effacer un livre
public void deleteBookById(@PathParam("id") int id) {
...
}
}

[Link] du projet
LibraryRestWebService 36
 Paramètres de requêtes

JAX-RS fournit des annotations pour extraire des paramètres

d’une requête

Elles sont utilisées sur les paramètres des méthodes des
ressources pour réaliser l’injection du contenu

Liste des différentes annotations disponibles

@PathParam : extraire les valeurs des Template Parameters

@QueryParam : extraire les valeurs des paramètres de requête

@FormParam : extraire les valeurs des paramètres de formulaire

@HeaderParam : extraire les paramètres de l’en-tête

@CookieParam : extraire les paramètres des cookies

@Context : extraire les informations liées aux ressources de contexte
37
 Paramètres de requêtes : fonctionnalités communes

Une valeur par défaut peut être spécifiée en utilisant

l’annotation @DefaultValue

Par défaut, JAX-RS décode tous les paramètres, la résolution

de l’encodage se fait par l’annotation @Encoded

Les annotations peuvent être utilisées sur les types Java

suivants

Les types primitifs sauf char et les classes qui les encapsulent

Toutes classes ayant un constructeur avec paramètre de type String

Toutes classes ayant la méthode statique valueOf(String)

List<T>, Set<T> et SortedSet<T>

38
 Paramètres de requêtes : @PathParam

L’annotation @PathParam est utilisée pour extraire les valeurs

des paramètres contenues dans les Template Parameters

Exemple
@Path("/books")
public class BookResource { /books/123/path1/path2/editor
...
Injecte les valeurs dans les
@GET paramètres de la méthode
@Path("{id}")
public String getBookById(@PathParam("id") int id) {
return "Java For Life " + id;
}
/books/name-sc2-editor-oreilly
@GET
@Path("name-{name}-editor-{editor}")
public String getBookByNameAndEditor(@PathParam("name") String name,
@PathParam("editor") String editor)
return "Starcraft 2 for Dummies (Name:" + name + " - Editor:" + editor + ")";
}
}

[Link] du projet
LibraryRestWebService 39
 Paramètres de requêtes : @QueryParam

L’annotation @QueryParam est utilisée pour extraire les

valeurs des paramètres contenues d’une requête quelque soit
son type de méthode HTTP

Exemple
/books/queryparameters?name=harry&isbn=1-111111-11&isExtended=true

@Path("/books")
public class BookResource { Injection de valeurs par défaut
... si les valeurs des paramètres
@GET ne sont pas fournies
@Path("queryparameters")
public String getQueryParameterBook(
@DefaultValue("all") @QueryParam("name") String name,
@DefaultValue("?-???????-?") @QueryParam("isbn") String isbn,
@DefaultValue("false") @QueryParam("isExtended") boolean isExtented) {

return name + " " + isbn + " " + isExtented;

}
}

[Link] du projet
LibraryRestWebService 40
 Paramètres de requêtes : @FormParam

L’annotation @FormParam est utilisée pour extraire les

valeurs des paramètres contenues dans un formulaire

Le type de contenu doit être application/x-www-form-urlencoded

Cette annotation est très utile pour extraire les informations
d’une requête POST d’un formulaire HTML

Exemple
@Path("/books")
public class BookResource {
...
@POST
@Path("createfromform")
@Consumes("application/x-www-form-urlencoded")
public String createBookFromForm(@FormParam("name") String name) {
[Link]("[Link]()");

return name;
}
}

[Link] du projet
LibraryRestWebService 41
 Paramètres de requêtes : @HeaderParam

L’annotation @HeaderParam est utilisée pour extraire les

valeurs des paramètres contenues dans l’en-tête d’une
requête

Exemple

@Path("/books")
public class BookResource {
...
@GET
@Path("headerparameters")
public String getHeaderParameterBook(
@DefaultValue("all") @HeaderParam("name") String name,
@DefaultValue("?-???????-?") @HeaderParam("isbn") String isbn,
@DefaultValue("false") @HeaderParam("isExtended") boolean isExtented) {
return name + " " + isbn + " " + isExtented;
}
}

[Link] du projet
LibraryRestWebService 42
 Paramètres de requêtes : @Context

L’annotation @Context permet d’injecter des objets liés au

contexte de l’application

Les types d’objets supportés sont les suivants

UriInfo : informations liées aux URIs

Request : informations liées au traitement de la requête

HttpHeaders : informations liées à l’en-tête

SecurityContext : informations liées à la sécurité

Certains de ces objets permettent d’obtenir les mêmes infor-

mations que les précédentes annotations liées aux paramètres

43
 Paramètres de requêtes : @Context / UriInfo

Un objet de type UriInfo permet d’extraire les informations

« brutes » d’une requête HTTP

Les principales méthodes sont les suivantes

String getPath() : chemin relatif de la requête

MultivaluedMap<String, String> getPathParameters() : valeurs des
paramètres de la requête contenues dans Template Parameters

MultivaluedMap<String, String> getQueryParameters() : valeurs des
paramètres de la requête

URI getBaseUri() : chemin de l’application

URI getAbsolutePath() : chemin absolu (base + chemins)

URI getRequestUri() : chemin absolu incluant les paramètres

Nous reviendrons sur l’objet UriInfo pour

manipuler le constructeur d’URI (UriBuilder)
44
 Paramètres de requêtes : @Context / UriInfo

Exemple : accéder aux informations d’une requête via UriInfo

[Link]
@Path("/books")
public class BookResource { [Link] du projet
...
LibraryRestWebService
@GET
@Path("informationfromuriinfo/{name}")
public String getInformationFromUriInfo(@Context UriInfo uriInfo,
@PathParam("name") String name) {
[Link]("getPath(): " + [Link]());
List<PathSegment> pathSegments = [Link]();
...
MultivaluedMap<String, String> pathParameters = [Link]();
...
MultivaluedMap<String, String> queryParameters = [Link]();
...
[Link]("getAbsolutePath(): " + [Link]());
[Link]("getBaseUri(): " + [Link]());
[Link]("getRequestUri(): " + [Link]());
return ...;
}
}

45
 Paramètres de requêtes : @Context / HttpHeaders

Un objet de type HttpHeader permet d’extraire les informa-

tions contenues dans l’en-tête d’une requête

Les principales méthodes sont les suivantes

Map<String, Cookie> getCookies() : les cookies de la requête

Locale getLanguage() : le langue de la requête

MultivaluedMap<String, String> getRequestHeaders() : valeurs des

paramètres de l’en-tête de la requête

MediaType getMediaType() : le type MIME de la requête

A noter que ces méthodes permettent d’obtenir le même

résultat que les annotations @HeaderParam et @CookieParam
46
 Paramètres de requêtes : @Context / HttpHeaders

Exemple : accéder aux informations à l’en-tête

[Link]

@Path("/books")
public class BookResource {
...
@GET
@Path("informationfromhttpheaders/{name}")
public String getInformationFromHttpHeaders(@Context HttpHeaders httpheaders) {
Map<String, Cookie> cookies = [Link]();
Set<String> currentKeySet = [Link]();
for (String currentCookie : currentKeySet) {
[Link](currentCookie);
}

MultivaluedMap<String, String> requestHeaders = [Link]();

Set<String> requestHeadersSet = [Link]();
for (String currentHeader : requestHeadersSet) {
[Link](currentHeader);
}
return "";
}
}

[Link] du projet
LibraryRestWebService 47
 Représentations : @Consumes, @Produces

L’annotation @Consumes est utilisée pour spécifier le ou les

types MIME qu’une méthode d’une ressource peut accepter

L’annotation @Produces est utilisée pour spécifier le ou les
types MIME qu’une méthode d’une ressource peut produire

Possibilité de définir un ou plusieurs types MIME

Ces annotations peuvent portées sur une classe ou sur une
méthode

L’annotation sur la méthode surcharge celle de la classe

Si ces annotations ne sont pas utilisées tous types MIME

pourront être acceptés ou produits

La liste des constantes des différents type MIME est
disponible dans la classe MediaType 48
 Représentations : @Consumes, @Produces

Exemple : Gestion du type MIME

Requête
GET /books/details/12 HTTP/1.1
Host: localhost
Accept: text/html
Type MIME
accepté par le
client Le type MIME du contenu retourné s’accorde
par rapport à ce qui est supporté par le client

Réponse
HTTP/1.1 200 OK
Date: Wed, 05 January 2010 [Link] GMT
Server: Jetty(6.1.14)
Content-Type: text/html

Type MIME de la <html>

réponse <title>Details</title>
<body>
<h1>Ce livre est une introduction sur la vie</h1>
</body>
</html>

49
 Représentations : @Consumes, @Produces

Exemple (suite) : Gestion du type MIME

@Path("/books")
public class BookResource { [Link] du projet
... LibraryRestWebService
@GET
@Path("details/{id}")
Le chemin des trois
@Produces(MediaType.TEXT_PLAIN) méthodes est identique
public String getDetailTextBookId(@PathParam("id") String id) {
return "Ce livre est une introduction sur la vie";
}
@GET
@Path("details/{id}")
@Produces(MediaType.TEXT_XML)
public String getDetailXMLBookId(@PathParam("id") String id) {
return "<?xml version=\"1.0\"?>" + "<details>Ce livre est une introduction sur la
vie" + "</details>";
} Le choix de la méthode déclenchée dépend
@GET
du type MIME supporté par le client
@Path("details/{id}")
@Produces(MediaType.TEXT_HTML)
public String getDetailHTMLBookId(@PathParam("id") String id) {
return "<html> " + "<title>" + "Details" + "</title>" + "<body><h1>" + "Ce livre
est une introduction sur la vie" + "</body></h1>" + "</html> ";
}
}

50
 Gestion du contenu

Précédemment nous sommes focalisés sur les informations

contenues dans l’en-tête d’une requête

JAX-RS permet également de manipuler le contenu du corps
d’une requête et d’une réponse

JAX-RS peut automatiquement effectuer des opérations de
sérialisation et dé-sérialisation vers un type Java spécifique

*/* : byte[]

text/* : String

text/xml, application/xml, application/*+xml : JAXBElement

application/x-www-form-urlencoded : MultivalueMap<String,String>

Dans la suite nous montrerons des exemples côté serveur
qui illustrent la manipulation des types Java
Dans la partie cliente, nous montrerons
comment appeler ces services
51
 Gestion du contenu : InputStream

Exemple : Requête et réponse avec un flux d’entrée

@Path("/contentbooks")
public class BookResource {
@PUT
@Path("inputstream")
public void updateContentBooksWithInputStream(InputStream is) throws IOException {
byte[] bytes = readFromStream(is);
String input = new String(bytes);
[Link](input);
}
private byte[] readFromStream(InputStream stream) throws IOException {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
byte[] buffer = new byte[1000]; int wasRead = 0;
do {
wasRead = [Link](buffer);
if (wasRead > 0) { [Link](buffer, 0, wasRead); }
} while (wasRead > -1);
return [Link]();
}

@Path("inputstream")
@GET
@Produces(MediaType.TEXT_XML)
public InputStream getContentBooksWithInputStream() throws FileNotFoundException {
return new FileInputStream("c:\\[Link]");
}
}

[Link] du projet
LibraryContentRestWebService 52
 Gestion du contenu : File

Exemple : Requête et réponse avec un fichier

@Path("/contentbooks")
public class BookResource {
@Path("file")
@PUT
public void updateContentBooksWithFile(File file) throws IOException {
byte[] bytes = readFromStream(new FileInputStream(file));
String input = new String(bytes);
[Link](input);
} JAX-RS crée un fichier temporaire
@Path("file")
à partir du fichier donné
@GET
@Produces(MediaType.TEXT_XML)
public File getContentBooksWithFile() {
File file = new File("c:\\[Link]");
return file;
}

...
}

[Link] du projet
LibraryContentRestWebService
53
 Gestion du contenu : String

Exemple : Requête et réponse avec un String

@Path("/contentbooks")
public class BookResource {
@Path("string")
@PUT
public void updateContentBooksWithString(String current) throws IOException {
[Link](current);
}

@Path("string")
@GET
@Produces(MediaType.TEXT_XML)
public String getContentBooksWithString() {
return "<?xml version=\"1.0\"?>" + "<details>Ce livre est une introduction sur la vie" +
"</details>";
}
...
}

[Link] du projet
LibraryContentRestWebService
54
 Gestion du contenu : types personnalisés

Actuellement nous avons employé les types disponibles

fournis par Java

JAX-RS offre la possibilité d’utiliser directement des types
personnalisés en s’appuyant sur la spécification JAXB

JAXB est défini par la JSR 222

C’est une spécification qui permet de mapper des classes
Java en XML et en XML Schema

L’avantage est de pouvoir manipuler directement des objets
Java sans passer par une représentation abstraite XML

Chaque classe est annotée pour décrire la mapping entre
l’XML Schema et les informations de la classe

XmlRootElement, XmlElement, XmlType, … 55
 Gestion du contenu : types personnalisés

JAX-RS supporte la sérialisation et la dé-sérialisation de

classes qui sont

annotées par @XmlRootElement, @XmlType

« enveloppées » par un objet JAXBElement

La format du contenu d’une requête et d’une réponse peut

être représenté par de l’XML ou du JSON

Ces formes de contenu sont définies par les annotations
@Produces et @Consumes peuvent être

XML : text/xml, application/xml, application/*+xml

JSON : application/json

La manipulation de types personnalisés oblige de préciser

dans le service le type MIME à traiter et à retourner
56
 Gestion du contenu : types personnalisés

Exemple : mise à jour d’un livre (format XML)

@XmlRootElement(name = "book")
public class Book {
protected String name;
Annotation JAXB pour définir
protected String isbn;
l’élément racine de l’arbre XML
public String getName() {
return name;
}

public void setName(String name) {

[Link] = name;
}

public String getIsbn() {

return isbn;
}

public void setIsbn(String isbn) {

[Link] = isbn;
}

public String toString() {

return name; [Link] du projet
} LibraryContentRestWebService
}

57
 Gestion du contenu : types personnalisés

Exemple (suite) : mise à jour d’un livre (format XML)

@Path("/contentbooks")
public class BookResource {
@Path("jaxbxml")
@Consumes("application/xml")
@PUT
public void updateContentBooksWithJAXBXML(Book current) throws IOException {
[Link]("Name: " + [Link]() + ", ISBN: " + [Link]());
}

@Path("jaxbxml")
@GET
@Produces("application/xml")
public Book getContentBooksWithJAXBXML() {
Book current = new Book();
[Link]("123-456-789");
Le type MIME retourné par le
[Link]("Harry Toper"); service ce qui permet au client de
connaître le format à traiter
return current;
}

...
}

[Link] du projet
LibraryContentRestWebService 58
 Gestion du contenu : types personnalisés

Exemple : mise à jour d’un livre (JAXBElement et format XML)

[Link] du projet
LibraryContentRestWebService

@Path("/contentbooks")
public class BookResource {
Utilisation d’un objet JAXBElement pour
... envelopper le type Book
@Path("jaxbxml")
@Consumes("application/xml")
@POST
public void updateContentBooksWithJAXBElementXML(JAXBElement<Book> currentJAXBElemnt) {
Book current = [Link]();

[Link]("Name: " + [Link]() + ", ISBN: " + [Link]());

}
}

Accès direct à l’objet Book

59
 Gestion du contenu : statuts des réponses

Lors de l’envoie de la réponse au client un code statut est

retourné

Réponse sans erreur

Les statuts des réponses sans erreur s’échelonnent de 200 à 399

Le code est 200 « OK » pour les services retournant un contenu non
vide

Le code est 204 « No Content » pour les services retournant un
contenu vide

Réponse avec erreur

Les statuts des réponses avec erreur s’échelonnent de 400 à 599

Une ressource non trouvée, le code de retour est 404 « Not Found »

Un type MIME en retour non supporté, 406 « Not Acceptable »

Une méthode HTTP non supportée, 405 « Method Not Allowed »
60
 Response

Actuellement, tous les services développés retournaient soit

un type Void soit un type Java défini par le développeur

JAX-RS facilite la construction de réponses en permettant de

de choisir un code de retour

de fournir des paramètres dans l’en-tête

de retourner une URI, …

Les réponses complexes sont définies par la classe Response
disposant de méthodes abstraites non utilisables directement

Object getEntity() : corps de la réponse

int getStatus() : code de retour

MultivalueMap<String, Object> getMetaData() : données de l’en-tête

Les informations de ces méthodes sont obtenues par des
méthodes statiques retournant des ResponseBuilder

Utilisation du patron de conception Builder
JAX-RS - M. Baron - Page 61
 Response

Principales méthodes de la classe Response

ResponseBuilder created(URI location) : Modifie la valeur de Location
dans l’en-tête, à utiliser pour une nouvelle ressource créée

ResponseBuilder notModified() : Statut à « Not Modified »

ResponseBuilder ok() : Statut à « Ok »

ResponseBuilder serverError() : Statut à « Server Error »

ResponseBuilder status([Link]) : défini un statut
particulier défini dans [Link]

…

Principales méthodes de la classe ReponseBuilder

Response build() : crée une instance

ResponseBuilder entity(Object value) : modifie le contenu du corps

ResponseBuilder header(String, Object) : modifie un paramètre de
l’en-tête 62
 Response

Exemple : Préciser code retour et ajouter informations dans

l’en-tête de la réponse [Link] du projet
LibraryContentRestWebService

@Path("/contentbooks")
public class BookResource { Statut à OK
...
@Path("response")
@GET
public Response getBooks() {
return Response
.status([Link]) Trois paramètres
.header("param1", "Bonjour")
.header("param2", "Hello")
.header("server", "keulkeul")
.entity("Ceci est le message du coprs de la réponse")
.build();
}
}

Un contenu String
dans le coprs
Finalisation en appelant
la méthode build()
63
 Response

Exemple : Code de retour avec erreur dans la réponse

@Path("/contentbooks")
public class BookResource {
...
@Path("response")
@GET
public Response getBooks() {
return Response
.serverError()
.build();
}
}

[Link] du projet
LibraryContentRestWebService

Retour du message « Internal Server

Error » généré par le serveur lors
d’une erreur 500

64
 Response

Exemple : Retourner une URI lors de la création d’une

ressource [Link] du projet
LibraryContentRestWebService

@Path("/contentbooks")
public class BookResource {
...
@Consumes("application/xml")
@POST
@Path("response")
public Response createBooks(Book newBook, @Context UriInfo uri) {
URI absolutePath = [Link]();
return [Link](absolutePath).build();
}
}

Nous verrons dans la suite la

construction d’URI via UriBuilder

65
 UriBuilder

La classe utilitaire UriBuilder permet de construire des URIs

complexes

Possibilité de construire des URIs avec UriBuilder via

UriInfo (voir @Context) où toutes URIs seront relatives au chemin
de la requête

« From scratch » qui permet de construire une nouvelle URI

A partir d’un UriInfo les méthodes pour obtenir un UriBuilder

UriBuilder getBaseUriBuilder() : relatif au chemin de l’application

UriBuilder getAbsolutePathBuilder() : relatif au chemin absolu (base
+ chemins)

UriBuilder getRequestUriBuilder() : relatif au chemin absolu incluant
les paramètres
66
 UriBuilder

Le principe d’utilisation de la classe utilitaire UriBuilder est

identique à ResponseBuilder

Les principales méthodes

URI build(Object… values) : construit une URI à partir d’une liste de
valeurs pour les Template Parameters

UriBuilder queryParam(String name, Object…values) : ajoute des

paramètres de requête

UriBuilder path(String path) : ajout un chemin de requête

UriBuilder fromUri(String uri) : nouvelle instance à partir d’une URI

UriBuilder host(String host) : modifie l’URI de l’hôte

… 67
 UriBuilder

Exemple : Construire une URI à partir de la requête et la

retourner lors de la création d’une ressource

[Link] du projet
LibraryContentRestWebService

@Path("/contentbooks")
public class BookResource {
...
@Consumes("application/xml")
@POST
@Path("uribuilder1")
public Response createBooksFromURI(Book newBook, @Context UriInfo uri) {
URI absolutePath = uri
.getAbsolutePathBuilder() Création d’une URI
.queryParam("param1", [Link]()) à partir du chemin
.path([Link]())
.build();
fourni de la requête
return [Link](absolutePath).build();
}
} Ajouter un paramètre

68
 UriBuilder

Exemple : Construire une URI et la retourner lors de la

création d’une ressource

[Link] du projet
LibraryContentRestWebService

@Path("/contentbooks")
public class BookResource {
...
@Consumes("application/xml")
@POST
@Path("uribuilder2")
public Response createURIBooks(Book newBook, @Context UriInfo uri) {
URI build = UriBuilder
.fromUri("[Link]
.path("path1")
.path("path2")
[Link] du projet
.build(); LibraryContentRestWebService
return [Link](build).build();
}

69
 Déploiement

Les applications JAX-RS sont construites et déployées sous le

format d’une application Web Java (WAR)

La configuration de JAX-RS déclarer les classes ressources
dans le fichier de déploiement ([Link])

Deux types de configuration sont autorisées

[Link] pointe sur une sous classe d’Application

[Link] pointe sur une Servlet fournie par l’implémentation JAX-RS

La classe Application permet de décrire les classes ressources

Set<Class> getClasses() : classes des ressources

Set<Object> getSingletons() : instances des ressources

Application fournit une implémentation à vide, la classe

PackageResourceConfig fournit une implémentation complète70
 Déploiement

Exemple : Déclaration des classes ressources via la Servlet

fournie par l’implémentation de JERSEY
Servlet fournie par Jersey pour le
traitement des requêtes HTTP

<?xml version="1.0" encoding="UTF-8"?>

<web-app version="2.5" ...>
<display-name>HelloWorldRestWebService</display-name>
<servlet>
<servlet-name>HelloWorldServletAdaptor</servlet-name>
<servlet-class>[Link]</servlet-class>
<init-param>
<param-name>[Link]</param-name>
<param-value>[Link]</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>HelloWorldServletAdaptor</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

[Link] du projet
HelloWorldRestWebService
71
 Déploiement

Exemple : Déclaration des classes ressources via Application

public class LibraryRestWebServiceApplication extends Application {
@Override
public Set<Class<?>> getClasses() { LibraryRestWebServiceApplication
Set<Class<?>> classes = new HashSet<Class<?>>();
[Link]([Link]);
du projet
return classes; LibraryRestWebService
}
}
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" ...>
<display-name>HelloWorldRestWebService</display-name>
<servlet>
<servlet-name>HelloWorldServletAdaptor</servlet-name>
<servlet-class>[Link]</servlet-class>
<init-param>
<param-name>[Link]</param-name>
<param-value>
[Link]
</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>HelloWorldServletAdaptor</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

[Link] du projet
LibraryRestWebService 72
 Web Service Rest avec Java6

JAX-RS peut être utilisée avec Java 6 (JAR) sans avoir à

déployer une application Web (WAR)

A la différence de JAX-WS l’implémentation JERSEY nécessite
l’ajout d’un serveur WEB en mode embarqué

Grizzly écouteur HTTP en NIO

Usages

Fournir des Services Web à une application type client lourd

Pour les tests unitaires, fournir des Mock de Services Web

Le développement des services Web reste identique

L’appel des services Web (client) ne nécessite pas de
configuration particulière 73
 Web Service Rest avec Java6

Exemple : Utiliser JAX-RS avec Java 6

@Path("/hello")
public class HelloWorldResource {

@GET
@Produces("text/plain")
public String getHelloWorld() {
return "Hello World from text/plain";
}
}

[Link] du projet
HelloWorldRestWebServiceFromJavaSE

public class HelloWorldRestWebServiceApplication extends Application {

@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> classes = new HashSet<Class<?>>();
[Link]([Link]);

return classes;
}
}

[Link] du projet
HelloWorldRestWebServiceFromJavaSE
74
 Web Service Rest avec Java6

Exemple (suite) : Utiliser JAX-RS avec Java 6

public class HelloWorldResourceTest {

protected SelectorThread st;

@After
public void tearDown() {
if (st != null) [Link]();
Création d’une instance de la
} sous classe Application
@Test
public void testDoGetWithApplication() throws ... {
Application app = new HelloWorldRestWebServiceApplication(); Création d’un point d’entrée pour
accéder aux classes ressources
RuntimeDelegate rd = [Link]();
Adapter a = [Link](app, [Link]);
st = [Link]([Link]("[Link] a);

... // Partie cliente, détaillée dans la suite

}
Création d’une instance du
private static URI getBaseURI() {
return [Link]("[Link] serveur Web
}
}

[Link] du projet
HelloWorldRestWebServiceFromJavaSE
75
 Développement Client

La spécification JAX-RS ne s’intéresse pas à fournir une API

pour le traitement côté client

A voir du côté des implémentations JAX-RS si une API cliente
est fournie ou pas (JERSEY en propose une)

Possibilité également d’utiliser des bibliothèques spécialisées
dans l’envoi et la réception de requêtes HTTP

L’utilisation de l’API cliente ne suppose pas que les services
Web soient développés avec JAX-RS (.NET, PHP, …)

Les avantages d’utiliser l’API cliente de JERSEY

Manipuler les types Java (pas de transformation explicite en XML)

Facilite l’écriture des tests unitaires
76
 Développement Client : l’initialisation

Initialisation du client
Client c = [Link]();

Configuration du client
[Link]().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);

Ou
[Link](true);

Ou
ClientConfig cc = new DefaultClientConfig();
[Link]().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
Client c = [Link](cc);

Création d’une instance WebResource

WebResource r = [Link]("[Link]

A partir de cet objet possibilité

de fabriquer la requête
77
 Développement Client : la création de la requête

La création de la requête s’appuie sur la patron Builder

Création d’une chaîne d’appel de méthodes dont le type de
retour est WebResource ou [Link]

La chaîne d’appel se termine par les méthodes correspondant
aux méthodes HTTP (GET, POST, …)

La classe [Link] contient les méthodes de
terminaison

<T> get(Class<T> c) : appelle méthode GET avec un type de retour T

<T> post(Class<T> c, Object entity) : appelle méthode POST en
envoyant un contenu dans la requête

<T> put(Class<T> c, Object entity) : appelle méthode PUT en
envoyant un contenu dans la requête

<T> delete(Class<T> c, Object entity) : appelle méthode DELETE en
envoyant un contenu dans la requête 78
 Développement Client : la création de la requête

La classe WebResource fournit des méthodes pour construire

l’en-tête de la requête

Principales méthodes de WebResource

WebResource path(String) : définition d’un chemin

WebResource queryParam(String key, String val) : paramètre requête

Builder accept(MediaType) : type supporté par le client

Builder header(String name, Object value) : paramètre en-tête

Builder cookie(Cookie cookie) : ajoute un cookie

… Méthodes de terminaison disponibles

Possibilité d’appeler plusieurs fois la même méthode

(exemple : header) 79
 Développement Client

Exemple : client pour récupérer un livre (GET)

public class BookResourceIntegrationTest {

@Test
public void testGetDetailsBookId() {
ClientConfig config = new DefaultClientConfig();
Client client = [Link](config);
WebResource service = [Link](getBaseURI());
// Get TEXT for application
[Link]("Ce livre est une introduction sur la vie",
[Link]("books").path("details").path("12")
.accept(MediaType.TEXT_PLAIN).get([Link]));
// Get XML for application
[Link]("<?xml version=\"1.0\"?><details>Ce livre est une introduction sur la
vie</details>",
[Link]("books").path("details").path("12")
.accept(MediaType.TEXT_XML).get([Link]));
// Get HTML for application
[Link]("<html><title>Details</title><body><h1>Ce livre est une introduction sur la
vie</h1></body></html>",
[Link]("books").path("details").path("12")
.accept(MediaType.TEXT_HTML).get([Link]));
}

private static URI getBaseURI() {

return [Link]("[Link]
}
}

[Link] du projet
LibraryRestWebService
80
 Développement Client

Exemple : client pour mettre à jour un livre (PUT)

public class BookResourceIntegrationTest {

@Test
public void testUpdateContentBooksWithJAXBXMLService() throws IOException {
ClientConfig config = new DefaultClientConfig();
Client client = [Link](config);
WebResource service = [Link](getBaseURI());

WebResource path = [Link]("contentbooks").path("jaxbxml");

Book current = new Book();
[Link]("123-456-789");
[Link]("Harry Toper");

[Link](current);
}

private static URI getBaseURI() {

return [Link]("[Link]
}
}

[Link] du projet
LibraryContentRestWebService
81
 Développement Client

Exemple : client manipulant un objet Response

public class BookResourceIntegrationTest {

@Test
public void testGetBooksService() {
ClientConfig config = new DefaultClientConfig();
Client client = [Link](config);
WebResource service = [Link](getBaseURI());

WebResource path = [Link]("contentbooks").path("response");

ClientResponse response = [Link]([Link]);

MultivaluedMap<String, String> headers = [Link]();

[Link]("Bonjour", [Link]("param1"));
[Link]("Hello", [Link]("param2"));
String entity = [Link]([Link]);
[Link]("Ceci est le message du coprs de la réponse", entity);
[Link]("Jetty(6.1.14)", [Link]("server"));
}

private static URI getBaseURI() {

return [Link]("[Link]
}
}

[Link] du projet
LibraryContentRestWebService
82
 Outils : Environnements de développement / Outils

Tous les environnements de développement de la plateforme

Java supportent JAX-RS

Eclipse

Netbeans

IntelliJ IDEA

Tous ces outils fournissent des assistants, des éditeurs XML

et des connecteurs pour serveurs d’application

Possibilité d’utiliser Maven pour faciliter l’intégration continue
des projets JAX-RS

Tous les serveurs d’application sont supportés (Tomcat,
JETYY, Glassfish, …)
83
 Bilan : Concepts à étudier

Gestion des exceptions

Mise en place de la sécurité

MessageBodyReader et MessageBodyWriter

Intégration de JAX-RS avec les EJBs

…

84