Jaxrs PDF

SOA Services Web REST
Dvelopper des Services Web REST

avec Java : JAX-RS
Mickal BARON - 2011
mailto:baron.mickael@gmail.com ou mailto:baron@ensma.fr
Licence
Creative Commons
Contrat Paternit
Partage des Conditions Initiales l'Identique
keulkeul.blogspot.com
2.0 France
http://creativecommons.org/licenses/by-sa/2.0/fr
JAX-RS - M. Baron - Page 2
Plan du cours
Gnralits JAX-RS
Premier service Web JAX-RS
Rappels HTTP (Requte et Rponse)
Dveloppement Serveur
Chemin de ressource @Path
Paramtres des requtes
Gestion du contenu, Response et UriBuilder

Dploiement
Dveloppement Client
Outils
Droulement du cours
Pdagogie du cours
Illustration avec de nombreux exemples qui sont disponibles
ladresse http://mbaron.developpez.com/soa/jaxrs
Des bulles daide tout au long du cours
Survol des principaux concepts en vitant une prsentation exhaustive
Logiciels utiliss
Navigateur Web, Eclipse 3.6, Tomcat 6, Maven 3
Exemples Maveniss indpendant de lenvironnement de dv.
Pr-requis
Ceci est une astuce
Schema XML, JAXB, Introduction Services Web
Remerciements
Djug
Ceci est une alerte

Ressources
Billets issus de Blog
zenoconsulting.wikidot.com/blog:1
blog.smile.fr/JAX-RS-le-specification-Java-pour-implementer-les-services-REST
blogs.sun.com/enterprisetechtips/entry/consuming_restful_web_services_with
www.touilleur-express.fr/2008/04/25/jsr-311-jax-rs-rest-une-histoire-de-restaurant/
eclipsedriven.blogspot.com/2010/12/writing-jax-rs-rest-api-server-with.html
blogs.sun.com/sandoz
Articles
www.oracle.com/technetwork/articles/javase/index-137171.html
wikis.sun.com/display/Jersey/Overview+of+JAX-RS+1.0+Features
jsr311.java.net/nonav/releases/1.1/index.html
en.wikipedia.org/wiki/JAX-RS
www.devx.com/Java/Article/42873
jcp.org/en/jsr/summary?id=311
www.vogella.de/articles/REST/article.html
www.infoq.com/articles/rest-introduction
download.oracle.com/javaee/6/tutorial/doc/giepu.html
docs.sun.com/app/docs/doc/820-4867/820-4867
Ressources (suite)
Articles (suite)
jersey.java.net/nonav/documentation/latest/user-guide.html
java.sun.com/developer/technicalArticles/WebServices/jax-rs/index.html
www.dotmyself.net/documentation/7.html
Prsentations
www.slideshare.net/caroljmcdonald/td09restcarol
www.slideshare.net/linkedin/building-consistent-restful-apis-in-a-highperformance-environment
www.slideshare.net/jugtoulouse/rest-nicolas-zozol-jug-toulouse-20100615
developers.sun.com/learning/javaoneonline/2008/pdf/TS-5425.pdf
Cours
jersey.java.net/nonav/documentation/latest/user-guide.html
Ressources : Bibliothque
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 : Aot 2010 - 536 pages - ISBN : 143022889X
RESTful Java Web Services

Auteur : Jose Sandoval
diteur : PACKT Publishing
Edition : Nov. 2009 - 256 pages - ISBN : 1847196462
Gnralits - Dveloppement de Services Web REST

Nous nous intressons dans ce cours au dveloppement des
services Web de type REST
Ct Serveur : code pour le traitement du service Web
Ct Client : code qui permet dappeler un service Web
La majorit des langages de programmation orients Web

supportent le dveloppement de services Web REST
Java, PHP, C#, C++,
Nous nous limitons au langage Java dans ce cours

Diffrents frameworks de dveloppement de Services Web
Ceux qui respectent la spcification JAX-RS (dtailler aprs)
Autres
AXIS 2 Apache (ws.apache.org/axis2)
Gnralits JAX-RS : la spcification

JAX-RS est lacronyme Java API for RESTful Web Services
Dcrite par la JSR 311 (jcp.org/en/jsr/summary?id=311)
Version courante de la spcification est la 1.1
Depuis la version 1.1, JAX-RS fait partie intgrante de la
spcification Java EE 6 au niveau de la pile Service Web
Cette spcification dcrit uniquement la mise en uvre de

services Web REST ct serveur
Le dveloppement des Services Web REST repose sur
lutilisation de classes Java et dannotations
Gnralits JAX-RS : les implmentations

Diffrentes implmentations de la spcification JAX-RS sont
disponibles
JERSEY : implmentation de rfrence fournie par Oracle
Site projet : jersey.java.net
CXF : fournie par Apache, la fusion entre XFire et Celtix

Site projet : cxf.apache.org
RESTEasy : fournie par JBoss

Site projet : www.jboss.org/resteasy
RESTlet : un des premiers framework implmentant REST

pour Java
Site projet : www.restlet.org
Gnralits JAX-RS : les implmentations

Comparaisons sur les performances des implmentations
java.dzone.com/articles/jax-rs-vendor-comparisons-part
www.infoq.com/news/2008/10/jaxrs-comparison
Comme la spcification JAX-RS ne dcrit pas la couche

cliente, chaque implmentation fournit une API spcifique
Dans la suite du support de cours nous utiliserons limplmentation de rfrence JERSEY
Version actuelle 1.4 respectant la spcification JAX-RS 1.1
Intgre dans Glassfish et limplmentation Java EE 6

Outils supports dans Netbeans
Description Maven (partie serveur)
groupId : com.sun.jersey
artifactId : jersey-server
version : 1.4
Gnralits JAX-RS : fonctionnement

Dveloppement de
clients dans des
langages diffrents
Description du Service Web permettant

de gnrer la partie cliente
WADL
Servlet
PHP
JAVA
HTTP
Serveur
Web
Conteneur Java
Classes JAVA annotes
implmentant le
service web
Diffrentes APIs
possibles pour la gestion
du client en Java
Couche Cliente
JAX-RS
Utilisation du Service
Web par envoie /
rception de contenu
HTTP
Approche Bottom / Up
.NET
Couche Serveur
Gnralits JAX-RS : Dveloppement

Le dveloppement de Services Web avec JAX-RS est bas
sur des POJO (Plain Old Java Object) en utilisant des
annotations spcifiques JAX-RS
Pas description requise dans des fichiers de configuration
Seule la configuration de la Servlet JAX-RS est requise
pour raliser le pont entre les requtes HTTP et les classes

Java annotes
Un Service Web REST est dploy dans une application Web
Gnralits JAX-RS : Dveloppement

Contrairement aux Services Web tendus il ny a pas de
possibilit de dvelopper un service REST partir du fichier
de description WADL
Seule lapproche Bottom / Up est disponible
Crer et annoter un POJO
Compiler, Dployer et Tester
Possibilit daccder au document WADL
Le fichier de description WADL est gnr automatiquement

par JAX-RS (exemple : http://host/context/application.wadl)
Plus tard nous verrons comment utilis WADL pour gnrer
la couche cliente
Le Premier Service Web JAX-RS

Exemple : Service Web REST HelloWorld
Dfinition dun chemin de ressource pour
associer une ressource hello une URI
@Path("/hello")
public class HelloWorldResource {
Lecture de la ressource
HelloWorld via une requte HTTP
de type GET
@GET
@Produces("text/plain")
public String getHelloWorld() {
return "Hello World from text/plain";
}
Le type MIME de la rponse est

de type text/plain
HelloWorldResource.java du projet
HelloWorldRestWebService

Exemple (suite) : Service Web REST HelloWorld
Envoie dune requte HTTP de type

GET demandant la lecture de la
ressource hello
Le retour est directement interprtable

depuis la navigateur puisquil sagit dun
type MIME reconnu
Plus tard, nous utiliserons des

outils qui facilitent lcriture de
requtes HTTP plus complexes
(POST, PUT, )

Structure dune application
Web classique Java
Le rle du fichier web.xml est de

dclarer la servlet JERSEY
index.html
web.xml
WEB-INF
HelloWorldRestWebService.war
classes
lib
Cette application Web contient

un service Web REST
HelloWorldResource.class
jersey-core-1.x.jar
jersey-server-1.x.jar
jsr311-api-1.0.jar
Les bibliothques ne sont pas

obligatoires dans le cas o le serveur
dapplication les intgre

Servlet fournie par Jersey pour le

traitement des requtes 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>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>fr.ensma.lisi.helloworldrestwebservice</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Dans la partie Dploiement
web.xml du projet
nous montrerons deux types

de configuration
Exemple file rouge : une bibliothque

Utilisation dun exemple reprsentatif pour la prsentation
des concepts de JAX-RS : une Bibliothque
Mise en place dun systme de CRUD
Bibliothque et livre sont des ressources
Description de lexemple
Une bibliothque dispose de livres
Possibilit dajouter, de mettre jour ou de supprimer un livre

Recherche dun livre en fonction de diffrents critres (ISBN, nom, )
Rcupration de donnes de types simples (String, Long, ) ou
structures
Diffrents formats de donnes (JSON, XML, )
Protocole HTTP : gnralits

Hyper Text Transfer Protocol v1.1
Protocole Client/Serveur sans tat
Impossibilit de conserver des informations issu du client
La conversation HTTP est initialise lorsque lURL est saisie

dans le navigateur
1 - le client ouvre la connexion avec le
serveur
2 - le client met une requte HTTP
3 - le serveur rpond au client

4 - la connexion est ferme
Serveur Web
Client WEB
Protocole HTTP : requte

Requte envoye par le client (navigateur) au serveur WWW
Document demand.
Fichier HTML, une
image, ...
Le type de mthode
de la requte GET,
POST, ...
Protocole HTTP
avec la version :
1.0 ou 1.1
<Mthode> <URI> HTTP/<Version>

[<Champ den-tte>:<Valeur>]
...
Ligne blanche
[corps de la requte pour la mthode Post]
Diffrentes informations
concernant le navigateur,
lutilisateur, ...
La ligne blanche
est obligatoire
Le corps de la requte uniquement si la mthode

est de type POST. Sont fournis les valeurs des
paramtres envoyes par un formulaire
Protocole HTTP : en-ttes de requte

Correspond aux formats de documents et aux paramtres
pour le serveur
Accept = types MIME accepts par le client (text/html, text/plain, )
Accept-Encoding = codage acceptes (compress, x-gzip, x-zip)
Accept-Charset = jeu de caractres prfr du client
Accept-Language = liste de langues (fr, en, de, )
Authorization = type dautorisation
BASIC nom:mot de passe (en base64)

Transmis en clair, facile dcrypter
Cookie = cookie retourn

From = adresse email de lutilisateur
...
Protocole HTTP : type de mthodes

Lorsquun client se connecte un serveur et envoie une
requte, cette requte peut-tre de plusieurs types, appels
mthodes
Requte de type GET
Pour extraire des informations (document, graphique, )
Intgre les donnes de formatage lURL (chane dinterrogation)
www.exemple.com/hello?key1=titi&key2=raoul&
Requte de type POST

Pour poster des informations secrtes, des donnes graphiques,
Transmis dans le corps de la requte
<Mthode> <URI> HTTP/<Version>
...
Ligne blanche
[corps de la requte pour la mthode Post]
Protocole HTTP : rponse

Rponse envoye par le serveur WWW au client (navigateur)
Protocole HTTP
avec la version :
1.0 ou 1.1
Statuts des rponses

HTTP. Lies une erreur
ou une russite : 200
Donne des
informations sur
le statut : OK
HTTP/<Version><Status><Commentaire Status>
Content-Type:<Type MIME du contenu>
...
Ligne blanche
Document
Type de contenu qui sera

retourn : text/html,
text/plain,
application/octet-stream
Diffrentes informations
concernant le serveur, ...
La ligne blanche
est obligatoire
Le document peut
contenir du texte non
format, du code HTML,
...
Protocole HTTP : en-ttes de rponse

Correspond aux informations concernant le serveur WWW
Accept-Ranges = accepte ou refus dune requte par intervalle
Age = anciennet du document en secondes
Server = information concernant le serveur qui retourne la rponse
WWW-Authenticate = systme dauthentification. Utiliser en couple
avec len-tte requte Authorization
ETag =
Location =
Protocole HTTP : statuts des rponses

Rponse du serveur au client <Status><Commentaire>
100-199 : Informationnel
100 : Continue (le client peut envoyer la suite de la requte),
200-299 : Succs de la requte client

200 : OK, 204 : No Content (pas de nouveau corps de rponse)
300-399 : Re-direction de la requte client

301 : Redirection, 302 : Moved Temporarily
400-499 : Erreur client

401 : Unauthorized, 404 : Not Found (ressource non trouve)
500-599 : Erreur serveur

503 : Service Unavailable (serveur est indisponible)
@Path
Une classe Java doit tre annote par @path pour quelle
puisse tre traite par des requtes HTTP
Lannotation @path sur une classe dfinit des ressources
appeles racines (Root Resource Class)
La valeur donne @path correspond une expression URI
relative au contexte de lapplication Web
http://localhost:8088/libraryrestwebservice/books
Adresse du
Serveur
Port
Contexte de
l'application WEB
Des informations sur la mise en place du

contexte dune application Web sont
disponibles dans le cours sur les Servlets
URI de la
ressource
@Path
Lannotation @path peut galement annoter des mthodes
de la classe (facultatif)
LURI rsultante est la concatnation de lexpression du
@path de la classe avec lexpression du @path de la mthode
Exemple
Requtes HTTP
de types GET
/books
@Path("/books")
public class BookResource {
@GET
public String getBooks() {
...
}
/books/borrowed
Serveur Web
BookResource.java du projet
LibraryRestWebService
@GET
@Path("/borrowed")
public String getBorrowedBooks() {
...
}
}
Conteneur de Servlets
@Path : Template Parameters

La valeur dfinie dans @path ne se limite pas seulement aux
expressions constantes
Possibilit de dfinir des expressions plus complexes appeles
Template Parameters
Pour distinguer une expression complexe dans la valeur du
@path, son contenu est dlimit 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 rgulires

Exemple : Rcuprer un livre par son identifiant
/books/123
@Path("/books")
...
@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

Exemple (bis) : Rcuprer un livre par son identifiant
/books/123/path1/path2/editor
@Path("/books")
...
@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
@Path : Sub-resource locator

Une sub-resource locator est une mthode qui doit respecter les exigences suivantes
Annote avec @Path
Non annote avec @GET, @POST, @PUT, @DELETE
Retourne une sous ressource (un type Object)
Lintrt dutiliser une mthode sub-resource locator est
de pouvoir dlguer vers une autre classe ressource

Le dveloppement dune sous ressource suit un schma
classique, pas dobligation de placer une ressource racine
Une mthode sub-resource locator supporte le
polymorphisme (retourne des sous types)
@Path : Sub-resource locator

Exemple : Appeler une mthode Sub-resource locator
@Path("/books")
...
@Path("specific")
public SpecificBookResource getSpecificBook() {
return new SpecificBookResource();
}
}
Mthode Sub-resource locator dont la sous

ressource est dfinie par SpecificBookResource
public class SpecificBookResource {
@GET
@Path("{id}")
public String getSpecificBookById(@PathParam("id") int id) {
return ".NET platform is Bad";
}
}
SpecificBookResource.java du projet
/books/specific/123
@GET, @POST, @PUT, @DELETE : Mthodes HTTP

Lannotation des mthodes Java permet de traiter de
requtes HTTP suivant le type de mthode (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 mthodes Java
Le nom des mthodes Java na pas dimportance puisque

cest lannotation employe qui prcise o se fera le traitement
Possibilit dtendre les annotations disponibles pour grer
diffrents type de mthode HTTP
Protocole WebDav (extension au protocole HTTP pour la gestion de
documents)
Mthodes supportes : PROPFIND, COPY, MOVE, LOCK, UNLOCK,

La spcification JAX-RS, nimpose pas de respecter les conventions dfinies par le style REST
Possibilit dutiliser une requte HTTP de type GET pour effectuer une
suppression dune ressource
Des oprations CRUD sur des ressources sont ralises au

travers des mthodes HTTP
/books
GET : rcupre la liste de tous les livres
POST : crer un nouveau livre
Requtes HTTP
GET,
POST,
PUT et
DELETE
/books/{id}
GET : rcupre un livre
PUT : mise jour dun livre
DELETE : effacer un livre
Serveur Web
Conteneur de Servlets

Exemple : CRUD sur la ressource Livre
@Path("/books")
@GET
public String getBooks() {
return "Cuisine et moi / JavaEE 18";
}
@POST
public String createBook(String livre) {
return livre;
}
@GET
@Path("{id}")
}
@PUT
@Path("{id}")
public void updateBookById(@PathParam("id") int id) {
...
}
@DELETE
@Path("{id}")
public void deleteBookById(@PathParam("id") int id) {
...
}
}
Rcupre la liste de tous les livres
Crer un nouveau livre
Rcupre un livre
Mise jour dun livre
Effacer un livre
Paramtres de requtes
JAX-RS fournit des annotations pour extraire des paramtres
dune requte
Elles sont utilises sur les paramtres des mthodes des
ressources pour raliser linjection du contenu
Liste des diffrentes annotations disponibles
@PathParam : extraire les valeurs des Template Parameters
@QueryParam : extraire les valeurs des paramtres de requte
@FormParam : extraire les valeurs des paramtres de formulaire

@HeaderParam : extraire les paramtres de len-tte
@CookieParam : extraire les paramtres des cookies
@Context : extraire les informations lies aux ressources de contexte
Paramtres de requtes : fonctionnalits communes

Une valeur par dfaut peut tre spcifie en utilisant
lannotation @DefaultValue
Par dfaut, JAX-RS dcode tous les paramtres, la rsolution
de lencodage se fait par lannotation @Encoded
Les annotations peuvent tre utilises sur les types Java
suivants
Les types primitifs sauf char et les classes qui les encapsulent
Toutes classes ayant un constructeur avec paramtre de type String
Toutes classes ayant la mthode statique valueOf(String)
List<T>, Set<T> et SortedSet<T>
Paramtres de requtes : @PathParam

Lannotation @PathParam est utilise pour extraire les valeurs
des paramtres contenues dans les Template Parameters
Exemple
@Path("/books")
...
/books/123/path1/path2/editor
@GET
@Path("{id}")
}
Injecte les valeurs dans les

paramtres de la mthode
/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 + ")";
}
}
Paramtres de requtes : @QueryParam

Lannotation @QueryParam est utilise pour extraire les
valeurs des paramtres contenues dune requte quelque soit
son type de mthode HTTP
Exemple
/books/queryparameters?name=harry&isbn=1-111111-11&isExtended=true
@Path("/books")
Injection de valeurs par dfaut
...
si les valeurs des paramtres
@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;
}
}
Paramtres de requtes : @FormParam

Lannotation @FormParam est utilise pour extraire les
valeurs des paramtres contenues dans un formulaire
Le type de contenu doit tre application/x-www-form-urlencoded
Cette annotation est trs utile pour extraire les informations
dune requte POST dun formulaire HTML
Exemple
@Path("/books")
...
@POST
@Path("createfromform")
@Consumes("application/x-www-form-urlencoded")
public String createBookFromForm(@FormParam("name") String name) {
System.out.println("BookResource.createBookFromForm()");
return name;
}
}
Paramtres de requtes : @HeaderParam

Lannotation @HeaderParam est utilise pour extraire les
valeurs des paramtres contenues dans len-tte dune
requte
Exemple
@Path("/books")
...
@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;
}
}
Paramtres de requtes : @Context

Lannotation @Context permet dinjecter des objets lis au
contexte de lapplication
Les types dobjets supports sont les suivants
UriInfo : informations lies aux URIs
Request : informations lies au traitement de la requte
HttpHeaders : informations lies len-tte

SecurityContext : informations lies la scurit
Certains de ces objets permettent dobtenir les mmes informations que les prcdentes annotations lies aux paramtres
Paramtres de requtes : @Context / UriInfo

Un objet de type UriInfo permet dextraire les informations
brutes dune requte HTTP
Les principales mthodes sont les suivantes
String getPath() : chemin relatif de la requte
MultivaluedMap<String, String> getPathParameters() : valeurs des
paramtres de la requte contenues dans Template Parameters
MultivaluedMap<String, String> getQueryParameters() : valeurs des

paramtres de la requte
URI getBaseUri() : chemin de lapplication

URI getAbsolutePath() : chemin absolu (base + chemins)
URI getRequestUri() : chemin absolu incluant les paramtres
Nous reviendrons sur lobjet UriInfo pour
manipuler le constructeur dURI (UriBuilder)
Paramtres de requtes : @Context / UriInfo

Exemple : accder aux informations dune requte via UriInfo
http://localhost:8088/libraryrestwebservice/books/informationfromuriinfo/test?toto=ddd
@Path("/books")
...
@GET
@Path("informationfromuriinfo/{name}")
public String getInformationFromUriInfo(@Context UriInfo uriInfo,
@PathParam("name") String name) {
System.out.println("getPath(): " + uriInfo.getPath());
List<PathSegment> pathSegments = uriInfo.getPathSegments();
...
MultivaluedMap<String, String> pathParameters = uriInfo.getPathParameters();
...
MultivaluedMap<String, String> queryParameters = uriInfo.getQueryParameters();
...
System.out.println("getAbsolutePath(): " + uriInfo.getAbsolutePath());
System.out.println("getBaseUri(): " + uriInfo.getBaseUri());
System.out.println("getRequestUri(): " + uriInfo.getRequestUri());
return ...;
}
}
Paramtres de requtes : @Context / HttpHeaders

Un objet de type HttpHeader permet dextraire les informations contenues dans len-tte dune requte
Les principales mthodes sont les suivantes
Map<String, Cookie> getCookies() : les cookies de la requte
Locale getLanguage() : le langue de la requte
MultivaluedMap<String, String> getRequestHeaders() : valeurs des
paramtres de len-tte de la requte
MediaType getMediaType() : le type MIME de la requte
A noter que ces mthodes permettent dobtenir le mme

rsultat que les annotations @HeaderParam et @CookieParam
Paramtres de requtes : @Context / HttpHeaders

Exemple : accder aux informations len-tte
http://localhost:8088/libraryrestwebservice/books/informationfromhttpheaders
@Path("/books")
...
@GET
@Path("informationfromhttpheaders/{name}")
public String getInformationFromHttpHeaders(@Context HttpHeaders httpheaders) {
Map<String, Cookie> cookies = httpheaders.getCookies();
Set<String> currentKeySet = cookies.keySet();
for (String currentCookie : currentKeySet) {
System.out.println(currentCookie);
}
MultivaluedMap<String, String> requestHeaders = httpheaders.getRequestHeaders();
Set<String> requestHeadersSet = requestHeaders.keySet();
for (String currentHeader : requestHeadersSet) {
System.out.println(currentHeader);
}
return "";
}
}
Reprsentations : @Consumes, @Produces

Lannotation @Consumes est utilise pour spcifier le ou les
types MIME quune mthode dune ressource peut accepter
Lannotation @Produces est utilise pour spcifier le ou les
types MIME quune mthode dune ressource peut produire
Possibilit de dfinir un ou plusieurs types MIME
Ces annotations peuvent portes sur une classe ou sur une
mthode
Lannotation sur la mthode surcharge celle de la classe
Si ces annotations ne sont pas utilises tous types MIME

pourront tre accepts ou produits
La liste des constantes des diffrents type MIME est
disponible dans la classe MediaType
JAX-RS - M. Baron - Page
48

Exemple : Gestion du type MIME
Requte
Type MIME
accept par le
client
GET /books/details/12 HTTP/1.1

Host: localhost
Accept: text/html
Le type MIME du contenu retourn saccorde

par rapport ce qui est support par le client
Rponse
HTTP/1.1 200 OK
Date: Wed, 05 January 2010 14:44:55 GMT
Server: Jetty(6.1.14)
Content-Type: text/html
Type MIME de la
rponse
<html>
<title>Details</title>
<body>
<h1>Ce livre est une introduction sur la vie</h1>
</body>
</html>
Exemple (suite) : Gestion du type MIME

@Path("/books")
...
@GET
Le chemin des trois
@Path("details/{id}")
mthodes est identique
@Produces(MediaType.TEXT_PLAIN)
public String getDetailTextBookId(@PathParam("id") String id) {
return "Ce livre est une introduction sur la vie";
}
@GET
@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 mthode dclenche dpend
@GET
du type MIME support par le client
@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> ";
}
}
Gestion du contenu
Prcdemment nous sommes focaliss sur les informations
contenues dans len-tte dune requte
JAX-RS permet galement de manipuler le contenu du corps
dune requte et dune rponse
JAX-RS peut automatiquement effectuer des oprations de
srialisation et d-srialisation vers un type Java spcifique
*/* : 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 ct serveur

qui illustrent la manipulation des types Java
Dans la partie cliente, nous montrerons
comment appeler ces services
Gestion du contenu : InputStream

Exemple : Requte et rponse avec un flux dentre
@Path("/contentbooks")
@PUT
@Path("inputstream")
public void updateContentBooksWithInputStream(InputStream is) throws IOException {
byte[] bytes = readFromStream(is);
String input = new String(bytes);
System.out.println(input);
}
private byte[] readFromStream(InputStream stream) throws IOException {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
byte[] buffer = new byte[1000]; int wasRead = 0;
do {
wasRead = stream.read(buffer);
if (wasRead > 0) { baos.write(buffer, 0, wasRead); }
} while (wasRead > -1);
return baos.toByteArray();
}
@Path("inputstream")
@GET
public InputStream getContentBooksWithInputStream() throws FileNotFoundException {
return new FileInputStream("c:\\example.xml");
}
}
LibraryContentRestWebService
Gestion du contenu : File

Exemple : Requte et rponse avec un fichier
@Path("file")
@PUT
public void updateContentBooksWithFile(File file) throws IOException {
byte[] bytes = readFromStream(new FileInputStream(file));
String input = new String(bytes);
System.out.println(input);
}
JAX-RS cre un fichier
@Path("file")
@GET
public File getContentBooksWithFile() {
File file = new File("c:\\example.xml");
return file;
}
temporaire
partir du fichier donn
...
}
Gestion du contenu : String

Exemple : Requte et rponse avec un String
@Path("string")
@PUT
public void updateContentBooksWithString(String current) throws IOException {
System.out.println(current);
}
@Path("string")
@GET
public String getContentBooksWithString() {
return "<?xml version=\"1.0\"?>" + "<details>Ce livre est une introduction sur la vie" +
"</details>";
}
...
}
Gestion du contenu : types personnaliss

Actuellement nous avons employ les types disponibles
fournis par Java
JAX-RS offre la possibilit dutiliser directement des types
personnaliss en sappuyant sur la spcification JAXB
JAXB est dfini par la JSR 222
Cest une spcification qui permet de mapper des classes

Java en XML et en XML Schema
Lavantage est de pouvoir manipuler directement des objets
Java sans passer par une reprsentation abstraite XML
Chaque classe est annote pour dcrire la mapping entre
lXML Schema et les informations de la classe
XmlRootElement, XmlElement, XmlType,

JAX-RS supporte la srialisation et la d-srialisation de
classes qui sont
annotes par @XmlRootElement, @XmlType
enveloppes par un objet JAXBElement
La format du contenu dune requte et dune rponse peut

tre reprsent par de lXML ou du JSON
Ces formes de contenu sont dfinies par les annotations

@Produces et @Consumes peuvent tre
XML : text/xml, application/xml, application/*+xml
JSON : application/json
La manipulation de types personnaliss oblige de prciser

dans le service le type MIME traiter et retourner

Exemple : mise jour dun livre (format XML)
@XmlRootElement(name = "book")
public class Book {
protected String name;
protected String isbn;
Annotation JAXB pour dfinir

llment racine de larbre XML
public String getName() {

return name;
}
public void setName(String name) {
this.name = name;
}
public String getIsbn() {

return isbn;
}
public void setIsbn(String isbn) {
this.isbn = isbn;
}
public String toString() {
return name;
}
}
Book.java du projet

Exemple (suite) : mise jour dun livre (format XML)
@Path("jaxbxml")
@Consumes("application/xml")
@PUT
public void updateContentBooksWithJAXBXML(Book current) throws IOException {
System.out.println("Name: " + current.getName() + ", ISBN: " + current.getIsbn());
}
@Path("jaxbxml")
@GET
@Produces("application/xml")
public Book getContentBooksWithJAXBXML() {
Book current = new Book();
current.setIsbn("123-456-789");
current.setName("Harry Toper");
return current;
Le type MIME retourn par le

service ce qui permet au client de
connatre le format traiter
}
...
}

Exemple : mise jour dun livre (JAXBElement et format XML)
...
Utilisation dun objet JAXBElement pour

envelopper le type Book
@Path("jaxbxml")
@POST
public void updateContentBooksWithJAXBElementXML(JAXBElement<Book> currentJAXBElemnt) {
Book current = currentJAXBElemnt.getValue();
System.out.println("Name: " + current.getName() + ", ISBN: " + current.getIsbn());

}
}
Accs direct lobjet Book

Gestion du contenu : statuts des rponses

Lors de lenvoie de la rponse au client un code statut est
retourn
Rponse sans erreur
Les statuts des rponses sans erreur schelonnent 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
Rponse avec erreur

Les statuts des rponses avec erreur schelonnent de 400 599
Une ressource non trouve, le code de retour est 404 Not Found
Un type MIME en retour non support, 406 Not Acceptable
Une mthode HTTP non supporte, 405 Method Not Allowed
Response
Actuellement, tous les services dvelopps retournaient soit
un type Void soit un type Java dfini par le dveloppeur
JAX-RS facilite la construction de rponses en permettant de
de choisir un code de retour
de fournir des paramtres dans len-tte
de retourner une URI,
Les rponses complexes sont dfinies par la classe Response

disposant de mthodes abstraites non utilisables directement
Object getEntity() : corps de la rponse
int getStatus() : code de retour
MultivalueMap<String, Object> getMetaData() : donnes de len-tte
Les informations de ces mthodes sont obtenues par des

mthodes statiques retournant des ResponseBuilder
Utilisation du patron de conception Builder
JAX-RS
- M. Baron - Page 61
Response
Principales mthodes de la classe Response
ResponseBuilder created(URI location) : Modifie la valeur de Location
dans len-tte, utiliser pour une nouvelle ressource cre
ResponseBuilder notModified() : Statut Not Modified

ResponseBuilder ok() : Statut Ok
ResponseBuilder serverError() : Statut Server Error
ResponseBuilder status(Response.Status) : dfini un statut particulier
dfini dans Response.Status
Principales mthodes de la classe ReponseBuilder

Response build() : cre une instance
ResponseBuilder entity(Object value) : modifie le contenu du corps
ResponseBuilder header(String, Object) : modifie un paramtre de
len-tte
Response
Exemple : Prciser code retour et ajouter informations dans
len-tte de la rponse
Statut OK
...
@Path("response")
@GET
public Response getBooks() {
return Response
Trois paramtres
.status(Response.Status.OK)
.header("param1", "Bonjour")
.header("param2", "Hello")
.header("server", "keulkeul")
.entity("Ceci est le message du coprs de la rponse")
.build();
}
}
Un contenu String
dans le coprs
Finalisation en appelant
la mthode build()
Response
Exemple : Code de retour avec erreur dans la rponse
...
@Path("response")
@GET
public Response getBooks() {
return Response
.serverError()
.build();
}
}
Retour du message Internal Server

Error gnr par le serveur lors
dune erreur 500
Response
Exemple : Retourner une URI lors de la cration dune
ressource
...
@POST
@Path("response")
public Response createBooks(Book newBook, @Context UriInfo uri) {
URI absolutePath = uri.getAbsolutePath();
return Response.created(absolutePath).build();
}
}
Nous verrons dans la suite la

construction dURI via UriBuilder
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 requte
From scratch qui permet de construire une nouvelle URI
A partir dun UriInfo les mthodes pour obtenir un UriBuilder

UriBuilder getBaseUriBuilder() : relatif au chemin de lapplication

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

les paramtres
UriBuilder
Le principe dutilisation de la classe utilitaire UriBuilder est
identique ResponseBuilder
Les principales mthodes
URI build(Object values) : construit une URI partir dune liste de
valeurs pour les Template Parameters
UriBuilder queryParam(String name, Objectvalues) : ajoute des
paramtres de requte
UriBuilder path(String path) : ajout un chemin de requte

UriBuilder fromUri(String uri) : nouvelle instance partir dune URI
UriBuilder host(String host) : modifie lURI de lhte
UriBuilder
Exemple : Construire une URI partir de la requte et la
retourner lors de la cration dune ressource
...
@POST
@Path("uribuilder1")
public Response createBooksFromURI(Book newBook, @Context UriInfo uri) {
URI absolutePath = uri
.getAbsolutePathBuilder()
.queryParam("param1", newBook.getName())
.path(newBook.getIsbn())
.build();
return Response.created(absolutePath).build();
}
}
Ajouter un paramtre
Cration dune URI

partir du chemin
fourni de la requte
UriBuilder
Exemple : Construire une URI et la retourner lors de la
cration dune ressource
...
@POST
@Path("uribuilder2")
public Response createURIBooks(Book newBook, @Context UriInfo uri) {
URI build = UriBuilder
.fromUri("http://www.mylocalhost")
.path("path1")
.path("path2")
.build();
return Response.created(build).build();
}
Dploiement
Les applications JAX-RS sont construites et dployes sous le
format dune application Web Java (WAR)
La configuration de JAX-RS dclarer les classes ressources
dans le fichier de dploiement (web.xml)
Deux types de configuration sont autorises
web.xml pointe sur une sous classe dApplication
web.xml pointe sur une Servlet fournie par limplmentation JAX-RS
La classe Application permet de dcrire les classes ressources

Set<Class> getClasses() : classes des ressources
Set<Object> getSingletons() : instances des ressources
Application fournit une implmentation vide, la classe

PackageResourceConfig fournit une implmentation
complte
JAX-RS - M. Baron - Page
70
Dploiement
Exemple : Dclaration des classes ressources via la Servlet
fournie par limplmentation de JERSEY
Servlet fournie par Jersey pour le

traitement des requtes HTTP
<servlet>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>fr.ensma.lisi.helloworldrestwebservice</param-value>
</init-param>
</servlet>
<servlet-mapping>
</servlet-mapping>
</web-app>
web.xml du projet
Dploiement
Exemple : Dclaration des classes ressources via Application
public class LibraryRestWebServiceApplication extends Application {

@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> classes = new HashSet<Class<?>>();
classes.add(BookResource.class);
return classes;
}
}
LibraryRestWebServiceApplication
du projet

<servlet>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>
fr.ensma.lisi.libraryrestwebservice.LibraryRestWebServiceApplication
</param-value>
</init-param>
</servlet>
<servlet-mapping>
</servlet-mapping>
</web-app>
web.xml du projet
Web Service Rest avec Java6

JAX-RS peut tre utilise avec Java 6 (JAR) sans avoir
dployer une application Web (WAR)
A la diffrence de JAX-WS limplmentation JERSEY ncessite
lajout dun 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 dveloppement des services Web reste identique

Lappel des services Web (client) ne ncessite pas de
configuration particulire

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";
}
}
HelloWorldResource.java du projet
HelloWorldRestWebServiceFromJavaSE
public class HelloWorldRestWebServiceApplication extends Application {

@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> classes = new HashSet<Class<?>>();
classes.add(HelloWorldResource.class);
return classes;
}
}
HelloWorldRestWebServiceApplication.java du projet

Exemple (suite) : Utiliser JAX-RS avec Java 6
public class HelloWorldResourceTest {
protected SelectorThread st;
@After
public void tearDown() {
if (st != null) st.stopEndpoint();
}
@Test
public void testDoGetWithApplication() throws ... {
Application app = new HelloWorldRestWebServiceApplication();
Cration dune instance de la

sous classe Application
Cration dun point dentre pour
accder aux classes ressources
RuntimeDelegate rd = RuntimeDelegate.getInstance();
Adapter a = rd.createEndpoint(app, Adapter.class);
st = GrizzlyServerFactory.create(UriBuilder.fromUri("http://127.0.0.1:8084/").build(), a);
... // Partie cliente, dtaille dans la suite
}
private static URI getBaseURI() {
return UriBuilder.fromUri("http://127.0.0.1:8084/").build();
}
Cration dune instance du

serveur Web
HelloWorldResourceTest.java du projet
Dveloppement Client
La spcification JAX-RS ne sintresse pas fournir une API
pour le traitement ct client
A voir du ct des implmentations JAX-RS si une API cliente
est fournie ou pas (JERSEY en propose une)
Possibilit galement dutiliser des bibliothques spcialises
dans lenvoi et la rception de requtes HTTP
Lutilisation de lAPI cliente ne suppose pas que les services

Web soient dvelopps avec JAX-RS (.NET, PHP, )
Les avantages dutiliser lAPI cliente de JERSEY
Manipuler les types Java (pas de transformation explicite en XML)
Facilite lcriture des tests unitaires
Dveloppement Client : linitialisation

Initialisation du client
Client c = Client.create();
Configuration du client
c.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
Ou
c.setFollowRedirects(true);
Ou
ClientConfig cc = new DefaultClientConfig();

cc.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
Client c = Client.create(cc);
Cration dune instance WebResource

WebResource r = c.resource("http://localhost:8080/xyz");
A partir de cet objet possibilit

de fabriquer la requte
Dveloppement Client : la cration de la requte

La cration de la requte sappuie sur la patron Builder
Cration dune chane dappel de mthodes dont le type de
retour est WebResource ou WebResource.Builder
La chane dappel se termine par les mthodes correspondant
aux mthodes HTTP (GET, POST, )
La classe WebResource.Builder contient les mthodes de
terminaison
<T> get(Class<T> c) : appelle mthode GET avec un type de retour T

<T> post(Class<T> c, Object entity) : appelle mthode POST en
envoyant un contenu dans la requte
<T> put(Class<T> c, Object entity) : appelle mthode PUT en

<T> delete(Class<T> c, Object entity) : appelle mthode DELETE en

Dveloppement Client : la cration de la requte

La classe WebResource fournit des mthodes pour construire
len-tte de la requte
Principales mthodes de WebResource
WebResource path(String) : dfinition dun chemin
WebResource queryParam(String key, String val) : paramtre requte
Builder accept(MediaType) : type support par le client
Builder header(String name, Object value) : paramtre en-tte

Builder cookie(Cookie cookie) : ajoute un cookie
Mthodes de terminaison disponibles
Possibilit dappeler plusieurs fois la mme mthode

(exemple : header)
Dveloppement Client
Exemple : client pour rcuprer un livre (GET)
public class BookResourceIntegrationTest {

@Test
public void testGetDetailsBookId() {
ClientConfig config = new DefaultClientConfig();
Client client = Client.create(config);
WebResource service = client.resource(getBaseURI());
// Get TEXT for application
Assert.assertEquals("Ce livre est une introduction sur la vie",
service.path("books").path("details").path("12")
.accept(MediaType.TEXT_PLAIN).get(String.class));
// Get XML for application
Assert.assertEquals("<?xml version=\"1.0\"?><details>Ce livre est une introduction sur la
vie</details>",
.accept(MediaType.TEXT_XML).get(String.class));
// Get HTML for application
Assert.assertEquals("<html><title>Details</title><body><h1>Ce livre est une introduction sur la
vie</h1></body></html>",
.accept(MediaType.TEXT_HTML).get(String.class));
}
return UriBuilder.fromUri("http://localhost:8088/libraryrestwebservice/").build();
}
}
BookResourceIntegrationTest.java du projet
Dveloppement Client
Exemple : client pour mettre jour un livre (PUT)
@Test
public void testUpdateContentBooksWithJAXBXMLService() throws IOException {
WebResource path = service.path("contentbooks").path("jaxbxml");
Book current = new Book();
current.setIsbn("123-456-789");
current.setName("Harry Toper");
path.put(current);
}

return UriBuilder.fromUri("http://localhost:8088/librarycontentrestwebservice/").build();
}
}
Dveloppement Client
Exemple : client manipulant un objet Response
@Test
public void testGetBooksService() {
WebResource path = service.path("contentbooks").path("response");
ClientResponse response = path.get(ClientResponse.class);
MultivaluedMap<String, String> headers = response.getHeaders();
Assert.assertEquals("Bonjour", headers.getFirst("param1"));
Assert.assertEquals("Hello", headers.getFirst("param2"));
String entity = response.getEntity(String.class);
Assert.assertEquals("Ceci est le message du coprs de la rponse", entity);
Assert.assertEquals("Jetty(6.1.14)", headers.getFirst("server"));
}
return UriBuilder.fromUri("http://localhost:8088/librarycontentrestwebservice/").build();
}
}
Outils : Environnements de dveloppement / Outils

Tous les environnements de dveloppement 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 dapplication

Possibilit dutiliser Maven pour faciliter lintgration continue
des projets JAX-RS
Tous les serveurs dapplication sont supports (Tomcat,
JETYY, Glassfish, )
Bilan : Concepts tudier

Gestion des exceptions
Mise en place de la scurit
MessageBodyReader et MessageBodyWriter
Intgration de JAX-RS avec les EJBs

Jaxrs PDF

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Jaxrs PDF

Enviado por

Direitos autorais:

Formatos disponíveis

SOA Services Web REST

Dvelopper des Services Web REST

Gestion du contenu, Response et UriBuilder

JAX-RS - M. Baron - Page 3

Exemples Maveniss indpendant de lenvironnement de dv.

Ceci est une astuce

Schema XML, JAXB, Introduction Services Web

Ceci est une alerte

JAX-RS - M. Baron - Page 5

JAX-RS - M. Baron - Page 6

Beginning JavaEE6 Platform With GlassFish 3

Auteur : Antonio Goncalves

RESTful Java Web Services

Gnralits - Dveloppement de Services Web REST

La majorit des langages de programmation orients Web

Nous nous limitons au langage Java dans ce cours

JAX-RS - M. Baron - Page 8

Gnralits JAX-RS : la spcification

Cette spcification dcrit uniquement la mise en uvre de

JAX-RS - M. Baron - Page 9

Gnralits JAX-RS : les implmentations

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

RESTEasy : fournie par JBoss

RESTlet : un des premiers framework implmentant REST

Gnralits JAX-RS : les implmentations

Comme la spcification JAX-RS ne dcrit pas la couche

Intgre dans Glassfish et limplmentation Java EE 6

JAX-RS - M. Baron - Page 11

Gnralits JAX-RS : fonctionnement

Description du Service Web permettant

JAX-RS - M. Baron - Page 12

Gnralits JAX-RS : Dveloppement

pour raliser le pont entre les requtes HTTP et les classes

Gnralits JAX-RS : Dveloppement

Possibilit daccder au document WADL

Le fichier de description WADL est gnr automatiquement

JAX-RS - M. Baron - Page 14

Le Premier Service Web JAX-RS

Le type MIME de la rponse est

JAX-RS - M. Baron - Page 15

Le Premier Service Web JAX-RS

Envoie dune requte HTTP de type

Le retour est directement interprtable

Plus tard, nous utiliserons des

JAX-RS - M. Baron - Page 16

Le Premier Service Web JAX-RS

Le rle du fichier web.xml est de

Cette application Web contient

Les bibliothques ne sont pas

Le Premier Service Web JAX-RS

Servlet fournie par Jersey pour le

nous montrerons deux types

Exemple file rouge : une bibliothque

Possibilit dajouter, de mettre jour ou de supprimer un livre

JAX-RS - M. Baron - Page 19

Protocole HTTP : gnralits

La conversation HTTP est initialise lorsque lURL est saisie

2 - le client met une requte HTTP

3 - le serveur rpond au client

JAX-RS - M. Baron - Page 20

Protocole HTTP : requte

<Mthode> <URI> HTTP/<Version>

Le corps de la requte uniquement si la mthode