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

@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 l’URI /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.

l’URI

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)

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

L’exemple 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 l’URI /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 qu’objets complexes

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

JAX-RS et JAXB

JAX-RS permet l’utilisation d’objets JAXB afin de manipuler des données en XML. Voici un exemple :

Méthodes HTTP à travers les annotations

L’annotation 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 n’a pas d’importance puisque c’est l’annotation 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, n’impose pas de respecter les conventions définies par le style REST. Il est possible donc d’utiliser 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

d’une 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 d’une requête. Elles sont utilisées sur les paramètres des méthodes des ressources pour réaliser l’injection 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 l’en-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 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.

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>

L’annotation @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;

}

} L’annotation @QueryParam est utilisée pour extraire les valeurs des paramètres contenues d’une 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 d’URI 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

} 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) { System.out.println("BookResource.createBookFromForm()");

return name;

}

} 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

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

isExtented) { }

} 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 informations que les précédentes annotations liées aux paramètres.

Un objet de type UriInfo permet d’extraire les informations « brutes » d’une 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 l’application - URI getAbsolutePath() : chemin absolu (base + chemins) - URI getRequestUri() : chemin absolu incluant les paramètres

Exemple : accéder aux informations d’une 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 d’extraire les informations 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’entê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.

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

}

}

L’annotation @Consumes est utilisée pour spécifier le ou les 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. 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. 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 types MIME est disponible dans la classe MediaType. Exemple : Gestion de type MIME

types MIME qu’une 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é s’accorde 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 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. 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 d’entré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é d’utiliser directement des types personnalisés en s’appuyant 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. 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, …

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 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, 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 d’un livre (format XML)

Dans cet exemple, l’annotation JAXB XmlRootElement(name = "book") définit l’élément racine de l’arbre 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; }

} L’URL /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 d’un livre (JAXBElement et format XML)

Dans cet exemple, un objet JAXBElement est utilisé pour envelopper le type Book. L’accès direct à l’objet 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 l’envoie 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 l’exemple qui suit nous exploitons le même objet Book qui est mappé un XSD grâce à JAXB. Cette approche permet donc d’utiliser 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 suivant :

{ "name":"JAX-RS", "isbn":"Queen size mattress" }

Pour utiliser à la fois XML et JSON : @Produces({"application/json","application/xml"). Sachant que par défaut c’est le rendu XML qui sera utilisé, dans ce cas il faut que le client spécifie dans le header de la requête http le format JSON : Accept: application/json

6. Réponse

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 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, qui dispose de méthodes abstraites non utilisables directement. La méthode Object getEntity() retourne le corps de la réponse, la méthode int getStatus() retourne un code et la méthode MultivalueMap<String, Object> getMetaData() retourne les données de l’en-tête. Les informations de ces méthodes sont obtenues par des méthodes statiques retournant des ResponseBuilder. Il est aussi possible d’utiliser un patron de conception Builder.

Les principales méthodes de la classe Response sont les suivantes :

- 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(Response.Status) : défini un statut particulier défini dans

Response.Status

- …

Les principales méthodes de la classe ReponseBuilder sont les suivantes :

- 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

19

Université Virtuelle de Tunis Développement Orienté Services Services Web avec JAX-RS

Exemple : Préciser le code de retour et ajouter des informations dans l’entête de la réponse.

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

@Path("response") @GET public Response getBooks() { return Response .status(Response.Status.OK) .header("param1", "Bonjour") .header("param2", "Hello") .entity(new Book("JAX-RS","1-1111-11