Développement des Services Web REST avec Java : JAX-RS

5

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

La requ te de type POST permet de poster des informations secr tes, des donn es graphiques,&

Elle est transmise dans le corps de la requ te.

POST /book.php HTTP/1.1

Host: www.biblio.com

User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.9.0.9)

Gecko/2009040821 Firefox/3.0.9 (.NET CLR 3.5.30729) FirePHP/0.2.4

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,/;q=0.8

Accept-Language: fr,fr-fr;q=0.8,en-us;q=0.5,en;q=0.3

Accept-Encoding: gzip,deflate

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7

Content-Type: application/x-www-form-urlencoded

Content-Length: 40

Keep-Alive: 300

Connection: keep-alive

title=SOA&author=Xavier

Fournier

Voici la structure r ponse qui peut tre envoy e par le serveur WWW au client :

HTTP/<Version><Status><Commentaire Status>

Content-Type:<Type MIME du contenu>

[<Champ den-t te>:<Valeur>] ...

Ligne blanche

Document

Nous remarquons la pr sence de la version du protocole HTTP, avec cette fois le statut de la

r ponse li e une erreur ou une r ussite (200) et des informations (Commentaire) sur le statut

OK. Le type de contenu retourn est notamment sp cifi (text/html, text/plain,

application/octet-stream) et enfin le document qui peut tre format dun code HTML ou

autre.

3. Annotations de JAX-RS

@Path

Une classe Java doit tre annot e par lannotation @path pour quelle puisse tre trait e par des

requ tes HTTP. Cette annotation d finit des ressources appel es racines (Root Resource Class).

La valeur donn e @path correspond une expression URI relative au contexte de lapplication

web.

Exemple : http://localhost:8080/libraryrestwebservice/books

• localhost : adresse du serveur
• 8080 : port

• libraryrestwebservice : contexte de lapplication web
• books : URI de la ressource

Lannotation @path peut galement annoter des m thodes de la classe. LURI r sultante est la

concat nation de lexpression du @path de la classe avec lexpression du @path de la m thode.

6

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

Par exemple, on peut invoquer les livres pr t s dune biblioth que travers lURI

/books/borrowed, comme le montre lexemple ci-dessous :

@Path("/books") public class

BookResource {

@GET

public String getBooks() {

...

}

@GET

@Path("/borrowed")

String getBorrowedBooks() {

...

}

}

Template parameters

public

La valeur d finie dans @path ne se limite pas seulement aux expressions constantes. Il est aussi

possibile 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 {&}.

Il est possible 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 Exemple :

@Path("/books/") public

class BookResource {

@GET

@Path("{id}")

public String getBookById(@PathParam("id") int id) {

return "SOA " + id;

}

@GET

@Path("name-{name}-editor-{editor}")

public String getBookByNameAndEditor(@PathParam("name") String name,

@PathParam("editor") String editor)

return "JAX-RS (Name:" + name + " - Editor:" + editor + ")";

}

}

Ainsi, on peut r cup rer un livre gr ce son identifiant (m thode getBookById) avec lURI

/books/123 par exemple. Comme il est possible de r cup rer un livre avec son nom et celui de

son diteur (m thode getBookByNameAndEditor) gr ce

/books/name-SOA-

editorDUNOD par exemple.

lURI

Sub-resource locator

Une sub-resource locator est une m thode qui doit respecter les exigences suivantes :

• Annot e avec @Path
• Non annot e avec @GET, @POST, @PUT, @DELETE

7

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

• Retourne une sous ressource (un type Object)

Lint r t dutiliser une m thode sub-resource locator est de pouvoir d l guer vers une autre

classe ressource. Le d veloppement dune sous ressource suit un sch ma classique, pas

dobligation de placer une ressource racine. Une m thode sub-resource locator supporte le

polymorphisme (retourne des sous types).

Lexemple suivant montre une m thode sub-resource locator (m thode getSpecificBook) dont

la sous ressource est d finie par SpecificBookResource. Il est donc possible de r cup rer un

livre de type SpecificBookResource avec son id, exemple travers lURI /books/specific/123.

@Path("/books/") public

class BookResource {

@Path("specific") public SpecificBookResource

getSpecificBook() {

SpecificBookResource();

return new

}

}

public class SpecificBookResource {

@GET

@Path("{id}")

public String getSpecificBookById(@PathParam("id") int id) {

return ".NET platform is Bad";

}

}

Traitement des donn es en tant quobjets complexes

JAX-RS peut traiter des objets complexes selon deux formats XML et JSON

JAX-RS et JAXB

JAX-RS permet lutilisation dobjets JAXB afin de manipuler des donn es en XML. Voici un

exemple :

M thodes HTTP travers les annotations

Lannotation des m thodes Java permet de traiter des 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 na pas dimportance puisque cest lannotation

employ e qui pr cise o se fera le traitement. Il est possible aussi d tendre les annotations

disponibles pour g rer diff rents type de m thode HTTP travers par exemple le protocole

WebDav (extension au protocole HTTP pour la gestion de documents) et les m thodes

support es : PROPFIND, COPY, MOVE, LOCK, UNLOCK, &

La sp cification JAX-RS, nimpose pas de respecter les conventions d finies par le style REST.

Il est possible donc dutiliser une requ te HTTP de type GET pour effectuer une suppression

8

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

dune ressource. Des op rations CRUD sur des ressources sont r alis es au travers des

m thodes HTTP.

Exemple : CRUD sur la ressource Livre

@Path("/books/") public

class BookResource {

@GET

public String getBooks() {

"Cuisine et moi / JavaEE 18";

return

}

@POST

public String createBook(String livre) {

return livre;

}

@GET

@Path("{id}")

public String getBookById(@PathParam("id") int id) {

return "Java For Life " + id;

}

@PUT

@Path("{id}")

public void updateBookById(@PathParam("id") int id) {

...

}

@DELETE

@Path("{id}")

public void deleteBookById(@PathParam("id") int id) {

...

}

}

Dans cet exemple, getBooks permet de r cup rer la liste de tous les livres, createBook cr e un

nouveau livre, getBooksById r cup re un livre, updateBooksById permet de mettre jour u livre

et deleteBookById supprime un livre.

4. Param tres de requ tes

JAX-RS fournit des annotations pour extraire des param tres dune requ te. Elles sont utilis es

sur les param tres des m thodes des ressources pour r aliser linjection du contenu. La liste des

diff rentes annotations disponibles est la suivante :

• @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 len-t te
• @CookieParam : extraire les param tres des cookies
• @Context : extraire les informations li es aux ressources de contexte

Une valeur par d faut peut tre sp cifi e en utilisant lannotation @DefaultValue. Par d faut,

JAX-RS d code tous les param tres, la r solution de lencodage se fait par lannotation

@Encoded.

9

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

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>

Lannotation @PathParam est utilis e pour extraire les valeurs des param tres contenues dans

les Template Parameters.

Exemple :

Dans cet exemple, la valeur de id est inject e dans la m thode getBookId pour r cup rer le livre

selon cet id.

@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 "Name:" + name + " - Editor:" + editor;

}

}

Lannotation @QueryParam est utilis e pour extraire les valeurs des param tres contenues

dune requ te quel que soit son type de m thode HTTP.

Exemple :

Dans cet exemple, des valeurs par d faut peuvent tre inject es si les valeurs des param tres ne

sont pas fournies. Un exemple dURI de cette ressource :

/books/queryparameters?name=SOA&isbn=1-111111-11&isExtended=false

@Path("/books/") public

class BookResource {

@GET

@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;

{

}

10

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

}

Lannotation @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 dune requ te POST dun formulaire

HTML.

Exemple :

@Path("/books/") public

class BookResource {

@POST

@Path("createfromform")

@Consumes("application/x-www-form-urlencoded")

public String createBookFromForm(@FormParam("name") String name) {

System.out.println("BookResource.createBookFromForm()");

return name;

}

}

Lannotation @HeaderParam est utilis e pour extraire les valeurs des param tres contenues

dans len-t te dune 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

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

isExtented) {

}

}

Lannotation @Context permet dinjecter des objets li s au contexte de lapplication. Les types

dobjets 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 len-t te
• SecurityContext : informations li es la s curit

Certains de ces objets permettent dobtenir les m mes informations que les pr c dentes

annotations li es aux param tres.

Un objet de type UriInfo permet dextraire les informations brutes dune requ te HTTP. Les

principales m thodes sont les suivantes :

11

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

• 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 lapplication
• URI getAbsolutePath() : chemin absolu (base + chemins)
• URI getRequestUri() : chemin absolu incluant les param tres

Exemple : acc der aux informations dune requ te via UriInfo

http://localhost:8080/restws/books/informationfromuriinfo/test?toto=ddd

@Path("/books/") public

class BookResource {

@GET

@Path("informationfromuriinfo/{name}")

getInformationFromUriInfo(@Context UriInfo uriInfo,

public String

@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 "";

}

}

Un objet de type HttpHeader permet dextraire les informations contenues dans len-t te dune

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

lent te de la requ te

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

A noter que ces m thodes permettent dobtenir le m me r sultat que les annotations

@HeaderParam et @CookieParam.

12

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

@Path("/books/") public

class BookResource {

@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);

}

httpheaders.getRequestHeaders();

MultivaluedMap<String, String> requestHeaders =

Set<String> requestHeadersSet = requestHeaders.keySet();

for (String currentHeader : requestHeadersSet) {

System. out .println(currentHeader);

}

return "" ;

}

}

Lannotation @Consumes est utilis e pour sp cifier le ou les

dune ressource peut accepter. Lannotation @Produces est utilis e pour sp cifier le ou les

types MIME quune m thode dune ressource peut produire. Il est possible de d finir un ou

plusieurs types MIME. Ces annotations peuvent tre port es sur une classe ou sur une

m thode. Lannotation 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 types MIME est disponible dans la classe MediaType.

Exemple : Gestion de type MIME

types MIME quune m thode

Type MIME accept par le client :

GET /books/details/12 HTTP/1.1

Host: localhost

Accept: text/html

Type MIME du contenu retourn saccorde par rapport ce qui est support par le client :

HTTP/1.1 200 OK

Date: Wed, 05 January 2010 14:44:55 GMT

Server: Jetty(6.1.14)

Content-Type: text/html

<html>

<title>Details</title>

<body>

13

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

<h1>Ce livre est une introduction sur la vie</h1>

</body> </html>

Dans le code qui suit, le chemin des trois m thodes est identique. Le choix de la m thode

d clench e d pend du type MIME support par le client :

@Path("/books/")

public class BookResource {

@GET

@Path("details/{id}")

@Produces(MediaType.TEXT_PLAIN)

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

return

String getDetailXMLBookId(@PathParam("id") String id) {

"<?xml version=\"1.0\"?>" + "<details>Ce livre est une

";

>

<

introduction sur la v ie " + "

/details

}

@ GET

@ Path( "details/{id}" )

@ Produces(M ediaType.TEXT_HTML)

public String getDetailHTMLBookId( @ PathParam( "id" ) String id) {

return "<html> " + "<title>" + "Details" + "</title>" + "<body><h1>"

+ "Ce livre e st une introduction sur la vie " + " /body></h 1>

" < /h tml> ";

<

" +

}

}

5. Gestion du contenu

Pr c demment nous sommes focalis s sur les informations contenues dans len-t te dune

requ te. JAX-RS permet galement de manipuler le contenu du corps dune requ te et dune

r ponse. Il peut ainsi 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.

Exemple : Requ te et r ponse avec un flux dentr e

14

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

@Path("/contentbooks/") public

class BookResource {

@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;

(wasRead > 0) { baos.write(buffer, 0, wasRead); }

wasRead = stream.read(buffer);

do {

if

} while (wasRead > -1);

return baos.toByteArray();

}

@Path("inputstream")

@GET

@Produces(MediaType.TEXT_XML)

public InputStream

getContentBooksWithInputStream() throws

FileNotFoundException {

return new FileInputStream( "c: \ \ example.xml" ) ;

}

}

Exemple : Requ te et r ponse avec un fichier

Dans cet exemple, JAX-RS cr e un fichier temporaire partir du fichier donn (m thode

getContentBooksWithFile)

@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);

System.out.println(input);

}

@Path("file")

@GET

@Produces(MediaType.TEXT_XML)

public File getContentBooksWithFile() {

File file = new File("c:\\example.xml");

return file;

15

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

}

}

Exemple : Requ te et r ponse avec un String

@Path("/contentbooks/") public

class BookResource {

@PUT

public void updateContentBooksWithString(String current) throws IOException

{

System.out.println(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>";

}

}

Actuellement nous avons employ les types disponibles fournis par Java. JAX-RS offre la

possibilit dutiliser directement des types personnalis s en sappuyant sur la sp cification

JAXB. Ce dernier JAXB est d fini par la JSR 222, qui est une sp cification permettant de

mapper des classes Java en XML et en XML Schema. Lavantage 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 lXML Schema et les informations de la classe :

XmlRootElement, XmlElement, XmlType, &

JAX-RS supporte la s rialisation et la d -s rialisation de classes qui sont annot es par

@XmlRootElement, @XmlType ou envelopp es par un objet JAXBElement. Le format du

contenu dune requ te et dune r ponse peut tre repr sent par de lXML ou du JSON. Ces

formes de contenu sont d finies par les annotations @Produces et @Consumes, qui peuvent

tre de type :

• 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.

JAX-RS et JAXB

Exemple : mise jour dun livre (format XML)

Dans cet exemple, lannotation JAXB XmlRootElement(name = "book") d finit l l ment

racine de larbre XML.

16

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

@XmlRootElement(name = "book")

@XmlAccessorType(XmlAccessType.FIELD) public

class Book {

@XmlElement

protected String name;

@XmlElement

protected String isbn;

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;

}

}

Dans la ressource BookResource, le type MIME retourn par le service (m thode

getContentBookWithJAXBXML) permet de conna tre le format traiter.

@Path("/contentbooks/") public class BookResource

{

@Path("jaxbxml")

@Consumes("application/xml")

@PUT

public void updateContentBooksWithJAXBXML(Book current) throws IOException

{

current.getIsbn());

System.out.println("Name: " + current.getName() + ", ISBN: " +

}

@Path("jaxbxml")

@GET

@Produces("application/xml")

public Book getContentBooksWithJAXBXML() {

Book current = new Book();

current.setIsbn("123-456-789");

current.setName("SOA");

return

current;

}

}

LURL /contentbooks/jaxbxml rend le r sultat suivant :

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

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

17

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

<xs:element name="book" type="book"/>

<xs:complexType name="book">

<xs:sequence>

<xs:element name="name" type="xs:string"/>

<xs:element name="isbn" type="xs:string"/>

</xs:sequence>

<xs:complexType>

</xs:schema>

Exemple : Mise jour dun livre (JAXBElement et format XML)

Dans cet exemple, un objet JAXBElement est utilis pour envelopper le type Book. Lacc s

direct lobjet Book se fait par la m thode getValue().

@Path("/contentbooks") public

class BookResource {

@Path("jaxbxml")

@Consumes("application/xml")

@POST

public void updateContentBooksWithJAXBElementXML(JAXBElement<Book>

currentJAXBElemnt) {

Book current = currentJAXBElemnt.getValue();

System.out.println("Name: " + current.getName() + ", ISBN: " +

current.getIsbn());

}

}

Lors de lenvoie de la r ponse au client un code statut est retourn . 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.

Pour les r ponses avec erreur, leurs statuts s chelonnent de 400 599. Pour une ressource non

trouv e, le code de retour est 404 Not Found . Pour un type MIME en retour non support ,

le code retourn est 406 Not Acceptable . Enfin pour une m thode HTTP non support e, le

code retourn est 405 Method Not Allowed .

JAX-RS et JSON

JAX-RS permet de manipuler des donn es en JSON gr ce des biblioth ques tierces telles

JAXB, Jackson,& Dans lexemple qui suit nous exploitons le m me objet Book qui est mapp

un XSD gr ce JAXB. Cette approche permet donc dutiliser le m me objet pour un rendu en

XML ou JSON :

@Path("/contentbooks/") public class

BookResource {@Path("jaxbxml")

@Path("jaxbjson")

@GET

18

Universit Virtuelle de Tunis D veloppement Orient Services

Services Web avec JAX-RS

@Produces("application/json")

public Book getContentBooksWithJAXBJSON() {

Book current = new Book();

current.setIsbn("123-456-789");

current.setName("SOA");

return

current;

}

}

Le rendu JSON est le su...