Home

Jersey 2.0-m13 User Guide

1. 47 Migrating from Jersey 1 x bind MyInjectablePerRequest class to MyInjectablePerRequest class in Req singleton binding bind MyInjectableSingleton class in Singleton class singleton instance binding bind new MyInjectableSingleton to MyInjectableSingleton class register module to ResourceConfig can be done also in constructor ResourceConfig rc new ResourceConfig rc addClasses rc addBinders new MyBinder Jersey 2 0 dynamic binding public static class MyApplication extends Application Inject public MyApplication ServiceLocator serviceLocator System out println Registering injectables DynamicConfiguration dc Injections getConfiguration serviceLocator request scope binding Injections addBinding Injections newBinder MyInjectablePerRequest class to MyInject dc singleton binding Injections addBinding Injections newBinder MyInjectableSingleton class to MyInjecta dc singleton instance binding Injections addBinding Injections newBinder new MyInjectableSingleton to MyInjecta dc request scope binding with specified custom annotation Injections addBinding Injections newBinder MyInjectablePerRequest class to MyInject qualifiedBy new MyAnnotationImpl in RequestScoped class dc commits changes dce commit Override public Set lt Class lt
2. m13 jersey com sun jersey api client filter GZIPContentEncodingFilter html If this filter is added then a request entity is compressed with the Content Encoding of gzip and a response entity if compressed with aContent Encoding of gzip is decompressed The filter declares an Accept Encoding of gzip 2 A logging filter LoggingFilter http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client filter LoggingFilter html If this filter is added then the request and response headers as well 33 Client API as the entities are logged to a declared output stream if present or to System out if not Often this filter will be placed at the end of the ordered list of filters to log the request before it is sent and the response after it is received The filters above are good examples that show how to modify or read request and response entities Refer to the source code https maven java net service local artifact maven redirect r releases amp g com sun jersey amp a jersey client amp v 2 0 m13 amp e jar of the Jersey client for more details 7 7 Testing services The Jersey client API was originally developed to aid the testing of the Jersey server side primarily to make it easier to write functional tests in conjunction with the JUnit framework for execution and reporting It is used extensively and there are currently over 1000 tests Embedded servers Grizzly and a special in memory server are util
3. 0 cece cee cc eecc ence ence eeeeeeeeeeeaeeeaes 11 3 16 Injection of more beans into one resource methods oooocccoccnnccnnconnconnconnconncnnacnnncnnncnnnonnss 12 3 17 Sub tesource methods rn site mecha see IR as 13 3 18 Sub resource locators snars eree 2 Er nn ER RR ini 14 3 19 Injection ee a a Ee Pokepmeneilishiesrrsrmejbsrrkessehsibsipernn et 15 4 1 Using File with a specific MIME type to produce a response cece cece eeeecneee eee een eens 17 4 2 Returning 201 status code and adding Location header in response to POST request 18 4 3 Adding an entity body to a custom response oocooccnncnnccnnccnnconnccnnccnnccnnconnconncnnncnnncnnncnnnonose 18 4 4 Throwing Jersey specific exceptions to control response ocoooccnccnnccnnccnnccnnconacnnccnnccnnccnninono 19 4 5 Jersey specific exception implementation oooccnoccnncnnocnnncnnncnnnonnnonoronncnnconnconncrnnccnncnnncnnncos 19 4 6 Mapping generic exceptions tO responses cece cece eee cece ee cece nace neceneeeeeeeeeeeeeaeeeaesenes 20 4 7 Conditional GET support lt gt n eserse e ernea E EEE EEES EEEE E E AEE ESEE 21 O 22 5 2 Building URIs using query parameters ooooccoccnnccnnccnnconnccnnconnconncnnncnnnnnnnnnnrnnnrnnccnnccnnccnnions 23 6 1 Deployment agnostic application model ussussunssenssnneennennnennnennnsennnnnnnennen nenn 24 6 2 Reusing Jersey implementation in your custom application model c
4. 5 Context UrilInfo ui 6 if data null 7 throw new WebApplicationException 400 8 9 this data data 10 11 this limits limits 12 13 if limits contains data 14 throw new WebApplicationException 400 15 16 this tag computeEntityTag ui getRequestUri 17 if request getMethod equals GET 18 Response ResponseBuilder rb request evaluatePreconditions tag 1 9 if rb null 20 throw new WebApplicationException rb build 21 22 The constructor of the Spark linesResouce root resource class computes an entity tag from the request URI and then calls the request evaluatePreconditions http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Request html evaluatePreconditions javax ws rs core EntityTag with that entity tag If a client request contains an If None Match header with a value that contains the same entity tag that was calculated then the evaluatePreconditions http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Request html evaluatePreconditions javax ws rs core EntityTag returns a pre filled out response with the 304 status code and entity tag set that may be built and returned Otherwise evaluatePreconditions http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Request html evaluatePreconditions javax ws rs core EntityTag returns null and the normal response can be returned Notice that in this example the constructor of a resou
5. For certificate based authentication see the class HTTPSProperties http jersey java net nonav apidocs latest jersey com sun jersey client urlconnection HTTPSProperties html for how to set javax net ssl HostnameVerifier and javax net ssl SSLContext With Apache HTTP client The support for HTTP authentication and cookies is much better with the Apache HTTP client than with HttpURLConnection See the Java documentation for the package com sun jersey client apache http jersey java net nonav apidocs 2 0 m13 contribs jersey apache client com sun jersey client apache package summary html ApacheHttpClientState http jersey java net nonav apidocs 2 0 m13 contribs jersey apache client com sun jersey client apache config ApacheHttpClientState html and ApacheHttpClientConfig http jersey java net nonav apidocs 2 0 m13 contribs jersey apache client com sun jersey client apache config ApacheHttpClientConfig html for more details 35 Chapter 8 Filters and Interceptors Chapter 9 Message Body Workers Chapter 10 Asynchronous Services and Clients Chapter 11 Programmatic API for Building Resources Chapter 12 Support for Common Media Types 12 1 JSON TODO Describe support for JSON various notations options 12 2 XML TODO Describe support for XML 12 3 Multipart TODO Describe support for multipart 40 Chapter 13 Support for Server Sent Events Chapter 14 Secur
6. difference and thus request URLs that end or do not end in a will both be matched JAX RS Application Resources and Sub Resources 3 1 2 GET PUT POST ODELETE HTTP Methods 3 1 3 GET _ http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs GET html PUT http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs PUT html EPOST http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs POST html DELETE _ http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs DELETE html and HEAD http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs HEAD html are resource method designator annotations defined by JAX RS and which correspond to the similarly named HTTP methods In the example above the annotated Java method will process HTTP GET requests The behavior of a resource is determined by which of the HTTP methods the resource is responding to The following example is an extract from the storage service sample that shows the use of the PUT method to create or update a storage container Example 3 3 PUT method 1 PUT 2 public Response putContainer 3 System out println PUT CONTAINER container 4 5 URI uri urilnfo getAbsolutePath 6 Container c new Container container uri toString 7 8 Response r 9 if MemoryStore MS hasContainer c 10 r Response created uri build 11 else 12 r Response noCon
7. gt gt getClasses return 48 Migrating from Jersey 1 x 18 1 2 ResourceConfig Reload In Jersey 1 the reload functionality is based on two interfaces 1 com sun jersey spi container ContainerListener 2 com sun jersey spi container ContainerNotifier Containers which support the reload functionality implement the ContainerListener interface so that once you get access to the actual container instance you could call it s onReload method and get the container re load the config The second interface helps you to obtain the actual container instance reference An example on how things are wired together follows Example 18 1 Jersey 1 reloader implementation 1 public class Reloader implements ContainerNotifier 2 List lt ContainerListener gt 1s 3 4 public Reloader 5 ls new ArrayList lt ContainerListener gt 6 7 8 public void addListener ContainerListener 1 9 ls add 1 10 11 12 public void reload 13 for ContainerListener 1 1s 14 l1 onReload 1 5 16 17 Example 18 2 Jersey 1 reloader registration 1 Reloader reloader new Reloader 2 resourceConfig getProperties put ResourceConfig PROPERTY_CONTAINER_NOTIF In Jersey 2 two interfaces are involved again but these have been re designed 1 org glassfish jersey server spi Container 2 org glassfish jersey server spi ContainerLifecycleListener The Container interface introduces two reload method
8. 7 3 3 Ub TEesoutces nee sent NSE AREE EEEE SEEE OSSES TERES Paii 12 3 4 Life cycle of Root Resource Classes oooooccoccnnccnnccnnconoconoconncnnncnnccnnconoconccnnconncinnions 14 3 3 MES Injection IT 15 3 6 Use of Contekt issn anro er ins EE e E S EEE pin ihren 16 4 Representations and RESponses ssi saimes ania ie nei a eRe EE RESE ARESE 17 4 1 Representations and Java Types oooconoccncconocnnccnnonnncnnnnonoronncnnccnnconnccnnccnnccnnconncinncos 17 4 2 Building Responses issem u ae oe p prieta gea ia 18 4 3 WebApplicationException and Mapping Exceptions to Responses ccooccccccncccnccnoccnicnnos 18 4 4 Conditional GETs and Returning 304 Not Modified Responses coooccocccccccoccnoconicnno 20 3 URIS dnd LINKS cie a leds sii 22 3 1 Building URIS sips tioi 0a it er 22 6 Deploying a RESTful Web Service scsi enson eeose keer cena KEDE EEEE EIEEE 24 II PL wastes utes 2 ee sterben T 27 7 1 Uniform Interface Constraint 2 00 00 cece cece c cence ence ence eeceeecaeecaeeea sean eens eeneeeneeeenees 27 7 2 Ease of use and reusing JAX RS artifacts oooococcnoccnnccnnccnnconoconoconncnnncnnncnnrcnnccnannnos 28 7 3 Getting started with the Jersey client ooooncnonnnccnnccnnccnnconnconnccnnconnconnconaronoconicnninnns 29 TA Overview of the API a erahnen Dunst 29 7 4 1 Configuring a Client and WebResource 222422442ssnneenneennennnen seen nennen 29 7 4 2 Building a request un
9. Hure nn BIER nn 30 743 RECEIVINE a Tesponse anna it tuners O E 31 7 4 4 Creating new WebResources from a WebResource oooccocccoccnoconnconnconnconnccnnoos 31 7 4 5 Java instances and types for representations cee cece cece eee eee ence eeeeeeeeeeees 31 7 5 Adding support for new representations oocooocnnocnnccnnccnncnnncnnccnnconnccnnccnnccnnconncnnicnnose 32 TOs Using FIETS csi td es 32 16 1 Supported filters viciosos noir adria seeds TEPA INSS 33 TT VOSUNS SELVICES cities ii in inside ibeces pecan de ctide 34 7 8 Security with Http s URLConnection coocccoccnnccnnccnnconnconnconcnnncnnncnnronoronnrnnconncinncinns 35 7 8 1 With Http s URLConnection ccoccoccnccnconccnconcnnconcnncononncononncononnconanoconanorinonos 35 7 8 2 With Apache HTTP client ee 35 8 Filters and Interceptors 2 02a es eb essioterdaas bey 36 9 Message Body Workers cocos reinen pm lab I ees Monee 37 10 Asynchronous Services and Clients 20 0 0 cece cece cece cece seca ceca ceca cena eens eeneeeaeeeeeeeeeeeeeeaees 38 11 Programmatic API for Building Resources 0 0 0 0 cece cece cece ence ence eeceeeeeeeeaeeeaeeea nennen nenn 39 lil Jersey 2 0 m13 User Guide 12 13 14 15 16 17 18 Support for Common Media Types sisse eee pone eree eper ia Ra pE R E EEEa a EE 40 TT ISON 22 22 RR A E had A E Ea ESE 40 122 AME ee ee le er eaa aa a sa a ERa eS 40 123 Multipart mn 2 se nl a EE E EEN E E ee
10. SNAPSHOT apidocs javax ws rs BeanParam html 1 2 public class MyBeanParam 3 PathParam p 4 private String pathParam 5 6 MatrixParam m 7 Encoded 8 DefaultValue default 9 private String matrixParam 10 11 HeaderParam header 12 private String headerParam 13 14 private String queryParam 1 5 16 public MyBeanParam QueryParam q String queryParam 17 this queryParam queryParam 18 19 20 public String getPathParam 21 return pathParam 22 23 24 25 Example 3 15 Injection of MyBeanParam as a method parameter 1 2 POST 3 public void post BeanParam MyBeanParam beanParam String entity 4 final String pathParam beanParam getPathParam contains injected pa 5 6 7 The example shows aggregation of injections PathParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs PathParam html QueryParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs QueryParam html MatrixParam http Jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs MatrixParam html and HeaderParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs HeaderParam html into one signle bean The rules for injections inside the bean are the same as described above for these injections The DefaultValue http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs DefaultValue html is used to define the default value for matrix parameter matrix
11. a String instance If response meta data is required then the Java type ClientResponse http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client ClientResponse html can be declared from which the response status headers and entity may be obtained For example the following gets both the entity tag and response entity from the response ClientResponse response r get ClientResponse class EntityTag response getEntityTag String entity response getEntity String class Ifthe ClientResponse type is not utilized and the response status is greater than or equal to 300 then the runtime exception UniformInterfaceException http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client UniformInterfaceException html is thrown This exception may be caught and the ClientResponse obtained as follows try String entity r get String class catch UniformInterfaceException ue ClientResponse response ue getResponse 7 4 4 Creating new WebResources from a WebResource A new WebResource http jersey java net nonav apidocs 2 0 m 13 jersey com sun jersey api client WebResource html can be created from an existing WebResource by building from the latter s URI Thus it is possible to build the request URI before building the request For example the following appends anew path segment and adds some query parameters WebResource r c resource http l
12. any service This is a very powerful concept in software engineering that makes Web based search engines and service mash ups possible It induces properties such as 1 simplicity the architecture is easier to understand and maintain and 2 modifiability or loose coupling clients and services can evolve over time perhaps in new and unexpected ways while retaining backwards compatibility Further constraints are required 1 every resource is identified by a URI 2 aclient interacts with the resource via HTTP requests and responses using a fixed set of HTTP methods 3 one or more representations can be retured and are identified by media types and 4 the contents of which can link to further resources The above process repeated over and again should be familiar to anyone who has used a browser to fill in HTML forms and follow links That same process is applicable to non browser based clients Many existing Java based client APIs such as the Apache HTTP client API or java net HttpURLConnection supplied with the JDK place too much focus on the Client Server constraint for the exchanges of request and responses rather than a resource identified by a URI and the use of a fixed set of HTTP methods 27 Client API A resource in the Jersey client API is an instance of the Java class WebResource http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client WebResource html and encapsulates a URI The fixed
13. beanParam getPathParam pathParam OANA OFBWN FE 3 3 Sub resources Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html may be used on classes and such classes are referred to as root resource classes Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html may also be used on methods of root resource classes This enables common functionality for a number of resources to be grouped together and potentially reused The first way Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html may be used is on resource methods and such methods are referred to as sub resource methods The following example shows the method signatures for a root resource class from the jmaki backend sample 12 JAX RS Application Resources and Sub Resources Example 3 17 Sub resource methods 1 Singleton 2 Path printers 3 public class PrintersResource 4 5 GET 6 Produces application json application xml F public WebResourceList getMyResources 8 9 GET Path list 10 Produces application json application xml del public WebResourceList getListOfPrinters T2 13 GET Path jMakiTable 14 Produces application json 15 public PrinterTableModel getTable 16 17 GET Path jMakiTree 18 Produces application json 19 public TreeM
14. exist since there may only be a maximum of one such representation sent in a request The representation being produced corresponds to what is returned by the resource method For example JAX RS makes it simple to produce images that are instance of File as follows Example 4 1 Using File with a specific MIME type to produce a response 1 GET 2 Path images image 3 Produces image 4 public Response getImage PathParam image String image 5 File f new File image 6 7 if f exists 8 throw new WebApplicationException 404 9 10 11 String mt new MimetypesFileTypeMap getContentType f 12 return Response ok f mt build LS Y A File type can also be used when consuming a temporary file will be created where the request entity 1s stored The Content Type if not set see next section can be automatically set from the MIME media types declared by Produces http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Produces html if the most acceptable media type is not a wild card one that contains a for example application or Given the following method the most acceptable MIME type is used when multiple output MIME types allowed 1 GET 17 Representations and Responses 2 Produces application xml application json 3 public String doGetAsXmlOrJson 4 5 If application xml is the most acceptable then the Cont
15. http docs oracle com javaee 5 api javax servlet http HttpServletResponse html are available using Context http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Context html 16 Chapter 4 Representations and Responses 4 1 Representations and Java Types Previous sections on Produces http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Produces html and Consumes http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Consumes html referred to MIME media types of representations and showed resource methods that consume and produce the Java type String for a number of different media types However St ring is just one of many Java types that are required to be supported by JAX RS implementations Java types such as byte java io InputStream java io Reader and java io File are supported In addition JAXB beans are supported Such beans are JAXBElement or classes annotated with XmlRootElement http docs oracle com javase 6 docs api javax xml bind annotation XmlRootElement html or XmIType http docs oracle com javase 6 docs api javax xml bind annotation XmIType html The samples jaxb and json from jaxb show the use of JAXB beans Unlike method parameters that are associated with the extraction of request parameters the method parameter associated with the representation being consumed does not require annotating A maximum of one such unannotated method parameter may
16. set of HTTP methods are methods on WebResource or if using the builder pattern more on this later are the last methods to be called when invoking an HTTP method on a resource The representations are Java types instances of which may contain links that new instances of WebResource may be created from 7 2 Ease of use and reusing JAX RS artifacts Since a resource is represented as a Java type it makes it easy to configure pass around and inject in ways that is not so intuitive or possible with other client side APIs The Jersey Client API reuses many aspects of the JAX RS and the Jersey implementation such as 1 URI building using UriBuilder http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core UriBuilder html and UriTemplate http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api uri UriTemplate html to safely build URIs 2 Support for Java types of representations such as byte String InputStream File DataSource and JAXB beans in addition to Jersey specific features such as JSON http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api json package summary html support and MIME Multipart http jersey java net nonav apidocs 2 0 m13 contribs jersey multipart index html support 3 Using the builder pattern to make it easier to construct requests Some APIs like the Apache HTTP client or java net HttpURLConnection http docs oracle com javase 1 5 0 docs api java net Http
17. the Java method will consume representations identified by the MIME media type text plain Notice that the resource method returns void This means no representation is returned and response with a status code of 204 No Content will be returned Consumes http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Consumes html can be applied at both the class and the method levels and more than one media type may be declared in the same Consumes http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Consumes html declaration 3 2 Parameter Annotations Param Parameters of a resource method may be annotated with parameter based annotations to extract information from a request One of the previous examples presented the use of PathParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs PathParam html to extract a path parameter from the path component of the request URL that matched the path declared in Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html QueryParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs QueryParam html is used to extract query parameters from the Query component of the request URL The following example is an extract from the sparklines sample JAX RS Application Resources and Sub Resources Example 3 8 Query parameters 1 Path smooth 2 GET 3 public Response smooth 4 D
18. APSHOT apidocs javax ws rs Produces html annotation at the class level The doGetAsHtml method s Produces http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Produces html annotation overrides the class level Produces http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Produces html setting and specifies that the method can produce HTML rather than plain text If a resource class is capable of producing more that one MIME media type then the resource method chosen will correspond to the most acceptable media type as declared by the client More specifically the Accept header of the HTTP request declared what is most acceptable For example if the Accept header is Accept text plain then the doGetAsPlainText method will be invoked Alternatively if the Accept header is Accept text plain q 0 9 text html which declares that the client can accept media types of text plain and text html but prefers the latter then the doGetAsHtml method will be invoked More than one media type may be declared in the same Produces http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Produces html declaration for example Example 3 5 Using multiple output MIME types GET Produces application xml application json public String doGetAsXmlOrJson Oe WN PF The doGetAsXmlOrJson method will get invoked if either of the media types application xml and application json are acc
19. Jersey 2 0 m13 User Guide Jersey 2 0 m13 User Guide Table of Contents Preface eek Ep R en ig verde vii 1 Getting Startede ehetu e NS 1 1 1 Creating a New Project from Maven Archetype ooccooccncccnccnnconnconnconnconnconacnnaconccnnronose 1 1 2 Exploring the Newly Created Project ooooccooccncconoconccnnocnncnnncnnncnnccnnronnconnccnnconaconncos 1 1 3 Customizing the JAX RS Resource i eiieeii p r cence eee e NE E EE E seas sen 1 1 4 Running the Project 2 8a ST si rare 1 1 5 Creating a JavaEE Web Application coooccnccnnccnccnnoconccnnccnnconnconnconnconncnnncnnncnnncnnronose 1 1 6 Exploring Other Jersey Examples 2unssnssnssnnsnnnennnsnnnnnnnnnnnennnen seca nenn nennen 1 2 Jersey Modules and Dependencies 2 055 csc c v enari 8 seems sr 2 2 1 Sample Scenarios sorro re nhac ecole d oes oases tases Seek O EEE OE ET E INESE 2 2 1 1 Basic Server Side Application ooooooocnnononcnnornncrnorronoron sce rennen nennen ares E SKE ii 2 3 JAX RS Application Resources and Sub Resources coooccocccnccnnccnnccnnccnnconnconnconconaconccnoronicnnos 3 3 1 Root Resource Classes ss sos 120 eek ee 3 ES O 4 3 1 2 GET PUT POST DELETE HTTP Methods 5 3 13 Produees u sn ie lib 5 3 14 OCONSUMES u 2 een ein SE 7 3 2 Parameter Annotations Param ccccccceceececn ec eeeecece ee eeeen sence eeeeneaeseeeeeesaeenees
20. Param Also the Encoded http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Encoded html annotation has the same behaviour as if it were used for injection in the resource method directly Injecting the bean parameter into Singleton resource class fields is not allowed injections into method parameter must be used instead BeanParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs BeanParam html can contain all parameters injections injections PathParam http jax rs spec java net nonav 2 0 11 JAX RS Application Resources and Sub Resources SNAPSHOT apidocs javax ws rs PathParam html QueryParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs QueryParam html MatrixParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs MatrixParam html HeaderParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs HeaderParam html CookieParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs CookieParam html FormParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs FormParam html More beans can be injected into one resource or method parameters even if they inject the same request values For example the following is possible Example 3 16 Injection of more beans into one resource methods POST public void post BeanParam MyBeanParam beanParam BeanParam AnotherBean anot String entity
21. SHOT apidocs javax ws rs core UriBuilder html from the bookmark sample Example 5 1 URI building 1 Path users 2 public class UsersResource 3 4 Context Urilnfo urilnfo 5 6 7 8 GET 9 Produces application json 10 public JSONArray getUsersAsJsonArray 11 JSONArray uriArray new JSONArray 12 for UserEntity userEntity getUsers 13 UriBuilder ub urilnfo getAbsolutePathBuilder 14 URI userUri ub 1 5 path userEntity getUserid 16 build 17 uriArray put userUri toASCIIString 18 19 return uriArray 20 21 Urilnfo http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Urilnfo html is obtained using the Context annotation and in this particular example injection onto the field of the root resource class is performed previous examples showed the use of Context on resource method parameters Urilnfo http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Urilnfo html can be used to obtain URIs and associated UriBuilder http jax rs spec java net nonav 2 0 SNAPSHOT 22 URIs and Links apidocs javax ws rs core UriBuilder html instances for the following URIs the base URI the application is deployed at the request URI and the absolute path URI which is the request URI minus any query components The getUsersAsJsonArray method constructs a JSONArrray where each element is a URI identifying a specific user re
22. URLConnection html can be rather hard to use and or require too much code to do something relatively simple This is why the Jersey Client API provides support for wrapping HttpURLConnection and the Apache HTTP client Thus it is possible to get the benefits of the established implementations and features while getting the ease of use benefit It is not intuitive to send a POST request with form parameters and receive a response as a JAXB object with such an API For example with the Jersey API this is very easy Example 7 1 POST request with form parameters Form f new Form f add x foo f add y Harty 1 2 3 4 5 Client c Client create 6 WebResource r c resource http localhost 8080 form 7 8 9 0 1 JAXBBean bean r type MediaType APPLICATION_FORM_URLENCODED_TYPE accept MediaType APPLICATION_JSON_TYPE post JAXBBean class f 1 1 In the above code a Form http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api representation Form html is created with two parameters a new WebResource http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client WebResource html instance is created from a Client http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client Client html then 28 Client API the Form instance is POSTed to the resource identified with the form media type and the response is req
23. ass is annotated with Provider http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs ext Provider html this declares that the class is of interest to the JAX RS runtime Such a class may be added to the set of classes of the Application http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Application html instance that is configured When an application throws an EntityNotFoundException http docs oracle com javaee 5 api javax persistence EntityNotFoundException html the toResponse method of the EntityNotFoundMapper instance will be invoked 4 4 Conditional GETs and Returning 304 Not Modified Responses Conditional GETs are a great way to reduce bandwidth and potentially server side performance depending on how the information used to determine conditions is calculated A well designed web site may return 304 Not Modified responses for the many of the static images it serves JAX RS provides support for conditional GETs using the contextual interface Request http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Request html The following example shows conditional GET support from the sparklines sample 20 Representations and Responses Example 4 7 Conditional GET support 1 public SparklinesResource 2 QueryParam d IntegerList data 3 DefaultValue 0 100 QueryParam limits Interval limits 4 Context Request request
24. be declared in the terminating HTTP method for PUT POST and DELETE requests For example the following sends a POST request String request content String response r accept MediaType APPLICATION_JSON_TYPE MediaType APPLICATION_XML_TYP header X FOO BAR post String class request GI where the String content will be serialized as the request entity see the section Java instances and types for representations section for further details on the supported Java types The Content Type of the request entity may be declared using the type builder method as follows String response r accept MediaType APPLICATION_JSON_TYP MediaType APPLICATION_XML_ TYPE header X FOO BAR type MediaType TEXT_PLAIN_TYPE post String class request Gl or alternatively the request entity and type may be declared using the entity method as follows String response r accept 30 Client API MediaType APPLICATION_JSON_TYPE MediaType APPLICATION_XML_TYPE header X FOO BAR entity request MediaType TEXT_PLAIN_TYPE post String class 7 4 3 Receiving a response If the response has a entity or representation then the Java type of the instance required is declared in the terminating HTTP method In the above examples a response entity is expected and an instance of String is requested The response entity will be de serialized to
25. ch as setting the entity tag and last modified date of the representation 4 3 WebApplicationException and Mapping Exceptions to Responses Previous sections have shown how to return HTTP responses and it is possible to return HTTP errors using the same mechanism However sometimes when programming in Java it is more natural to use exceptions for HTTP errors 18 Representations and Responses The following example shows the throwing of a Not FoundException from the bookmark sample Example 4 4 Throwing Jersey specific exceptions to control response 1 Path items itemid 2 public Item getItem PathParam itemid String itemid 3 Item i getItems get itemid 4 if i null 5 throw new NotFoundException Item itemid is not found 6 7 return i 8 This exception is a Jersey specific exception that extends WebApplicationException http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs WebA pplicationException html and builds a HTTP response with the 404 status code and an optional message as the body of the response Example 4 5 Jersey specific exception implementation 1 public class NotFoundException extends WebApplicationException 2 3 4 Create a HTTP 404 Not Found exception 5 2 6 public NotFoundException 7 super Responses notFound build 8 9 10 PR EI Create a HTTP 404 Not Found exception T2 param m
26. e NT 40 Support for Server Sent Events serere rreri a ehemals TEE 41 SECULAR AAA E ASS 42 WADE Suppoit ienee a a e E E NE E een 43 Jersey TestiPrame work AEEA E A E eae ee 44 Building and Testing Jersey u a a E a een en 45 17 1 Checking Out the Souree enra EAE Besen 45 17 2 B ildin the SOULE msie ee tone e ae e arae a lee e enia neh 45 17 3 TESIT ern r sired E E T S E EE EN N EES 45 174 Usmg NetBeans me ers mt her AROE TEE 46 Migrating from Jersey Ui unse are Sods eases Aaa Daniela 47 18 1 Server AA Re lem BR RRiee roten 47 18 1 1 Injecting custom objects 2 0 0 cece cece eee ca eece cece cena een eeneeeeeeeeeeeeeaeeeaees 47 18 1 2 ResourceContig Reload ccascecvsedusniweross dees ehepeeuea ss apro na 49 18 1 3 MessageBodyReaders and MessageBodyWriters ordering 50 18 2 Client APIS Ersten Sawa haan eeatont rend lae EEN 50 18 2 1 Making a simple client request ooocooccnnccnnconnconoconocnnocnnccnnconronccnnconnccnncons 51 AA UA ceed dopa RNE r E EE EEEE Eaa EE teases beens 51 18 2 3 Setting Accept header iii 51 18 2 4 Attaching entity to request a oin en a naa 52 18 2 5 Setting SSLContext and or HostnameVerifier 00 ceee eee cee ceeeen teen es 52 iv List of Tables 2 1 Jersey modules and dependencies u 223 800808 Rise 18 1 Mapping of Jersey 1 x to JAX RS 2 0 client classes ooooccnoconcconoccnocnnccnoconocnnccnnccnncconions Lis
27. eBodyWorkers whole set is sorted by declaration distance media type and source custom providers have smaller priority than Jersey provided JAX RS 1 x ordering can still be forced by setting parameter MessageProperties LEGACY_WORKERS_ORDERING jersey config workers legacyOrdering to true in ResourceConfig or ClientConfig properties 18 2 Client API JAX RS 2 0 provides functionality that is equivalent to the Jersey 1 x proprietary client API Here is a rough mapping between the Jersey 1 x and JAX RS 2 0 Client API classes 50 Migrating from Jersey 1 x Table 18 1 Mapping of Jersey 1 x to JAX RS 2 0 client classes Natay RS L Ihss Class Fomtsursjaictias pitt eneB iideand constructors Forathwinstaiientmeiheds fomsusjectienpW bb mTaWebResource Numa pcs ap V klbikhrkenn AV tieRssnurenethods by calling WebTarget request async The following sub sections show code examples 18 2 1 Making a simple client request Jersey 1 x way Client client Client create WebResource webResource client resource restURL path myresource param String result webResource pathParam param value get String class JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL path myresource param String result target pathParam param value get String class 18 2 2 Registering filters Jersey 1 x way C
28. ece cece eee reece eee 24 6 3 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 24 6 4 Configuration of maven war plugin in pom xml with Servlet 3 0 00 eee eeee eee 25 6 5 Deployment of a JAX RS application using web xml with Servlet 3 0 0 0 eee 25 6 6 Deployment of your application using Jersey specific servlet 22202240224nsen nennen nenn 26 6 7 Using Jersey specific servlet without an application model instance us2uussenssenseen seen 26 7 1 POST request with form parameters cee eee cee cee cc ence eeeeeeee seen eeea seca seas eeu eeneeeneeeneees 28 14 1 Accessing Security Contexts era ini RI 42 18 1 Jersey 1 reloader implementation oocccoccnnccnnccnnconoconoconacnnncnnnnnnronnrnnconnccnnccnnccnnconncnnniss 49 18 2 Jersey 1 reloader registration s mis neresine nears aa Sirenen 49 18 3 Jersey 2 reloader implementation 2 2 0 0 0 lee eee ee cee eens ce eeceeecaeeea essa nenn nenn eennsensnnn nn 50 18 4 Jersey 2 reloader registration e 0 ee ie 50 vi Preface This is user guide for Jersey 2 0 m13 We are trying to keep it up to date as we add new feature Please use also our API documentation linked from the Jersey home page http jersey java net as an additional source of information about Jersey features and API If you would like to contribute to the guide or have questions on things not covered in our docs plea
29. eceived the response is filtered by filterl filter2 and filter3 in that order before the response is returned Filters are implemented using the russian doll stack based pattern where a filter is responsible for calling the next filter in the ordered list of filters or the next filter in the chain of filters The basic template for a filter is as follows class AppClientFilter extends ClientFilter public ClientResponse handle ClientRequest cr Modify the request ClientRequest mcr modifyRequest cr Call the next filter ClientResponse resp getNext handle mcr Modify the response return modifyResponse resp The filter modifies the request if required by creating a new ClientRequest http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client ClientRequest html or modifying the state of the passed ClientRequest before calling the next filter The call to the next request will return the response a ClientResponse The filter modifies the response if required by creating anew ClientResponse or modifying the state of the returned Client Response Then the filter returns the modified response Filters are re entrant and may be called by multiple threads performing requests and processing responses Supported filters The Jersey Client API currently supports two filters 1 A GZIP content encoding filter GZIPContentEncodingFilter http jersey java net nonav apidocs 2 0
30. efaultValue 2 QueryParam step int step 5 DefaultValue true QueryParam min m boolean hasMin 6 DefaultValue true QueryParam max m boolean hasMax 7 DefaultValue true QueryParam last m boolean hasLast 8 DefaultValue blue QueryParam min color ColorParam minColor 9 DefaultValue green QueryParam max color ColorParam maxColor 10 DefaultValue red QueryParam last color ColorParam lastColor 11 I le wee dh If a query parameter step exists in the query component of the request URI then the step value will be will extracted and parsed as a 32 bit signed integer and assigned to the step method parameter If step does not exist then a default value of 2 as declared in the DefaultValue http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs DefaultValue html annotation will be assigned to the step method parameter If the step value cannot be parsed as a 32 bit signed integer then a HTTP 404 Not Found response is returned User defined Java types such as ColorParam may be used which as implemented as follows Example 3 9 Custom Java type for consuming request parameters 1 public class ColorParam extends Color 2 public ColorParam String s 3 super getRGB s 4 gt 6 private static int getRGB String s 7 if s charAt 0 8 try 9 Color c Color decode 0x s substring 1 10 return c getRGB ET catch Numb
31. eloper to concisely and efficiently implement a reusable client side solution that leverages existing and well established client side HTTP implementations The client API can be utilized to interoperate with any RESTful Web service implemented using one of many frameworks and is not restricted to services implemented using JAX RS However developers familiar with JAX RS should find the client API complementary to their services especially if the client API is utilized by those services themselves or to test those services The goals of the client API are threefold 1 Encapsulate a key constraint of the REST architectural style namely the Uniform Interface Constraint and associated data elements as client side Java artifacts 2 Make it as easy to interoperate with RESTful Web services as the JAX RS server side API makes it easy to build RESTful Web services and 3 Share common concepts of the JAX RS API between the server and the client side The Client API supports a pluggable architecture to enable the use of different underlying HTTP client implementations Several such implementations are supported by Jersey To name a few we have a client connectors for Http s URLConnection classes supplied with the JDK and the Grizzly client 7 1 Uniform Interface Constraint The uniform interface constraint bounds the architecture of RESTful Web services so that a client such as a browser can utilize the same interface to communicate with
32. ent Type of the response will be set to application xml 4 2 Building Responses Sometimes it is necessary to return additional information in response to a HTTP request Such information may be built and returned using Response http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Response html and Response ResponseBuilder http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Response ResponseBuilder html For example a common RESTful pattern for the creation of a new resource is to support a POST request that returns a 201 Created status code and a Location header whose value is the URI to the newly created resource This may be achieved as follows Example 4 2 Returning 201 status code and adding Location header in response to POST request 1 POST 2 Consumes application xml 3 public Response post String content 4 URI createdUri 5 create content 6 return Response created createdUri build 7 In the above no representation produced is returned this can be achieved by building an entity as part of the response as follows Example 4 3 Adding an entity body to a custom response 1 POST 2 Consumes application xml 3 public Response post String content 4 URI createdUri 5 String createdContent create content 6 return Response created createdUri entity createdContent build I Response building provides other functionality su
33. eptable If both are equally acceptable then the former will be chosen because it occurs first Optionally server can also specify the quality factor for individual media types These are considered if several are equally acceptable by the client For example JAX RS Application Resources and Sub Resources 3 1 4 Example 3 6 Server side content negotiation GET Produces application xml qs 0 9 application json public String doGetAsXmlOrJson Owe WN PF In the above sample if client accepts both application xml and application json equally then server always sends application json since application xml has a lower quality factor The examples above refer explicitly to MIME media types for clarity It is possible to refer to constant values which may reduce typographical errors see the constant field values of MediaType http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core MediaType html Consumes The Consumes http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Consumes html annotation is used to specify the MIME media types of representations a resource can consume that were sent by the client The above example can be modified to set the cliched message as follows Example 3 7 Specifying input MIME type 1 POST 2 Consumes text plain 3 public void postClichedMessage String message 4 Store the messag 5 In this example
34. erFormatException e 12 throw new WebApplicationException 400 T3 14 else Lo try 16 Field f Color class getField s 17 return Color f get null getRGB 18 catch Exception e 19 throw new WebApplicationException 400 20 21 22 23 In general the Java type of the method parameter may 1 Be a primitive type 2 Have a constructor that accepts a single String argument JAX RS Application Resources and Sub Resources 3 Have a static method named valueOf or fromString that accepts a single String argument see for example Integer valueOf String and java util UUID fromString String or 4 Be List lt T gt Set lt T gt or SortedSet lt T gt where T satisfies 2 or 3 above The resulting collection is read only Sometimes parameters may contain more than one value for the same name If this is the case then types in 4 may be used to obtain all values If the DefaultValue http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs DefaultV alue html is not used in conjunction with QueryParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs QueryParam html and the query parameter is not present in the request then value will be an empty collection for List Set or SortedSet null for other object types and the Java defined default for primitive types The PathParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs PathParam htm
35. essage the String that is the entity of the 404 response 13 2 14 public NotFoundException String message 15 super Response status Responses NOT_FOUND 16 entity message type text plain build 17 18 4921 In other cases it may not be appropriate to throw instances of WebApplicationException http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs WebA pplicationException html or classes that extend WebApplicationException http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs WebApplicationException html and instead it may be preferable to map an existing exception to a response For such cases it is possible to use the ExceptionMapper lt E extends Throwable gt http jax rs spec java net nonav 2 0 SNAPSHOTY apidocs javax ws rs ext ExceptionMapper html interface For example the following maps the EntityNotFoundException http docs oracle com javaee 5 api javax persistence EntityNotFoundException html to a HTTP 404 Not Found response 19 Representations and Responses Example 4 6 Mapping generic exceptions to responses 1 Provider 2 public class EntityNotFoundMapper implements 3 Except ionMapper lt javax persistence EntityNotFoundException gt 4 public Response toResponse Javax persistence EntityNotFoundException ex 5 return Response status 404 6 entity ex getMessage 7 type text plain 8 build 9 10 The above cl
36. est URI headers and entity or read modify the response status headers and entity The Client and WebResource classes extend from Filterable http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client filter Filterable html and that enables the addition of ClientFilter http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client filter ClientFilter html instances A WebResource will inherit filters from its creator which can be a 32 Client API 7 6 1 Client or another WebResource Additional filters can be added to a WebResource after it has been created For requests filters are applied in reverse order starting with the WebResource filters and then moving to the inherited filters For responses filters are applied in order starting with inherited filters and followed by the filters added to the WebResource All filters are applied in the order in which they were added For instance in the following example the Client has two filters added filterl and filter2 in that order and the WebResource has one filter added filter3 ClientFilter filterl ClientFilter filter2 are Client c Client create c addFilter filterl c addFilter filter2 ClientFilter filter3 WebResource r c resource r addFilter filter3 After a request has been built the request is filtered by filter3 filter2 and filterl in that order After the response has been r
37. form urlencoded 3 public void post MultivaluedMap lt String String gt formParams 4 5 Store the messag Le you don t need to use the Context http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Context html annotation Another kind of injection is the BeanParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs BeanParam html which allows to inject the parameters described above into a single bean A bean annotated with BeanParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs BeanParam html containing any fields and appropriate param annotation like PathParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs PathParam html will be initialized with corresponding request values in expected way as if these fields were in the resource class Then instead of injecting request values like path param in constructor parameters or class fields the BeanParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs BeanParam html can be used to inject such a bean into a resource or resource method The BeanParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs BeanParam html is used this way to aggregate more request parameters into a single bean 10 JAX RS Application Resources and Sub Resources Example 3 14 Example of the bean which will be used as BeanParam http jax rs spec java net nonav 2 0
38. here are some restrictions when injecting on to resource classes with a life cycle other than per request In such cases it is not possible to injected onto fields for the annotations associated with extraction of request parameters However it is possible to use the Context http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Context html annotation on fields in such cases a thread local proxy will be injected The FormParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs FormParam html annotation is special and may only be utilized on resource and sub resource methods This is because it extracts information from a request entity 15 JAX RS Application Resources and Sub Resources 3 6 Use of Context Previous sections have introduced the use of Context http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Context html Chapter 5 of the JAX RS specification presents all the standard JAX RS Java types that may be used with Context http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Context html When deploying a JAX RS application using servlet then ServletConfig http docs oracle com javaee 5 api javax servlet ServletConfig html ServletContext http docs oracle com javaee 5 api javax servlet ServletContext html HttpServletRequest http docs oracle com javaee 5 api javax servlet http HttpServletRequest html and HttpServletResponse
39. ity Security information is available by obtaining the SecurityContext http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core SecurityContext html using Context http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Context html which is essentially the equivalent functionality available on the HttpServletRequest http docs oracle com javaee 5 api javax servlet http HttpServletRequest html SecurityContext http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core SecurityContext html can be used in conjunction with sub resource locators to return different resources if the user principle is included in a certain role For example a sub resource locator could return a different resource if a user is a preferred customer Example 14 1 Accessing SecurityContext 1 Path basket 2 public ShoppingBasketResource get Context SecurityContext sc 3 if sc isUserInRole PreferredCustomer 4 return new PreferredCustomerShoppingBaskestResource 5 else 6 return new ShoppingBasketResource ll T 8 5 42 Chapter 15 WADL Support Chapter 16 Jersey Test Framework Chapter 17 Building and Testing Jersey 17 1 17 2 17 3 Checking Out the Source Jersey source code is available in a Git repository you can browse at http java net projects jersey sources code show In case you are not familiar with Git we recommend reading on of
40. ized to deploy the test based services Many of the Jersey samples contain tests that utilize the client API to server both for testing and examples of how to use the API The samples utilize Grizzly or embedded Glassfish to deploy the services The following code snippets are presented from the single unit test HelloWorldWebAppTest of the helloworld webapp https maven java net service local artifact maven redirect r releases amp g com sun jersey samples amp a helloworld webapp amp v 2 0 m13 amp c project amp e zip sample The setUp method called before a test is executed creates an instance of the Glassfish server deploys the application and a WebResource instance that references the base resource Override protected void setUp throws Exception super setUp Start Glassfish glassfish new GlassFish BASE_URI getPort T Deploy Glassfish referencing the web xml ScatteredWar war new ScatteredWar BASE_URI getRawPath new File src main webapp new File src main webapp WEB INF web xml Collections singleton new File target classes toURI toURL glassfish deploy war Client c Client create r c resource BASE_URI The tearDown method called after a test is executed stops the Glassfish server Override protected void tearDown throws Exception super tearDown glassfish stop The testHelloWorld method tests that the resp
41. l and the other parameter based annotations MatrixParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs MatrixParam html HeaderParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs HeaderParam html CookieParam http Jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs CookieParam html FormParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs FormParam html obey the same rules as QueryParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs QueryParam html MatrixParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs MatrixParam html extracts information from URL path segments HeaderParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs HeaderParam html extracts information from the HTTP headers CookieParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs CookieParam html extracts information from the cookies declared in cookie related HTTP headers FormParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs FormParam html is slightly special because it extracts information from a request representation that is of the MIME media type application x www form urlencoded and conforms to the encoding specified by HTML forms as described here This parameter is very useful for extracting information that is POSTed by HTML forms for example the following extracts the form
42. late will respond For example if the user entered their username as Galileo the web service will respond to the following URL http example com users Galileo To obtain the value of the username variable the PathParam http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs PathParam html may be used on method parameter of a request method for example Example 3 2 Specifying URI path parameter 1 Path users username 2 public class UserResource 3 4 GET 5 Produces text xml 6 public String getUser PathParam username String userName 7 8 Ir If it is required that a user name must only consist of lower and upper case numeric characters then it is possible to declare a particular regular expression which overrides the default regular expression 4 for example Path users username a zA Z a zA Z_0 9 In this type of example the username variable will only match user names that begin with one upper or lower case letter and zero or more alpha numeric characters and the underscore character If a user name does not match that a 404 Not Found response will occur A Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html value may or may not begin with a it makes no difference Likewise by default a Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html value may or may not end in a it makes no
43. lic class MyApplication extends PackagesResourceConfig 3 public MyApplication super org foo rest org bar rest ZO OB You also need to set maven war plugin attribute to false in pom xml when building war without web xml file using maven 24 Deploying a RESTful Web Service Example 6 4 Configuration of maven war plugin in pom xm1 with Servlet 3 0 1 lt plugins gt A 3 lt plugin gt 4 lt groupld gt org apache maven plugins lt groupld gt 5 lt artifactId gt maven war plugin lt artifactId gt 6 lt version gt 2 1 1 lt version gt 7 lt configuration gt 8 lt failOnMissingWebXml gt false lt failOnMissingWebXml gt 9 lt configuration gt 10 lt plugin gt Men us 12 lt plugins gt Another deployment option is to declare JAX RS application details in the web xml This is usually suitable in case of more complex deployments e g when security model needs to be properly defined or when additional initialization parameters have to be passed to Jersey runtime JAX RS 1 1 specifies that a fully qualified name of the class that implements Application http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Application html may be declared in the lt servlet name gt element of the JAX RS application s web xml This is supported in a Web container implementing Servlet 3 0 as follows Example 6 5 Deployment of a JAX RS application using web xml with Servlet 3 0 1 lt web app gt 2 l
44. lient client Client create WebResource webResource client resource restURL webResource addFilter new HTTPBasicAuthFilter username password JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL target configuration register new HttpBasicAuthFilter username password 18 2 3 Setting Accept header Jersey 1 x way Client client Client create WebResource webResource client resource restURL accept text plain ClientResponse response webResource get ClientResponse class JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL 51 Migrating from Jersey 1 x Response response target request text plain get Response class 18 2 4 Attaching entity to request Jersey 1 x way Client client Client create WebResource webResource client resource restURL ClientResponse response webResource post ClientResponse class payload JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL Response response target request post Entity text payload Response class 18 2 5 Setting SSLContext and or HostnameVerifier Jersey 1 x way HTTPSProperties prop new HTTPSProperties hostnameVerifier sslContext DefaultClientConfig dcc new DefaultClientConfig dcc getProperties
45. localhost 8080 xyz WebResource r c resource http localhost 8080 xyz and redirection will be configured for responses to requests invoked on the Web resource Client instances are expensive resources It is recommended a configured instance is reused for the creation of Web resources The creation of Web resources the building of requests and receiving of responses are guaranteed to be thread safe Thus a Client instance and WebResource instances may be shared between multiple threads In the above cases a WebResource instance will utilize HttpUrlConnection or HttpsUrlConnection if the URI scheme of the WebResource is http or https respectively 7 4 2 Building a request Requests to a Web resource are built using the builder pattern see RequestBuilder http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client RequestBuilder html where the terminating method corresponds to an HTTP method see UniformInterface http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client UniformInterface html For example String response r accept MediaType APPLICATION_JSON_TYPE MediaType APPLICATION_XML_ TYPE header X FOO BAR get String class The above sends a GET request with an Accept header of application json application xml and a non standard header xX FOO of BAR If the request has a request entity or representation then an instance of a Java type can
46. n code relying on those APIs 18 1 1 Injecting custom objects Jersey 1 x have its own internal dependency injection framework which handles injecting various parameters into field or methods It also provides a way how to register custom injection provider in Singleton or PerRequest scopes Jersey 2 x uses HK2 as dependency injection framework and users are also able to register custom classes or instances to be injected in various scopes Main difference in Jersey 2 x is that you don t need to create special classes or providers for this task everything should be achievable using HK2 API Custom injectables can be registered at ResourceConfig level by adding new HK2 Module or by dynamically adding binding almost anywhere using injected HK2 Services instance Jersey 1 x Singleton ResourceConfig resourceConfig new DefaultResourceConfig resourceConfig getSingletons add new SingletonTypelnjectableProvider lt Context SingletonType gt SingletonType class new SingletonType Jersey 1 x PerRequest ResourceConfig resourceConfig new DefaultResourceConfig resourceConfig getSingletons add new PerRequestTypelnjectableProvider lt Context PerRequestType gt Override public Injectable lt PerRequestType gt getInjectable ComponentContext ic C Lf ses H Jersey 2 0 HK2 Module public static class MyBinder extends AbstractBinder Override protected void configure request scope binding
47. ocalhost 8080 xyz MultivaluedMap lt String String gt params MultivaluedMapImpl params add foo x params add bar y String response r path abc queryParams params get String class that results in a GET request to the URI http localhost 8080 xyz abc foo x amp bar y 7 4 5 Java instances and types for representations All the Java types for representations supported by the Jersey server side for requests and responses are also supported on the client side This includes the standard Java types as specified by JAX RS in section 31 Client API 4 2 4 http jsr3 11 java net nonav releases 1 0 spec index html in addition to JSON Atom and Multipart MIME as supported by Jersey To process a response entity or representation as a stream of bytes use InputStream as follows InputStream in r get InputStream class Read from the stream in close Note that it is important to close the stream after processing so that resources are freed up To POST a file use File as follows File f String response r post String class f Refer to the JAXB sample https maven java net service local artifact maven redirect r releases amp g com sun jersey samples amp a jaxb amp v 2 0 m13 amp c project amp e zip to see how JAXB with XML and JSON can be utilized with the client API more specifically see the unit tests 7 5 Adding support for new representations The support for ne
48. odel getTree 20 21 GET Path ids printerid 22 Produces application json application xml 23 public Printer getPrinter PathParam printerid String printerId 24 25 PUT Path ids printerid 26 Consumes application json application xml 27 public void putPrinter PathParam printerid String printerId Printer 28 29 DELETE Path ids printerid 30 public void deletePrinter PathParam printerid String printerld 31 If the path of the request URL is printers then the resource methods not annotated with Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html will be selected If the request path of the request URL is printers list then first the root resource class will be matched and then the sub resource methods that match list will be selected which in this case is the sub resource method getListOfPrinters So in this example hierarchical matching on the path of the request URL is performed The second way Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html may be used is on methods not annotated with resource method designators such as GET http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs GET html or POST http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs POST html Such methods are referred to as sub resource locators The following example shows the method signatures for a ro
49. onse to a GET request to the Web resource returns Hello World 34 Client API public void testHelloWorld throws Exception String responseMsg r path helloworld get String class assertEquals Hello World responseMsg Note the use of the path method on the WebResource to build from the base WebResource 7 8 Security with Http s URLConnection 7 8 1 With Http s URLConnection 7 8 2 The support for security specifically HTTP authentication and or cookie management with Http s URLConnection is limited due to constraints in the API There are currently no specific features or properties on the Client class that can be set to support HTTP authentication However since the client API by default utilizes HttpURLConnection or HttpsURLConnection it is possible to configure system wide security settings which is obviously not sufficient for multiple client configurations For HTTP authentication the java net Authenticator can be extended and statically registered Refer to the Http authentication http docs oracle com javase 6 docs technotes guides net http auth html document for more details For cookie management the java net CookieHandler can be extended and statically registered Refer to the Cookie Management http docs oracle com javase 6 docs technotes guides net http cookie html document for more details To utilize HTTP with SSL it is necessary to utilize the https scheme
50. ot resource class and a resource class from the optimistic concurrency sample 13 JAX RS Application Resources and Sub Resources Example 3 18 Sub resource locators 1 Path item 2 public class ItemResource 3 Context Urilnfo urilnfo 4 5 Path content 6 public ItemContentResource getItemContentResource T return new ItemContentResource 8 9 10 GET 11 Produces application xml 12 public Item get 13 14 15 public class ItemContentResource 16 17 GET 18 public Response get 19 20 PUT 21 Path version 22 public void put 23 PathParam version int version 24 Context HttpHeaders headers 25 byte in 26 The root resource class ItemResource contains the sub resource locator method get ItemContentResource that returns a new resource class If the path of the request URL is item content then first of all the root resource will be matched then the sub resource locator will be matched and invoked which returns an instance of the ItemContentResource resource class Sub resource locators enable reuse of resource classes In addition the processing of resource classes returned by sub resource locators is performed at runtime thus it is possible to support polymorphism A sub resource locator may return different sub types depending on the request for example a sub resource locator could return different sub types dependen
51. parameter named name from the POSTed form data Example 3 10 Processing POSTed HTML form 1 POST 2 Consumes application x www form urlencoded 3 public void post FormParam name String name 4 5 Store the messag If it is necessary to obtain a general map of parameter name to values then for query and path parameters it is possible to do the following Example 3 11 Obtaining general map of URI path and or query parameters GET public String get Context Urilnfo ui MultivaluedMap lt String String gt queryParams ui getQueryParameters MultivaluedMap lt String String gt pathParams ui getPathParameters Ope WBN ER JAX RS Application Resources and Sub Resources For header and cookie parameters the following Example 3 12 Obtaining general map of header parameters GET public String get Context HttpHeaders hh MultivaluedMap lt String String gt headerParams hh getRequestHeaders Map lt String Cookie gt pathParams hh getCookies ape WBN HH In general Context http jax rs spec java net nonav 2 0 SNAPSHOTY apidocs javax ws rs core Context html can be used to obtain contextual Java types related to the request or response Because form parameters unlike others are part of the message entity it is possible to do the following Example 3 13 Obtaining general map of form parameters 1 POST 2 Consumes application x www
52. put HTTPSProperties PROPERTY_HTTPS_PROPERTIES prop Client client Client create dcc Jersey 2 0 way Client client ClientFactory newClient client configuration setProperty ClientProperties SSL_CONTEXT sslContext client configuration setProperty ClientProperties HOSTNAME_VERIFIER hostnameVer 52
53. rce class can be used perform actions that may otherwise have to be duplicated to invoked for each resource method 21 Chapter 5 URIs and Links 5 1 Building URIs A very important aspects of REST is hyperlinks URIs in representations that clients can use to transition the Web service to new application states this is otherwise known as hypermedia as the engine of application state HTML forms present a good example of this in practice Building URIs and building them safely is not easy with java net URI http docs oracle com javase 1 5 0 docs api java net URL html which is why JAX RS has the UriBuilder http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core UriBuilder html class that makes it simple and easy to build URIs safely UriBuilder http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core UriBuilder html can be used to build new URIs or build from existing URIs For resource classes it is more than likely that URIs will be built from the base URI the web service is deployed at or from the request URI The class Urilnfo http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Urilnfo html provides such information in addition to further information see next section The following example shows URI building with Urilnfo http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Urilnfo html and UriBuilder http jax rs spec java net nonav 2 0 SNAP
54. rceConfig implementation automatically by declaring the packages as follows Example 6 7 Using Jersey specific servlet without an application model instance 1 lt web app gt 2 lt servlet gt 3 lt servlet name gt Jersey Web Application lt servlet name gt 4 lt servlet class gt com sun jersey spi container servlet ServletContainer lt 5 lt init param gt 6 lt param name gt com sun jersey config property packages lt param name gt tb lt param value gt org foo rest org bar rest lt param value gt 8 lt init param gt 9 RER 10 lt servlet gt 1 1 12 lt web app gt JAX RS also provides the ability to obtain a container specific artifact from an Application http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Application html instance For example Jersey supports using Grizzly http grizzly java net as follows SelectorThread st RuntimeDelegate createEndpoint new MyApplication SelectorTh Jersey also provides Grizzly http grizzly java net helper classes to deploy the ServletThread instance at a base URL for in process deployment The Jersey samples provide many examples of Servlet based and Grizzly in process based deployments 26 Chapter 7 Client API This section introduces the JAX RS Client API which is a high level Java based API for interoperating with RESTful Web services It makes it very easy to interoperate with RESTful Web services and enables a dev
55. s which you can call to get the application re loaded One of these methods allows to pass in a new ResourceConfig instance You can register your implementation of ContainerLifecycleListener the same way as any other provider i e either by annotating it by Provider annotation or adding it to the ResourceConfig directly either using the class using ResourceConfig addClasses or registering a particular instance using ResourceConfig addSingletons method An example on how things work in Jersey 2 follows 49 Migrating from Jersey 1 x Example 18 3 Jersey 2 reloader implementation 1 public class Reloader implements ContainerLifecycleListener 2 3 Container container 4 5 public void reload ResourceConfig newConfig 6 container reload newConfig 7 8 9 public void reload 10 container reload 14 T2 13 Override 14 public void onStartup Container container 15 this container container 16 17 18 Override 19 public void onReload Container container 20 ignore or do whatever you want after reload has been done 21 22 23 Override 24 public void onShutdown Container container 25 ignore or do something after the container has been shutdown 26 27 Example 18 4 Jersey 2 reloader registration 1 Reloader reloader new Reloader 2 resourceConfig addSingletons reloader 18 1 3 MessageBodyReaders and MessageBodyWriters ordering JAX RS 2 0 defines new order of Messag
56. s GET import javax ws rs Path import javax ws rs Produces Path helloworld public class HelloWorldResource public static final String CLICHED_MESSAGE Hello World OANA O FP WN FE Ne 10 11 GET 12 Produces text plain 13 public String getHello 14 return CLICHED_MESSAGE 15 16 Let s look at some of the JAX RS annotations used in this example JAX RS Application Resources and Sub Resources 3 1 1 Path The Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html annotation s value is a relative URI path In the example above the Java class will be hosted at the URI path helloworld This is an extremely simple use of the Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html annotation What makes JAX RS so useful is that you can embed variables in the URIs URI path templates are URIs with variables embedded within the URI syntax These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI Variables are denoted by curly braces For example look at the following Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html annotation Path users username In this type of example a user will be prompted to enter their name and then a Jersey web service configured to respond to requests to this URI path temp
57. se contact us at users jersey java net mailto users jersey java net Vil Chapter 1 Getting Started This chapter provides a quick introduction on how to get started building RESTful services using Jersey The example described here uses the lightweight Grizzly HTTP server At the end of this chapter you will see how to implement equivalent functionality as a JavaEE web application you can deploy on any servlet container supporting Servlet 2 5 and higher 1 1 Creating a New Project from Maven Archetype 1 2 1 3 1 4 1 5 1 6 If you want to depend on Jersey snapshot versions the following repository needs to be added to the pom lt repository gt lt id gt snapshot repository java net lt id gt lt name gt Java net Snapshot Repository for Maven lt name gt lt url gt https maven java net content repositories snapshots lt url gt lt layout gt default lt layout gt lt repository gt Now to create a new Jersey project based on Grizzly 2 container from a maven archetype execute the following in the directory where the new project should reside mvn archetype generat DarchetypeArtifactId jersey quickstart qgrizzly2 Darchetyp Feel free to adjust the group id package name and artifact id of your new project in the line above or you can change it after it gets generated by updating the project pom xml Exploring the Newly Created Project TODO Customizing the JAX RS Resource TODO instruc
58. source The URI is built from the absolute path of the request URI by calling Urilnfo getAbsolutePathBuilder http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Urilnfo html getA bsolutePathBuilder A new path segment is added which is the user ID and then the URI is built Notice that it is not necessary to worry about the inclusion of characters or that the user ID may contain characters that need to be percent encoded UriBuilder takes care of such details UriBuilder http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core UriBuilder html can be used to build replace query or matrix parameters URI templates can also be declared for example the following will build the URI http localhost segment name value Example 5 2 Building URIs using query parameters 1 UriBuilder fromUri http localhost 2 path a 3 queryParam name value 4 build segment value 23 Chapter 6 Deploying a RESTful Web Service JAX RS provides a deployment agnostic abstract class Application http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Application html for declaring root resource and provider classes and root resource and provider singleton instances A Web service may extend this class to declare root resource and provider classes For example Example 6 1 Deployment agnostic application model 1 public class MyApplication extends Application 2 p
59. st execution If you don t want to skip the tests execute the following instead mvn clean install Building the whole Jersey project including tests could take significant amount of time Testing Jersey contains many tests Unit tests are in the individual Jersey modules integration and end to end tests are in jersey code tests directory You can run tests related to a particular area using the following command 45 Building and Testing Jersey mvn Dtest lt pattern gt test where pattern may be a comma separated set of names matching tests 17 4 Using NetBeans NetBeans IDE has excellent maven support The Jersey maven modules can be loaded built and tested in NetBeans without any additional NetBeans specific project files 46 Chapter 18 Migrating from Jersey 1 x This chapter is a migration guide for people switching from Jersey 1 x Since many of the Jersey 1 x features became part of JAX RS 2 0 standard which caused changes in the package names we decided it is a good time to do a more significant incompatible refactoring which will allow us to introduce some more interesting new features in the future As the result there are many incompatiblities between Jersey 1 x and Jersey 2 0 This chapter summarizes how to migrate the concepts found in Jersey 1 x to Jersey JAX RS 2 0 concepts 18 1 Server API Jersey 1 x contains number of proprietary server APIs This section covers migration of applicatio
60. summary id 339 3 1 Root Resource Classes Root resource classes are POJOs Plain Old Java Objects that are annotated with Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html have at least one method annotated with Path http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Path html or a resource method designator annotation such as GET http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs GET html PUT http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs PUT html POST http jax rs spec java net nonav 2 0 SNAPSHOTY apidocs javax ws rs POST html DELETE http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs DELETE html Resource methods are methods of a resource class annotated with a resource method designator This section shows how to use Jersey to annotate Java objects to create RESTful web services The following code example is a very simple example of a root resource class using JAX RS annotations The example code shown here is from one of the samples that ships with Jersey the zip file of which can be found in the maven repository here https maven java net service local artifact maven redirect r releases amp g org glassfish jersey examples amp a helloworld amp v 2 0 m13 amp c project amp e zip Example 3 1 Simple hello world root resource class package org glassfish jersey examples helloworld import javax ws r
61. t on the role of the principle that is authenticated Note that the runtime will not manage the life cycle or perform any field injection onto instances returned from sub resource locator methods This is because the runtime does not know what the life cycle of the instance is 3 4 Life cycle of Root Resource Classes By default the life cycle of root resource classes is per request namely that a new instance of a root resource class is created every time the request URI path matches the root resource This makes for a very natural programming model where constructors and fields can be utilized as in the previous section showing the constructor of the SoarklinesResource class without concern for multiple concurrent requests to the same resource In general this is unlikely to be a cause of performance issues Class construction and garbage collection of JVMs has vastly improved over the years and many objects will be created and discarded to serve and process the HTTP request and return the HTTP response 14 JAX RS Application Resources and Sub Resources Instances of singleton root resource classes can be declared by an instance of Application http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Application html Jersey supports two further life cycles using Jersey specific annotations If a root resource class is annotated with Singleton then only one instance is created per web application If a root reso
62. t of Examples 3 1 Simple hello world root resource class 1 0 00 cee eee cee cece ee ceeece seca ceca cece nenn aiiis 3 3 2 Specifying URI path parameter coooconoconccnnccnnccnnccnnconoronocnnconnconncrnnconnconncnnncnnncnnnnnnnnnureness 4 3 3 PUT method 2 2 2232 28er Dinner EEEO AE EEE PEERS IPES 5 3 4 Specifying output MIME type uuseassenssensensssnnsunssunssnnsennsennennnsnnnsnnnsennnennnennennsen nenn nenn 6 3 5 Using multiple output MIME types 20 0 0 eee stio aap ESEA eiS 6 3 6 Server side content negotiation eee ceee cece eece cece cena cena een eeneeeeeeeeeeeeeeeseaeseaeeeaes 7 3 7 Specifying input MIME type ssiri essere RS 7 3 8 Query Parameters criei ii eiii 8 3 9 Custom Java type for consuming request parameters coooccocnnncnnocnnccnnccnnccnnccnnccnnconnconaconaconoss 8 3 10 Processing POSTed HTML form ooconoccnocnnncnnccnnncnncnnoronccnnconnconnccnncnnncnnncnnncnnncnnncnnncnarenoss 9 3 11 Obtaining general map of URI path and or query parameters ooccoccnnccnnccnnccnncnnncnnnconaconicinoss 9 3 12 Obtaining general map of header parameters ooooccnnccnnconcconeconncnnncnnnnnncnnnronncnnconncinnccnncons 10 3 13 Obtaining general map of form parameters cece cece eee eee ce ee ca eece cena sense nennen een 10 3 14 Example of the bean which will be used as BeanParam u222s40sssessen seen seen eenes 11 3 15 Injection of MyBeanParam as a method parameter
63. t servlet gt 3 lt servlet name gt org foo rest MyApplication lt servlet name gt 4 lt servlet gt 9 6 7 8 lt servlet mapping gt lt servlet name gt org foo rest MyApplication lt servlet name gt lt url pattern gt resources lt url pattern gt 9 lt servlet mapping gt 10 eee 11 lt web app gt Note that the lt servlet class gt element is omitted from the servlet declaration This is a correct declaration utilizing the Servlet 3 0 extension mechanism Also note that lt servlet mapping gt is used to define the base resource URI When running in a Servlet 2 x then instead it is necessary to declare the Jersey specific servlet and pass the Application http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Application html implementation class name as one of the servlet s init param entries 25 Deploying a RESTful Web Service Example 6 6 Deployment of your application using Jersey specific servlet 1 lt web app gt 2 lt servlet gt 3 lt servlet name gt Jersey Web Application lt servlet name gt 4 lt servlet class gt com sun jersey spi container servlet ServletContainer lt 5 lt init param gt 6 lt param name gt javax ws rs Application lt param name gt 7 lt param value gt org foo rest MyApplication lt param value gt 8 lt init param gt 9 PN 10 lt servlet gt 11 12 lt web app gt Alternatively a simpler approach is to let Jersey choose the PackagesResou
64. tent build 13 14 15 MemoryStore MS createContainer c 16 return r 1 7 3 By default the JAX RS runtime will automatically support the methods HEAD and OPTIONS if not explicitly implemented For HEAD the runtime will invoke the implemented GET method if 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 WADL http wadl java net document describing the resource Produces The Produces http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Produces html annotation is used to specify the MIME media types of representations a resource can produce and send back to the client In this example the Java method will produce representations identified by the MIME media type text plain Produces http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs Produces html can be applied at both the class and method levels Here s an example JAX RS Application Resources and Sub Resources Example 3 4 Specifying output MIME type 1 Path myResource 2 Produces text plain 3 public class SomeResource 4 GET 5 public String doGetAsPlainText 6 7 8 9 GET 10 Produces text html ET public String doGetAsHtml 12 13 14 The doGetAsPlainText method defaults to the MIME type of the Produces http jax rs spec java net nonav 2 0 SN
65. the API 7 4 1 To utilize the client API it is first necessary to create an instance of a Client http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client Client html for example Client c Client create Configuring a Client and WebResource The client instance can then be configured by setting properties on the map returned from the getProperties methods or by calling the specific setter methods for example the following configures the client to perform automatic redirection for appropriate responses c getProperties put ClientConfig PROPERTY_FOLLOW_REDIRECTS true which is equivalent to the following c setFollowRedirects true Alternatively it is possible to create a Client instance using a ClientConfig http jersey java net nonav apidocs 2 0 m 13 jersey com sun jersey api client config ClientConfig html object for example ClientConfig cc new DefaultClientConfig cc getProperties put ClientConfig PROPERTY_FOLLOW_REDIRECTS true Client c Client create cc Once a client instance is created and configured it is then possible to obtain a WebResource http jersey java net nonav apidocs 2 0 m 13 jersey com sun jersey api client 29 Client API WebResource html instance which will inherit the configuration declared on the client instance For example the following creates a reference to a Web resource with the URI http
66. the many Getting Started with Git articles you can find on the web For example this DZone RefCard http refcardz dzone com refcardz getting started git Before you can clone Jersey repository you have to sign up for a java net http java net account Once you are registered you have to add an SSH key to your java net profile see this article on how to do that http java net projects help pages ProfileSettings SSH_Keys_Tab To clone the Jersey repository you can execute the following command on the command line provided you have a command line Git client installed on your machine git clone ssh lt your_java_net_id gt java net jersey cod Milestones and releases of Jersey are tagged You can list the tags by executing the standard Git command in the repository directory git tag 1 Building the Source Jersey source code requires Java SE 6 or greater The build is based on Maven Maven 3 or greater is recommended Also it is recommended you use the following Maven options when building the workspace can be set in MAVENT_OPTS environment variable Xmx1048m XX PermSize 64M XX MaxPermSize 128M It is recommended to build all of Jersey after you cloned the source code repository To do that execute the following commands in the directory where jersey source repository was cloned typically the directory named jersey code mvn Dmaven test skip true clean install This command will build Jersey but skip the te
67. tions on how to make simple edits to the newly created resource Running the Project TODO instructions on how to run the project Creating a JavaEE Web Application TODO Exploring Other Jersey Examples Jersey codebase contains a number of useful samples on how to use various JAX RS and Jersey features Please refer to the TODO Examples section of this guide for more information on those Chapter 2 Jersey Modules and Dependencies Jersey is built assembled and installed using Maven Jersey is deployed to the Java Net maven repository at the following location http maven java net https maven java net index html The Jersey modules can be browsed at the following location https maven java net content repositories releases org glassfish jersey Jars Jar sources Jar JavaDoc and samples are all available on the java net maven repository An application depending on Jersey requires that it in turn includes the set of jars that Jersey depends on Jersey has a pluggable component architecture so the set of jars required to be include in the class path can be different for each application All Jersey components are built using Java SE 6 compiler It means you will also need at least Java SE 6 to be able to compile and run your application Developers using maven are likely to find it easier to include and manage dependencies of their applications than developers using ant or other build technologies This document will e
68. ublic Set lt Class lt gt gt getClasses 3 Set lt Class lt gt gt s new HashSet lt Class lt gt gt 4 s add HelloWorldResource class 5 return sS 6 7 Alternatively it is possible to reuse one of Jersey s implementations that scans for root resource and provider classes given a classpath or a set of package names Such classes are automatically added to the set of classes that are returned by getClasses For example the following scans for root resource and non provider classes in packages org foo rest org bar rest and in any sub packages of those two Example 6 2 Reusing Jersey implementation in your custom application model 1 public class MyApplication extends PackagesResourceConfig 2 public MyApplication 3 super org foo rest org bar rest 4 Ss There are multiple deployment options for the class that implements Application http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs core Application html interface in the Servlet 3 0 container For simple deployments no web xml is needed at all Instead an E ApplicationPath http Jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs ApplicationPath html annotation can be used to annotate the user defined application class and specify the the base resource URI of all application resources Example 6 3 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 1 ApplicationPath resources 2 pub
69. uested as an instance of a JAXB bean with an acceptable media type identifying the Java Script Object Notation JSON format The Jersey client API manages the serialization of the Form instance to produce the request and de serialization of the response to consume as an instance of a JAXB bean If the code above was written using Ht tpURLConnect ion then the developer would have to write code to serialize the form sent in the POST request and de serialize the response to the JAXB bean In addition further code would have to be written to make it easy to reuse the same resource http localhost 8080 form that is encapsulated in the WebResource type 7 3 Getting started with the Jersey client Refer to the dependencies chapter http jersey java net nonav documentation 2 0 m13 chapter_deps html chapter_deps and specifically the Core client http jersey java net nonav documentation 2 0 m13 chapter_deps html core_client section for details on the dependencies when using the Jersey client with Maven and Ant Refer to the Java API documentation http jersey java net nonav apidocs 2 0 m13 jersey com sun jersey api client package summary html for details on the Jersey client API packages and classes Refer to the Java API Apache HTTP client documentation http jersey java net nonav apidocs 2 0 m13 contribs jersey apache client index html for details on how to use the Jersey client API with the Apache HTTP client 7 4 Overview of
70. urce class is annotated with PerSession then one instance is created per web session and stored as a session attribute 3 5 Rules of Injection Previous sections have presented examples of annotated types mostly annotated method parameters but also annotated fields of a class for the injection of values onto those types This section presents the rules of injection of values on annotated types Injection can be performed on fields constructor parameters resource sub resource sub resource locator method parameters and bean setter methods The following presents an example of all such injection cases Example 3 19 Injection 1 Path id d 2 public class InjectedResource 3 Injection onto field 4 DefaultValue q QueryParam p 5 private String p 6 7 Injection onto constructor parameter 8 public InjectedResource PathParam id int id 9 10 Injection onto resource method parameter 11 GET 12 public String get Context Urilnfo ui 13 14 Injection onto sub resource resource method parameter 15 Path sub id 16 GET 17 public String get PathParam sub id String id 18 1 9 Injection onto sub resource locator method parameter 20 Path sub id 21 public SubResource getSubResource PathParam sub id String id 22 23 Injection using bean setter method 24 HeaderParam X header 2 5 public void setHeader String header 26 T
71. w application defined representations as Java types requires the implementation of the same provider based interfaces as for the server side JAX RS API namely MessageBodyReader _ http jsr311 java net nonav javadoc javax ws rs ext MessageBodyReader html and MessageBodyWriter http jsr311 java net nonav javadoc javax ws rs ext MessageBodyWriter html respectively for request and response entities or inbound and outbound representations Refer to the entity provider https maven java net service local artifact maven redirect r releases amp g com sun jersey samples amp a entity provider amp v 2 0 m13 amp c project amp e zip sample for such implementations utilized on the server side Classes or implementations of the provider based interfaces need to be registered withaClientConfig and passed to the Client for creation The following registers a provider class MyReader which will be instantiated by Jersey ClientConfig cc new DefaultClientConfig cc getClasses add MyReader class Client c Client create cc The following registers an instance or singleton of MyReader ClientConfig cc new DefaultClientConfig MyReader reader cc getSingletons add reader Client c Client create cc 7 6 Using filters Filtering requests and responses can provide useful functionality that is hidden from the application layer of building and sending requests and processing responses Filters can read modify the requ
72. xplain to both maven and non maven developers how to depend on Jersey for their application Ant developers are likely to find the Ant Tasks for Maven http maven apache org ant tasks index html very useful The following table provides an overview of all Jersey modules and their dependencies with links to the respective binaries Table 2 1 Jersey modules and dependencies Module Dependencies Description Core jersey server jersey commons Base server functionality jersey client jersey commons Basic client functionality jersey Common functionality shared by client and server commons Containers 2 1 Sample Scenarios 2 1 1 Basic Server Side Application For a server side Jersey application you typically need to depend on jersey server module to provide the basic functionality then you may want to support JSON mapping and a standard JavaEE servlet container you would deploy your application to So this would be the common set of dependencies for your project for this kind of scenario e jersey server e jersey commons Chapter 3 JAX RS Application Resources and Sub Resources This chapter presents an overview of the core JAX RS concepts resources and sub resources The JAX RS 2 0 SNAPSHOT JavaDoc can be found online here http jax rs spec java net nonav 2 0 SNAPSHOT apidocs index html The JAX RS 2 0 SNAPSHOT specification draft can be found online here http jcp org en jsr

Jersey 2.0-m13 User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents