RESTful Web Services

Developer's Guide

Sun Microsystems, Inc.

4150 Network Circle

Santa Clara, CA 95054

U.S.A.

Part No: 820–4867–11

April 2009

Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other

countries, exclusively licensed through X/Open Company, Ltd.

Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coee Cup logo, docs.sun.com, Enterprise JavaBeans, EJB, GlassFish, J2EE, J2SE, Java Naming and

Directory Interface, JavaBeans, Javadoc, JDBC, JDK, JavaScript, JavaServer, JavaServer Pages, JMX, JSP, JVM, MySQL, NetBeans, OpenSolaris, SunSolve, Sun

GlassFish, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. or its subsidiaries in the U.S. and other countries. All SPARC

trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing

SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK and Sun

TM

Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering eorts

designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY

IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO

THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright 2009 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés.

Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier,

et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis

et dans d'autres pays.

Cette distribution peut comprendre des composants développés par des tierces personnes.

Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l'Université de Californie. UNIX est une marque déposée aux

L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les eorts de

pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient

une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface

d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.

Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et

peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations nales, ou utilisateurs naux, pour des armes nucléaires,

des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou

réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités gurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière

non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui

sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spéciquement designés, sont rigoureusement interdites.

What Are RESTful Web Services? ........................................................................................................5

How Does Jersey Fit In? .........................................................................................................................6

Learning More About RESTful Web Services .....................................................................................6

Installing Jersey on GlassFish ................................................................................................................9

▼ Adding Jersey to GlassFish .............................................................................................................9

Installing Jersey in NetBeans .............................................................................................................. 10

Installing and Running the Jersey Sample Applications ................................................................. 10

Installing the Jersey Sample Applications ................................................................................. 10

The @Path Annotation and URI Path Templates ............................................................................ 16

More on URI Path Template Variables ..................................................................................... 17

Responding to HTTP Resources .......................................................................................................18

The Request Method Designator Annotations ........................................................................ 18

Using Entity Providers to Map HTTP Response and Request Entity Bodies ....................... 19

Using @Consumes and @Produces to Customize Requests and Responses ................................ 21

The @Produces Annotation ........................................................................................................ 21

The @Consumes Annotation ........................................................................................................ 22

▼ Deploying and Testing a Jersey Application using NetBeans IDE ......................................... 31

▼ Deploying and Testing a Jersey Application without NetBeans ............................................. 31

▼ Building and Running the Bookstore Application from a Terminal Window ..................... 51

▼ Building and Running the Bookstore Application from NetBeans IDE ............................... 51

to as Jersey.

RESTful web services are services that are built to work best on the web. Representational State

Transfer (REST) is an architectural style that species constraints, such as the uniform

interface, that if applied to a web service induce desirable properties, such as performance,

scalability, and modiability, that enable services to work best on the Web. In the REST

architectural style, data and functionality are considered resources, and these resources are

accessed using Uniform Resource Identiers (URIs), typically links on the web. The resources

RESTful web services typically map the four main HTTP methods to the operations they

perform : create, retrieve, update, and delete. The following table shows a mapping of HTTP

methods to the operations they perform.

TABLE 1–1 Mapping HTTP Methods to Operations Performed

CHAPTER 1

TM

CHAPTER 2

present) and ignore the response entity (if set). For OPTIONS, the Allow response header will be

set to the set of HTTP methods support by the resource. In addition Jersey will return a

document describing the resource.

Methods decorated with request method designators must return void, a Java programming

language type, or a javax.ws.rs.core.Response object. Multiple parameters may be extracted

from the URI using the PathParam or QueryParam annotations as described in

Request Parameters” on page 23

Entity providers supply mapping services between representations and their associated Java

types. There are two types of entity providers: MessageBodyReader and MessageBodyWriter.

For HTTP requests, the MessageBodyReader is used to map an HTTP request entity body to

method parameters. On the response side, a return value is mapped to an HTTP response entity

body using a MessageBodyWriter. If the application needs to supply additional metadata, such

java.io.Reader — All media types (*/*)

java.io.File — All media types (*/*)

javax.activation.DataSource — All media types (*/*)

javax.xml.transform.Source — XML types (text/xml, application/xml and

application/*+xml)

StreamingOutput — All media types (*/*), MessageBodyWriter only

if (i == null)

return rb.build();

lastModified(lastModified).tag(et).build();

}

By default, a resource class can respond to and produce all MIME media types of

representations specied in the HTTP request and response headers.

The @Produces annotation is used to specify the MIME media types or representations a

resource can produce and send back to the client. If @Produces is applied at the class level, all

the methods in a resource can produce the specied MIME types by default. If it is applied at the

method level, it overrides any @Produces annotations applied at the class level.

If no methods in a resource are able to produce the MIME type in a client request, the Jersey

runtime sends back an HTTP “406 Not Acceptable” error.

The value of @Produces is an array of String of MIME types. For example:

public String doGetAsPlainText() {

...

The following example shows how to apply @Consumes at both the class and method levels:

public class SomeResource {

public String doPost2(FormURLEncodedProperties formData) {

}

}

The doPost method defaults to the MIME media type of the @Consumes annotation at the class

level. The doPost2 method overrides the class level @Consumes annotation to specify that it can

accept URL-encoded form data.

If no resource methods can respond to the requested MIME type, an HTTP 415 error

(Unsupported Media Type) is returned to the client.

The HelloWorld example discussed previously in this section can be modied to set the cliched

}