Home

Jersey 1.9-ea01 User Guide

1. The Main class deploys the Hel loWorldResource using the Grizzly Web container Lines 9 to 10 creates an initialization parameter that informs the Jersey runtime where to search for root resource classes to be deployed In this case it assumes the root resource class in the package com sun jersey samples helloworld resources or in a sub package of Lines 13 to 14 deploys the root resource to the base URI http localhost 9998 and returns a Grizzly SelectorThread The complete URI of the Hello World root resource is http localhost 9998 helloworld Notice that no deployment descriptors were needed and the root resource was setup in a few statements of Java code 1 3 Testing the root resource Goto the URI http localhost 9998 helloworld in your favourite browser Getting Started Or from the command line use curl gt curl http localhost 9998 helloworld 1 4 Here s one Paul created earlier The example code presented above is shipped as the HelloWorld http download java net maven 2 com sun jersey samples helloworld 1 9 ea0 1 helloworld 1 9 ea01 project zip sample in the Java Net maven repository For developers wishing to get started by deploying a Web application an equivalent sample as a Web application is shipped as the HelloWorld WebApp http download java net maven 2 com sun jersey samples helloworld webapp 1 9 ea0 1 helloworld webapp 1 9 ea01 project zip sample Chapter 2 Overvie
2. 11 Return some cliched textual content 12 return Hello World 13 Getting Started 14 The HelloWorldResource class is a very simple Web resource The URI path of the resource is helloworld line 2 it supports the HTTP GET method line 6 and produces cliched textual content line 12 of the MIME media type text plain line 9 Notice the use of Java annotations to declare the URI path the HTTP method and the media type This is a key feature of JSR 311 1 2 Deploying the root resource The root resource will be deployed using the Grizzly Web container Create the following Java class in your project it 2 3 4 3 6 7 8 9 10 11 12 13 14 LS 16 17 18 19 20 21 22 public class Main public static void main String args throws IOException final String baseUri http localhost 9998 final Map lt String String gt initParams new HashMap lt String String gt initParams put com sun jJersey config property packages com sun jersey samples helloworld resources System out println Starting grizzly SelectorThread threadSelector GrizzlyWebContainerFactory create baseUri initParams System out printlin String format Jersey app started with WADL available at Ssapplication wadl n Try out Sshelloworld nHit enter to stop it baseUri baseUri System in read threadSelector stopEndpoint System exit 0
3. 15 16 17 return context 18 19 20 Sample above shows simple JAXBCont ext creation all you need to do is put this Provider annotated class somewhere where Jersey can find it Users sometimes have problems with using provider classes on client side so just for reminder you have to declare them in client config cliend does not anything like package scanning done by server 38 XML Support Example 4 8 Using Provider with Jersey client ClientConfig cc new DefaultClientConfig cc getClasses add PlanetJAXBContextProvider class Client c Client create cc Ss 0 DN E 39 Chapter 5 JSON Support Jersey JSON support comes as a set of JAX RS MessageBodyReader lt T gt http jsr311 java net nonav releases 1 1 javax ws rs ext MessageBodyReader html and MessageBodyWriter lt T gt http jsr311 java net nonav releases 1 1 javax ws rs ext MessageBodyWriter html providers distributed with jersey json module These providers enable using three basic approaches when working with JSON format e POJO support e JAXB based JSON support e Low level JSONObject JSONArray based JSON support The first method is pretty generic and allows you to map any Java Object to JSON and vice versa The other two approaches limit you in Java types your resource methods could produce and or consume JAXB based approach could be taken if you want to utilize certain JAXB features The last low level approach gi
4. Example 2 5 Using multiple output MIME types GET Produces application xml application json public String doGetAsXmlOrJson Owe WN FP The doGetAsXm1OrJson method will get invoked if either of the media types application xml and application json are acceptable If both are equally acceptable then the former will be chosen because it occurs first 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 jsr311 java net nonav releases l 1 javax ws rs core MediaType html Overview of JAX RS 1 1 2 1 4 Consumes The Consumes http jsr311 java net nonav releases 1 1 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 2 6 Specifying input MIME type 1 POST 2 Consumes text plain 3 public void postClichedMessage String message 4 5 Store the messag In this example 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 jsr31 1 java net nonav relea
5. Jersey currently support several low level data types St reamSource SAXSource DOMSource and Document You can use these types as return type or method resource parameter Lets say we want to test this feature and we have helloworld sample as starting point All we need to do is add methods resources which consumes and produces XML and types mentioned above will be used Example 4 1 Low level XML test methods added to HelloWorldResource java 1 Path 1 2 POST 3 public StreamSource getl StreamSource streamSource 4 return streamSource 5 6 7 Path 2 8 POST 9 public SAXSource get2 SAXSource saxSource 10 return saxSource 11 12 13 Path 3 14 POST 15 public DOMSource get3 DOMSource domSource 16 return domSource 17 18 19 Path 4 20 POST 21 public Document get4 Document document 22 return document 23 Both MessageBodyReaders and MessageBody Writers are used in this case all we need is do POST request with some XML document as a request entity I want to keep this as simple as possible so I m going to send only root element with no content lt test gt You can create Jersey client to do that or use some other tool for example curl as I did curl v http localhost 9998 helloworld 1 d lt test gt You should get exactly same XML from our service as is present in the request in this case XML headers are added to response but content stays Feel free to iterate
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 E A 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 sr311 java net nonav releases 1 1 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 2 15 Custom Java type for consuming request parameters 1 public class ColorParam extends Color 2 public ColorParam String s 3 super getRGB s 4 5 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 NumberFormatException e 12 throw new WebApplicationException 400 13 14 else Lo try 16 Field f Color class getField
7. JSON notation was introduced in Jersey version 1 0 2 With natural notation Jersey will automatically figure out how individual items need to be processed so that you do not need to do any kind of manual configuration Java arrays and lists are mapped into JSON arrays even for single element cases Java numbers and booleans are correctly mapped into JSON numbers and booleans and you do not need to bother with XML attributes as in JSON they keep the original names So without any additional configuration just using JSONConfiguration natural build for configuring your JAXBContext you will get the following JSON for the bean initialized at Example 5 9 JAXB beans for JSON supported notations description initialization Example 5 17 JSON expression produced using natural notation de Ns Bro IO 2 name Bob 3 addresses street Long Street 1 4 town Short Village You might notice that the single element array addresses remains an array and also the non string id value is not limited with double quotes as natural notation automatically detects these things To support cases when you use inheritance for your JAXB beans an option was introduced to the natural JSON configuration builder to forbid XML root element stripping The option looks pretty same as at the default mapped notation case Example 5 14 Keep XML root tag equivalent in JSON mapped JSON notation Example 5 18 Keep XML root tag
8. java net nonav releases 1 1 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 get ListOfPrinters So in this example hierarchical matching on the path of the request URL is performed The second way Path http jsr311 java net nonav releases 1 1 javax ws rs Path html may be used is on methods not annotated with resource method designators such as GET http jsr311 java net nonav releases 1 1 javax ws rs GET html or EPOST http jsr311 java net nonav releases 1 1 javax ws rs POST html Such methods are referred to as sub resource locators The following example shows the method signatures for a root resource class and a resource class from the optimistic concurrency sample 17 Overview of JAX RS 1 1 Example 2 25 Sub resource locators 1 Path item 2 public class ItemResource 3 Context Urilnfo urilnfo 4 5 Path content 6 public ItemContentResource getItemContentResource 7 return new ItemContentResource 8 9 10 GET 11 Produces application xml 12 public Item get 13 14 15 public class ItemContentResource 16 47 GET 18 public Response get 19 20 PUT 21 Path version 22 public void put 23 PathParam version int ver
9. of using dynamic meta data for the definition of these type of contracts The use of dynamic meta data requires the server to return WADL fragments when using OPTIONS on an action resource URI When dynamic meta data is not available for example if using an older version of Jersey on the server client interfaces should be fully annotated and a tighly coupled contract should be used instead 10 1 6 Configuring Hypermedia in Jersey There are a few configuration options in hypermedia action sample http download java net maven 2 com sun jersey experimental hypermedia action hypermedia action sample that are worth highlighting First a special filter factory HypermediaFilterFactory must be enabled This can be done programmatically by adding com sun jersey server hypermedia filter HypermediaFilterFactory to the list defined by com sun jersey spi container ResourceFilters or declaratively in the application s web xml file Refer to the Java class com sun jersey samples hypermedia Main in the hypermedia sample for an example of how to do this using Grizzly which can be executed withmvn install exec java Second hypermedia applications must included the following Maven runtime dependencies lt dependency gt lt groupId gt com sun jersey experimental hypermedia action lt grouplId gt lt artifactId gt hypermedia action server lt artifactId gt 67 Experimental Features lt version gt Jersey version lt vers
10. 1 1 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 2 13 Use of Context Previous sections have introduced the use of Context http sr311 java net nonav releases 1 1 javax ws rs core Context html Chapter 5 http jsr311 java net nonav releases 1 1 spec spec3 html x3 520005 of the JAX RS specification presents all the standard JAX RS Java types that may be used with Context http jsr3 11 java net nonav releases 1 1 javax ws rs core Context html When deploying a JAX RS application using servlet then ServletConfig http java sun com javaee 5 docs api javax servlet ServletConfig html ServletContext http java sun com javaee 5 docs api javax servlet ServletContext html HttpServletRequest http java sun com javaee 5 docs api javax servlet http HttpServletRequest html and HttpServletResponse http java sun com javaee 5 docs api javax servlet http HttpServletResponse html are available using Context http jsr3 1 1 java net nonav releases 1 1 javax ws rs core Context html 24 Overview of JAX RS 1 1 2 14 Annotations Defined By JAX RS For a list of the annotations specified by JAX RS see Appendix A http sr311 java net nonav releases 1 1 spec spec3 html x3 66000A of the specification 25 Chapter 3 Client API 3 1 Introduction This section introduces the clien
11. 2 x or higher see later for specific version constraints with respect to JSON support Deploying an application for XML serialization support requires no additional dependences since Java SE 6 ships with JAXB 2 x support Maven developers using JSON serialization support of JAXB beans when using the MIME media type application json require a dependency on the jersey json http download java net maven 2 com sun jersey jersey json 1 9 ea0 1 jersey json 1 9 ea01 pom module no explicit dependency on jaxb impl is required This module depends on the JAXB reference implementation version 2 1 12 or greater and such a version is required when enabling support for the JAXB natural JSON convention For all other 72 Dependencies supported JSON conventions any JAXB 2 x version may be utilized The following dependency needs to be added to the pom lt dependency gt lt groupid gt com sun jersey lt grouplId gt lt artifactId gt jersey json lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt Non maven developers require jackson core asl jar http repository codehaus org org codehaus jackson jackson core as 1 7 1 jackson core asl 1 7 1 jar jackson mapper asl jar http repository codehaus org org codehaus jackson jackson mapper asl 1 7 1 jackson mapper as 1 7 1 jar jackson jaxrs jar http repository codehaus org org codehaus jackson jackson jaxrs l 7 1 jackson jaxrs 1 7 1 jar
12. Building URIs using query parameters coooccoccnncnnncnnncnnccnnconnconnconncnnnconncnnncnnncnnncnnnnnarenoss 20 2 28 Throwing Jersey specific exceptions to control response cece cece eee ceee ee eeeeeece seen eeaes 20 2 29 Jersey specific exception implementation cee cece cence eee ceeeea seca eeee eens eeu eeneeennees 20 2 30 Mapping generic exceptions tO responses eee eee cee cence eee ceeeceeeca ceca cena eeae eeu eeneeeenees 21 2 31 Conditional GET supports sss 50 osios esas sose5 te rn raton Si cuss PESTERA pS SESTETO Ena P HES ESE reed 22 2 32 Accessing SeECULIEYCONTERE merindad E e EEEa T aai 23 233 IEC tadas 24 3 1 POST request with form parameters cooocconccnccnncnnncnnccnnccnnconnconnccnnccnnconnconncnnncnnncnnnenanenass 27 4 1 Low level XML test methods added to HelloWorldResource java ooocooccccccnnccnccnnccnnccnncnnno 35 4 2 Planet clas ie ii e EEEE ED gece EENE ERASE 36 4 3 Resource Class coral ri rr batng See naked ook bos Ae o IAEA Aid senses aes 36 4 4 Method for consuming Planet cece cece cece cece cece cece cena cen E RE EE RENE ETE E E 37 4 5 Resource class JA XBElement vo csses 00s te cis conse totes eSsangssesusndssegseosashotseapedsauas ss chess 37 4 6 Client side JAXBElement rciris o ee ee a a s EE EE EE E E a 38 4 7 PlanetJAXB Conte xtProvidert ssrin teene e e ena E a E a E ris 38 4 8 Using Provider with Jersey client 0c cece ccc ee cec
13. Classes resisite ipa o enei i ES 22 2 IT SOCULILY ON 23 2 12 Rules of NJE HON knees eran ree EEEE sees seas SEE EESE EREE Ea eE aE EET 23 2 13 Use Of O Context E E VE OE EE A EEEE 24 2 14 Annotations Defined By JAX RS 00 0 eiretier eap a ara s oai as 25 3 Chent APP yiee oteto eTe ok E A ee EOT EE ees 26 E nea ha Vein O1 o P E EE EET T 26 3 2 Uniform Interface Constraint 2 2 0 0 cece cece cece cece cee ee cece cece eene een eenneeeeeeeeeeeeeeeeeaees 26 3 3 Ease of use and reusing JAX RS artifacts oooocccocccoccnnconnccnnccnncnnnconoconconncnnccnnconanonos 27 3 4 Getting started with the Jersey Client ooooccooccnnccnnconoconocnnocnnocnncnnnronccnnccnnccnnccnnions 28 E of the O 28 3 5 1 Configuring a Client and WebResource ooooccccccnccnncnnccnnccnnccnnccnnccnnconnconacinncos 28 3 5 2 Building a regUest eerd date a rro 29 3 5 3 Receiving a A ashe cede des sees gees tected AEN Peewee EE E 30 3 5 4 Creating new WebResources from a WebResQurce 0 ee cece cece eeee teenies 30 3 5 5 Java instances and types for representations oocccoccnnccnnccnnconoconncnnncnnncnnannnncnoss 31 3 6 Adding support for new representations oooccooccnccnnconnconnconnconnconeconnconconocnnrnnnronicnnos 31 Bots USNS FIETS E A AA AA 31 EN sats oise eers ates Shae TREE TIRARE PNE SAPETE AOST ERER SI TGE Era Ki 32 3 8 Testing services aiios res ri EEE E EE E VATE E E EES 33 3 9 Security with Http s URLConnecti
14. Dependencies To test a maven based web project with an external container such as GlassFish create the war file then deploy as follows assuming that the pom file is set up for deployment mvn clean package Dmaven test skip true Then execute the tests as follows myn test Djersey test containerFactory com sun jersey test framework spi contai DJERSEY_HTTP_PORT lt HTTP_PORT gt Breaking changes from 1 1 1 ea to 1 1 2 ea The maven project groupld has changed from com sun jersey test framework to com sun jersey The extending of Jersey unit test and configuration has changed See here http jersey java net nonav apidocs 1 9 ea01 jersey test framework com sun jersey test framework package summary html for an example See the blog entry on Jersey Test Framework http blogs sun com naresh entry jersey_test_framework_makes_it for detailed instructions on how to use 1 1 l ea version of the framework in your application 78 Chapter 12 Jersey with GlassFish 12 1 12 2 12 2 1 This chapter will present instructions on how to use Jersey with Glassfish when Jersey is distributed in the war and to manually upgrade the Jersey version bundled with a GlassFish installation Overriding Jersey with war files To override the version of Jersey distributed in GlassFish with a version of Jersey distributed in a war file ensure that class loader delegation is set to false in WEB INF sun web xml or WEB
15. HTTP 404 Not Found exception 5 6 public NotFoundException 7 super Responses notFound build 8 9 10 xe 11 Create a HTTP 404 Not Found exception 12 param message the String that is the entity of the 404 response 13 14 public NotFoundException String message ES super Response status Responses NOT_FOUND 16 entity message type text plain build 17 18 194 20 Overview of JAX RS 1 1 In other cases it may not be appropriate to throw instances of WebApplicationException http jsr311 java net nonav releases 1 1 javax ws rs WebA pplicationException html or classes that extend WebApplicationException http jsr3 11 java net nonav releases 1 1 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 jsr311 java net nonav releases l 1 javax ws rs ext ExceptionMapper html interface For example the following maps the EntityNotFoundException http java sun com javaee 5 docs api javax persistence EntityNotFoundException html to a HTTP 404 Not Found response Example 2 30 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 EntityNot
16. INF glassfish web xml For example lt sun web app error url gt lt context root gt context lt context root gt lt class loader delegate false gt lt sun web app gt In the GlassFish admin console go to Configuration gt JVM Settings switch to the JVM Options tab and add the following option Dcom sun enterprise overrideablejavaxpackages jJavax ws rs Javax ws rs Restart GlassFish for new JVM settings to take effect Upgrading Jersey in GlassFish GlassFish v3 0 and 3 0 1 GlassFish v3 0 comes up with Jersey version 1 1 4 1 GlassFish v3 0 1 with Jersey version 1 1 5 To upgrade these to 1 9 ea01 you will need to replace certain files manually GlassFish uses Jersey internally in it s REST administration API and the Update Center client would not allow you to upgrade in order to prevent this functionality The workaround described in this section is known to work but it is not currently a tested and supported scenario Please keep in mind things could break It is recommended to back up all all impacted files The actual replace steps follow Remove the existing Jersey files Stop all running server instances Then remove the following files from the GlassFish installation directory e glassfish modules jsr3 1 1 api jar glassfish modules jersey gf bundle jar glassfish modules jersey gf statsproviders jar glassfish modules jersey multipart jar glassfish modules jackson core asl jar glassfish m
17. Security Security information is available by obtaining the SecurityContext http sr311 java net nonav releases 1 1 javax ws rs core SecurityContext html using Context http jsr3 11 java net nonav releases 1 1 javax ws rs core Context html which is essentially the equivalent functionality available on the HttpServletRequest http java sun com javaee S docs api javax servlet http HttpServletRequest html SecurityContext http jsr3 1 1 java net nonav releases 1 1 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 acertain role For example a sub resource locator could return a different resource if a user is a preferred customer Example 2 32 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 7 8 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
18. WAB Example As mentioned above WAB is just an OSGified WAR archive Besides the ususal OSGi headers it must in addition contain a special header Web ContextPath specifying the web application context path Our WAB has beside some other the following headers present in the manifest Web ContextPath helloworld Webapp Context helloworld Bundle ClassPath WEB INF classes where the second one is ignored by GlassFish but is needed by other containers not fully compliant with the OSGi Enterprise Specification mentioned above The third manifest header worth mentioning is the Bundle ClassPath specifying where to find the application Java classes within the bundle archive For more detailed information on the example please see the source code http download java net maven 2 com sun jersey samples helloworld osgi webapp 1 9 ea01 helloworld osgi webapp 1 9 ea01 project zip Following is the listing showing how to actually install and run the WAB on GlassFish g install http download java net maven 2 com sun jersey samples helloworld osgi Bundle ID 246 g start 246 In the above listing the number 246 represents handler to the OSGi bundle you have just installed Bundle numbers are allocated dynamically It means you might be given a different handler It is important to always use the correct bundle number as specified by the Felix runtime in the Bundle ID response After the WAB gets installed and activated by the ab
19. com sun jersey api core ResourceConfig html implementations are utilized 70 Dependencies com sun jersey api core ClasspathResourceConfig http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api core ClasspathResourceConfig html or e com sun jersey api core PackagesResourceConfig http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api core PackagesResourceConfig html By default Jersey will utilize the ClasspathResourceConfig http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api core ClasspathResourceConfig html if an alternative is not specified If an alternative is specified that does not depend on the asm jar then it is no longer necessary to include the asm jar in the minimum set of required jars 11 2 Core client Maven developers require a dependency on the jersey client http download java net maven 2 com sun jersey jersey client 1 9 ea0 1 jersey client 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupid gt com sun jersey lt grouplid gt lt artifactId gt jersey client lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt Non maven developers require e jersey client jar http download java net maven 2 com sun jersey jersey client 1 9 ea0 1 jersey client 1 9 ea01 jar e jersey core jar http download java net maven 2 com sun jersey jersey core 1 9 ea01 jersey
20. equivalent in JSON natural JSON notation JSONConfiguration natural rootUnwrapping false build 46 JSON Support 5 2 2 3 Jettison mapped notation Next two notations are based on project Jettison http jettison codehaus org User 27s Guide You might want to use one of these notations when working with more complex XML documents Namely when you deal with multiple XML namespaces in your JAXB beans Jettison based mapped notation could be configured using JSONConfiguration mappedJettison build If nothing else is configured you will get similar JSON output as for the default mapped notation Example 5 19 JSON expression produced using Jettison based mapped notation 1 contact id 2 2 name Bob 3 addresses street Long Street 1 4 town Short Village The only difference is your numbers and booleans will not be converted into strings but you have no option for forcing arrays remain arrays in single element case Also the JSON object representing XML root tag is being produced If you need to deal with various XML namespaces however you will find Jettison mapped notation pretty useful Lets define a particular namespace for id item XmlElement namespace http example com public int id Then you simply confgure a mapping from XML namespace into JSON prefix as follows Example 5 20 XML namespace to JSON mapping configuration for Jettison based mapped notation 1 Ma
21. following Path http jsr311 java net nonav releases 1 1 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 template 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 jsr311 java net nonav releases 1 1 javax ws rs PathParam html may be used on method parameter of a request method for example Example 2 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 oF 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 Z2_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 jsr3 11 java net nonav r
22. from the application layer of building and sending requests and processing responses Filters can read modify the request URI headers and entity or read modify the response status headers and entity 31 Client API 3 7 1 The Client and WebResource classes extend from Filterable http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api client filter Filterable html and that enables the addition of ClientFilter http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api client filter ClientFilter html instances A WebResource will inherit filters from its creator which can be a Client or another WebResource Additional filters can be added to a WebResource after it has been created For requests 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 responses filters are applied in reverse order starting with the WebResource filters and then moving to the inherited filters 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 a Client c Client create c addFilter filterl c addFilter filter2 ClientFilter filter3 WebResource r c resource r addFilter filter3 After a reque
23. headers defining the contextual action set which in this case will consist of the pay and cancel actions but not the ship action An attempt to interact with any action not in the contextual action set will result in a client side exception if using proxies as shown above or a server side exception if using some other API The following annotations are allowed in hypermedia controller interfaces Name Consumes Produces CookieParam FormParam HeaderParam QueryParam as well as any HTTP method annotation like POST PUT etc All other annotations not listed here are unsupported at this time of note Mat rixParam is not supported The Name annotation used in Jersey is defined in com sun jersey core hypermedia 10 1 5 Server Evolution In the last section we have seen how the use of client proxies based on partially annotated interfaces facilitates server evolution An interface method annotated with Action and Name represents a loosely coupled contract with a server Changes to action resource URIs HTTP methods and parameter types on the server will not require a client re spin Naturally as in all client server architectures it is always possible to break backward compatibility but the ability to support more dynamic contracts usually at the cost of additional processing time is still an area of investigation We see this form of hypermedia support in Jersey as a small step in this direction showing the potential
24. image 6 th if f exists 8 throw new WebApplicationException 404 9 10 Lal String mt new MimetypesFileTypeMap getContentType f 12 return Response ok f mt build 13 A File type can also be used when consuming a temporary file will be created where the request entity is stored The Content Type if not set see next section can be automatically set from the MIME media types declared by Produces http jsr3 1 1 java net nonav releases 1 1 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 Example 2 21 The most acceptable MIME type is used when multiple output MIME types allowed 1 GET 2 Produces application xml application json 3 public String doGetAsXmlOrJson 4 5 if application xml is the most acceptable then the Content Type of the response will be set to application xml 2 5 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 jsr3 11 java net nonav releases 1 1 javax ws rs core Response html and Response ResponseBuilder http jsr311 java net nonav releases 1 1 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 Create
25. javax ws rs HeaderParam html CookieParam http jsr3 1 1 java net nonav releases 1 1 javax ws rs CookieParam html FormParam http jsr3 11 java net nonav releases 1 1 javax ws rs FormParam html obey the same rules as QueryParam http jsr311 java net nonav releases 1 1 javax ws rs QueryParam html MatrixParam _ http jsr311 java net nonav releases 1 1 javax ws rs MatrixParam html extracts information from URL path segments HeaderParam http jsr311 java net nonav releases 1 1 javax ws rs HeaderParam html extracts information from the HTTP headers CookieParam http jsr3 11 java net nonav releases 1 1 javax ws rs CookieParam html extracts information from the cookies declared in cookie related HTTP headers FormParam http jsr3 1 1 java net nonav releases 1 1 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 parameter named name from the POSTed form data Example 2 16 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
26. lt version gt lt dependency gt Non maven developers require jettison jar http repol maven org maven2 org codehaus jettison jettison 1 1 jettison 1 1 jar and additionally if not depending on the jersey bundle jar http download java net maven 2 com sun jersey jersey bundle 1 9 ea01 jersey bundle 1 9 ea01 jar non maven developers require jersey json jar http download java net maven 2 com sun jersey jersey json 1 9 ea01 jersey json 1 9 ea01 jar 11 4 4 Mail and MIME multipart The use of the Java type javax mail internet MimeMultipart requires Java Mail version 1 4 or higher Maven developers require a dependency on the java mail http download java net maven 1 javax mail poms mail 1 4 pom module Non maven developers require e mail jar http download java net maven 1 javax mail jars mail 1 4 jar e activation jar http download java net maven 1 javax activation jars activation 1 1 jar Jersey ships with a high level MIME multipart API Maven developers requires a dependency on the jersey multipart http download java net maven 2 com sun jersey contribs jersey multipart 1 9 ea01 jersey multipart 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupid gt com sun jersey contribs lt groupIid gt lt artifactId gt jersey multipart lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt Non maven developers require e mimepull
27. myObject new JSONObject 3 try myObject put name Agamemnon myObject put age 32 catch JSONException ex LOGGER log Level SEVERE Error ex 0 J00 sms 5 3 1 Examples Download http download java net maven 2 com sun jersey samples bookmark 1 9 ea0 1 bookmark 1 9 ea01 project zip to get a more complex example using low level JSON support 49 Chapter 6 Declarative Hyperlinking RESTful APIs must be hypertext driven http roy gbiv com untangled 2008 rest apis must be hypertext driven JAX RS currently offers UriBuilder http jsr311 java net nonav releases 1 1 javax ws rs core UriBuilder html to simplify URI creation but Jersey adds an additional annotation based alternative that is described here 6 1 Links in Representations Links are added to representations using the Ref annotation on entity class fields The Jersey runtime is responsible for injecting the appropriate URI into the field prior to serialization by a message body writer E g consider the following resource and entity classes Path widgets public class WidgetsResource GET public Widgets get return new Widgets public class Widgets Ref resource WidgetsResource class URI u After a call to WidgetsResource get the Jersey runtime will inject the value context widgets into the returned Widgets instance If an absolute URI is desired ins
28. net maven 2 lt url gt lt layout gt default lt layout gt lt repository gt lt repository gt lt id gt maven repository java net lt id gt lt name gt Java net Maven 1 Repository legacy lt name gt lt url gt http download java net maven 1 lt url gt lt layout gt legacy lt layout gt lt repository gt Non maven developers require e grizzly servlet webserver jar http download java net maven 2 com sun grizzly grizzly servlet webservetr 1 9 18 i grizzly servlet webserver 1 9 18 1 jar e jersey server jar http download java net maven 2 com sun jersey jersey server 1 9 ea0 1 jersey server 1 9 ea01 jar e jersey core jar http download java net maven 2 com sun jersey jersey core 1 9 ea01 jersey core 1 9 ea01 jar Getting Started e jsr311 api jar http download java net maven 2 javax ws rs jsr3 1 1 api 1 1 jsr311 api 1 1 jar e asm jar http repol maven org maven2 asm asm 3 1 asm 3 1 jar and optionally for WADL support if using Java SE 5 e jaxb impl jar http download java net maven 1 com sun xml bind jars jaxb impl 2 1 12 jar e jaxb api jar http download java net maven 1 javax xml bind jars jaxb api 2 1 jar e activation jar http download java net maven 1 javax activation jars activation 1 1 jar e stax api jar http download java net maven 1 javax xml stream jars stax api 1 0 2 jar For Ant developers the Ant Tasks for Maven http maven apache org ant tasks htm
29. of parameter name to values then for query and path parameters it is possible to do the following 13 Overview of JAX RS 1 1 Example 2 17 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 j Ope WBN ER For header and cookie parameters the following Example 2 18 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 Ope WN FR In general Context http jsr311 java net nonav releases 1 1 javax ws rs core Context html can be used to obtain contextual Java types related to the request or response For form parameters it is possible to do the following Example 2 19 Obtaining general map of form parameters 1 POST 2 Consumes application x www form urlencoded 3 public void post MultivaluedMap lt String String gt formParams 4 5 Store the messag 2 4 Representations and Java Types Previous sections on Produces http jsr311 java net nonav releases 1 1 javax ws rs Produces html and Consumes http jsr311 java net nonav releases 1 1 javax ws rs Consumes html referred to MIME media types of represe
30. possible to build the request URI before building the request For example the following appends a new path segment and adds some query parameters WebResource r c resource http localhost 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 30 Client API 3 5 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 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 http download java net maven 2 com sun jersey samples jaxb 1 9 ea01 jaxb 1 9 ea01 project zip to see how JAX
31. project zip Example 2 1 Simple hello world root resource class package com sun ws rest samples helloworld resources import javax ws rs GET import javax ws rs Produces import javax ws rs Path The Java class will be hosted at the URI path helloworld Path helloworld public class HelloWorldResource OANA O FPWN FE wo 10 11 The Java method will process HTTP GET requests 12 GET 13 The Java method will produce content identified by the MIME Media 14 type text plain ES Produces text plain 16 public String getClichedMessage 17 Return some cliched textual content 18 return Hello World 19 20 Let s look at some of the JAX RS annotations used in this example 2 1 1 Path The Path http jsr311 java net nonav releases 1 1 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 he1 lowor1d This Overview of JAX RS 1 1 2 1 2 is an extremely simple use of the Path http jsr311 java net nonav releases 1 1 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
32. short the XML namespace support means you should be able to use the very same JAXB beans for XML and JSON even if XML namespaces are involved 45 JSON Support Namespace mapping definition is similar to Example 5 20 XML namespace to JSON mapping configuration for Jettison based mapped notation Example 5 16 XML namespace to JSON mapping configuration for mapped notation 1 Map lt String String gt ns2json new HashMap lt String String gt 2 ns2json put http example com example 3 context new JSONJAXBContext 4 JSONConfiguration mapped 5 xml2JsonNs ns2json build types Dot character will be used by default as a namespace separator in the JSON identifiers E g for the above mentioned example namespace and tag T example T JSON identifier will be generated To change this default behaviour you can use the nsSeparator method on the mapped JSONConfiguration builder JSONConfiguration mapped xml2JsonNs ns2json nsSeparator build Then you will get example T instead of example T generated This option should be used carefully as the Jersey framework does not even try to check conflicts between the user selected separator character and the tag and or namespace names 5 2 2 2 Natural notation After using mapped JSON notation for a while it was apparent that a need to configure all the various things manually could be a bit problematic To avoid the manual work a new natural
33. specific servlet and pass the Application http jsr3 1 1 java net nonav releases 1 1 javax ws rs core Application html implementation class name as one of the servlet s init paranm entries Example 2 12 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 ha 10 lt servlet gt 11 12 lt web app gt Alternatively a simpler approach is to let Jersey choose the PackagesResourceConfig implementation automatically by declaring the packages as follows Example 2 13 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 7 8 lt param name gt com sun jersey config property packages lt param name gt lt param value gt org foo rest org bar rest lt param value gt lt init param gt 9 Dad 10 lt servlet gt 11 Lai 12 lt web app gt JAX RS also provides the ability to obtain a container specific artifact from an Applicatio
34. to their parent For instance the following are examples of action resources http orders 1 review http orders 1 pay http orders 1 ship for purchase order 1 identified by http orders 1 Action resources as first class citizens provide the necessary tools for developers to implement HATEOAS A set of action resources defines via their link relationships a contract with clients that has the potential to evolve over time depending on the application s state For instance assuming purchase orders are only reviewed once the review action will become unavailable and the pay action will become available after an order is reviewed 10 1 2 Hypermedia by Example The notion of action resources naturally leads to discussions about improved client APIs to support them Given that action resources are identified by URIs no additional API is really necessary but the use of client side proxies and method invocations to trigger these actions seems quite natural Additionally the 62 Experimental Features use of client proxies introduces a level of indirection that enables better support for server evolution i e the ability of a server s contract to support certain changes without breaking existing clients Finally it has been argued that using client proxies is simply more natural for developers and less error prone as fewer URIs need to be constructed Rather than presenting all these extensions abstractly
35. 1 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 16 Overview of JAX RS 1 1 Example 2 24 Sub resource methods 1 Singleton 2 Path printers 3 public class PrintersResource 4 5 GET 6 Produces application json application xml y 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 TreeModel getTree 20 21 GET Path ids printerid 22 Produces application json application xml 23 public Printer getPrinter PathParam printerid 24 25 PUT Path ids printerid 26 Consumes application json application xml 27 public void putPrinter PathParam printerid 28 29 DELETE Path ids printerid 30 public void deletePrinter PathParam printerid 31 String printerld String printerld Printer String printerld If the path of the request URL is printers then the resource methods not annotated with Path http jsr3 11
36. 2 12 Deployment of your application using Jersey specific servlet ooooccoccnncnnccnnccnnccnnccnnccnnions 11 2 13 Using Jersey specific servlet without an application model instance eee eeee teen 11 2 14 Query PALAMEtEDS 2 gece eek coli ines Sroeaes eat E ons tds 12 2 15 Custom Java type for consuming request parameters ocoooccoccnocnnccnnccnnconnconnccnncnnncnnncnnncnnnss 12 2 16 Processing POSTed HTML form 200 0 00 cc cece ence nece ence eeeeceeseeseaeseaesea sean sean eeaes 13 2 17 Obtaining general map of URI path and or query parameters oocooconccnnccnnconnccnnconnconiconicnnose 14 2 18 Obtaining general map of header parameters 00 ee cece cece ce neces ce ence eeeeeceeeeeeeeaeeenes 14 2 19 Obtaining general map of form parameters ooccoccnnccnnconnccnnccnnconnconnconnronornnrnnronccnnccnniinno 14 2 20 Using File with a specific MIME type to produce a response ooccooccnnccnnconnconncnnncnnncnunonose 15 2 21 The most acceptable MIME type is used when multiple output MIME types allowed 15 2 22 Returning 201 status code and adding Location header in response to POST request 16 2 23 Adding an entity body to a custom response eee eect e cence reece cee ece eect eeeeeeeeeeeeeeeaeeenes 16 2 24 Sub resource methods diiniita tn eg sede EEE EEE a E S T 17 2 25 Sub resQutce LOCALS criadores tiene rd iiO iaa Des lotto ateo ssa pra 18 2 26 URI build oia ari 19 2 27
37. B with XML and JSON can be utilized with the client API more specifically see the unit tests 3 6 Adding support for new representations The support for new 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 http download java net maven 2 com sun jersey samples entity provider 1 9 ea0 1 entity provider 1 9 ea01 project zip sample for such implementations utilized on the server side Classes or implementations of the provider based interfaces need to be registered witha ClientConfig 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 3 7 Using filters Filtering requests and responses can provide useful functionality that is hidden
38. FoundException ex 5 return Response status 404 6 entity ex getMessage 7 type text plain 8 build 9 10 The above class is annotated with Provider http jsr311 java net nonav releases 1 1 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 jsr311 java net nonav releases 1 1 javax ws rs core Application html instance that is configured When an application throws an EntityNotFoundException http java sun com javaee 5 docs api javax persistence EntityNotFoundException html the toResponse method of the Entit yNotFoundMapper instance will be invoked 2 9 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 jsr3 11 java net nonav releases 1 1 javax ws rs core Request html The following example shows conditional GET support from the sparklines sample 21 Overview of JAX RS 1 1 Example 2 31 Conditional GET support 1 public SparklinesResource 2 QueryParam d In
39. If there is a need for some other non default XML representation other JAXB annotations would need to be used This process is usually simplified by generating java source from XML Schema which is done by xjc Xjc is XML to java compiler and is part of JAXB See JAXB home page http jaxb java net for further details 4 3 POJOs Sometimes you can t don t want to add JAXB annotations to source code and you still want to have resources consuming and producing XML representation of your classes In this case JAXBElement class should help you Let s redo planet resource but this time we won t have XmlRootElement annotation on Planet class Example 4 5 Resource class JAXBElement 1 Path planet 2 public class Resource 3 4 GET 5 Produces MediaType APPLICATION_XML 6 public JAXBElement lt Planet gt getPlanet i Planet p new Planet 8 p id 1 9 p name Earth 10 p radius 1 0 11 1 2 return new JAXBElement lt Planet gt new OName planet Planet class p 13 14 15 POST 16 Consumes MediaType APPLICATION_XML 17 public void setPlanet JAXBElement lt Planet gt p 18 System out println setPlanet p getValue 19 20 37 XML Support As you can see everything is little more complicated with JAXBElement This is because now you need to explicitly set element name for Planet class XML representation Client side is even more ugly than server side because you can
40. Jersey 1 9 ea01 User Guide Jersey 1 9 ea01 User Guide Table of Contents O ix Te Getting Started nata A ON nl ih ceeds ee cw eset oir 1 1 1 Creating aroot T SQUICO ci 3 e isc ecs ciones cerrar e trienios reali 2 1 2 Deploying the root resource seisis teene Eere ES KE EEKE EIES EEEIEE EEIEIEE EEAS 3 1 3 Testing the root resourser p a bat e EE T EE de GEES 3 1 4 Here s one Paul created earlier oooonccoccnnccnnconnconoconoconoconcnnnconrnnccnnccnnccnnccnnccnnccnncos 4 2 OvervieW of JAX RS lid ias arepa iento P o 5 2 1 Root Resource Classes isise r ti is 5 O Path A NO 5 21 2 HITP Methods econ A A AS 6 2 1 3 OPLOUCES pere arsso rro 7 214 CONSUMes cm tas Dobe casts end oust daria isc 9 2 2 Deploying a RESTful Web Service siistia ea non ap a Et 9 2 3 Extracting Request Parameters ooooccocccccnnnccnncnnconnconnconnccnnconnconnconncnnncnnncnnronaranicnnos 11 2 4 Representations and Java Types s is cscsssssbsesgseessssessctesdhe Ties EEPE EEES eaS rai aSo 14 2 3 Building RESPONSES seisin niere anes Way dudes cneebis ae EEE EE eg deests KEETE IA E 15 2 6 SUB FESOUICES aiiora ape a E ceatta neu E TE E a E T Ea SE sas atte 16 2 1 Building URB oia A es ee el aa 18 2 8 WebApplicationException and Mapping Exceptions to Responses cce eeeeeee ee ee 20 2 9 Conditional GETs and Returning 304 Not Modified Responses ooccocccocccnccnnccnnccnnions 21 2 10 Life cycle of Root Resource
41. RLConnection classes supplied with the JDK and the Apache HTTP client 3 2 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 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 26 Client API 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 ide
42. a net maven 2 com sun grizzly grizzly servlet webserver 1 9 18 1 grizzly servlet webserver 1 9 18 1 jar grizzly http http download java net maven 2 com sun grizzly grizzly http 1 9 18 1 grizzly http 1 9 18 i jar grizzly framework http download java net maven 2 com sun grizzly grizzly framework l 9 18 i grizzly framework 1 9 18 i jar grizzly utils http download java net maven 2 com sun grizzly grizzly utils 1 9 18 1 grizzly utils 1 9 18 1 jar grizzly rcm http download java net maven 2 com sun grizzly grizzly rem 1 9 18 1 grizzly rcm 1 9 18 i jar grizzly portunif http download java net maven 2 com sun grizzly grizzly portunif 1 9 18 i grizzly portunif 1 9 18 i jar grizzly http servlet http download java net maven 2 com sun grizzly grizzly http servlet 1 9 18 i grizzly http servlet 1 9 18 i jar servlet api http repo1 maven org maven2 javax servlet servlet api 2 5 servlet api 2 5 jar This is needed to run helloworld sample tests if you want run something more complex or with different test container grizzly is used here you may need to add other application specific dependencies and remove some as well As was already written above Jersey test is descendant of standard unit test so it can be run same way You can execute it by executing org junit runner JUnitCore and passing your test class name as parameter from ant junit task http ant apache org manual OptionalTasks junit html or whateve
43. and bean setter methods The following presents an example of all such injection cases 23 Overview of JAX RS 1 1 Example 2 33 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 Li 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 19 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 25 public void setHeader String header 26 There 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 sr311 java net nonav releases 1 1 javax ws rs core Context html annotation on fields in such cases a thread local proxy will be injected The FormParam http jsr311 java net nonav releases
44. aven 2 com sun jersey jersey server 1 9 ea0 1 jersey server 1 9 ea01 jar e jersey core jar http download java net maven 2 com sun jersey jersey core 1 9 ea0 1 jersey core 1 9 ea01 jar e asm jar http repol maven org maven2 asm asm 3 1 asm 3 1 jar or if using the jersey bundle e jersey bundle jar http download java net maven 2 com sun jersey jersey bundle 1 9 ea01 jersey bundle 1 9 ea01 jar e asm jar http repol maven org maven2 asm asm 3 1 asm 3 1 jar For Ant developers the Ant Tasks for Maven http maven apache org ant tasks html may be used to add the following to the ant document such that the dependencies do not need to be downloaded explicitly lt artifact dependencies pathId dependency classpath gt lt dependency grouplId com sun jersey artifactld jersey server version 1 9 ea01 gt lt artifact remoteRepository id maven2 repository java net url http download java net maven 2 gt lt artifact remoteRepository id maven repository java net url http download java net maven 1 layout legacy gt lt artifact dependencies gt The path id dependency classpath may then be referenced as the classpath to be used for compiling or executing Specifically the asm jar http repol maven org maven2 asm asm 3 1 asm 3 1 jar dependency is required when either of the following com sun jersey api core ResourceConfig http jersey java net nonav apidocs 1 9 ea01 jersey
45. aven 2 com sun jersey jersey server 1 9 ea0 1 jersey server 1 9 ea01 jar jersey core http download java net maven 2 com sun jersey jersey core l 9 ea01 jersey core 1 9 ea01 jar jsr311 api http download java net maven 2 avax ws rs sr311 api 1 1 sr311 api 1 1 jar asm http repol maven org maven2 asm asm 3 1 asm 3 1 jar jersey test framework grizzly http download java net maven 2 com sun jersey jersey test framework jersey test framework grizzly 1 9 ea01 jersey test framework grizzly 1 9 ea01 jar jersey test framework core http download java net maven 2 com sun jersey jersey test framework jersey test framework core l 9 ea01 jersey test framework core 1 9 ea01 jar 55 Jersey Test Framework jersey client http download java net maven 2 com sun jersey jersey client 1 9 ea01 jersey client 1 9 ea01 jar javax servlet http download java net maven glassfish org glassfish javax servlet 3 0 b66 javax servlet 3 0 b66 jar junit http repol maven org maven2 junit junit 4 5 junit 4 5 jar jaxb impl http download java net maven 2 com sun xml bind axb impl 2 1 jaxb impl 2 1 jar jaxb api http download java net maven 2 javax xml bind jaxb api 2 1 jaxb api 2 1 jar stax api http repo1 maven org maven2 javax xml stream stax api 0 2 stax api 1 0 2 jar activation http repol maven org maven 2 javax activation activation 1 1 activation 1 1 jar grizzly servlet webserver http download jav
46. com sun jersey api client WebResource html instance is created from a Client http jersey java net nonav apidocs 1 9 ea0 1 jersey com sun jersey api client Client html then the Form instance is POSTed to the resource identified with the form media type and the response is requested 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 3 4 Getting started with the Jersey client Refer to the dependencies chapter chapter_deps and specifically the Core client 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 1 9 ea01 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 l 9
47. configuration point in this area To pass your specialized JSONJAXBContext to Jersey you will finally need to implement a JAXBContext ContextResolver lt T gt http jsr3 11 java net nonav releases 1 1 javax ws rs ext ContextResolver html Example 5 6 An example of a JAXBContext resolver implementation 1 Provider 2 public class JAXBContextResolver implements ContextResolver lt JAXBContext gt 3 4 private JAXBContext context 5 private Class types MyJaxbBean class 6 7 public JAXBContextResolver throws Exception 8 this context 9 new JSONJAXBContext H 10 JSONConfiguration natural build types A 11 12 13 public JAXBContext getContext Class lt gt objectType 14 for Class type types T5 if type objectType 16 return context 7 18 19 return null 20 21 53 Creation of our specialized JAXBContext Final JSON format is given by this JSONConfiguration instance 5 2 2 JSON Notations JSONConfiguration allows you to use four various JSON notations Each of these notations serializes JSON in a different way Following is a list of supported notations 42 JSON Support MAPPED default notation NATURAL JETTISON_MAPPED e BADGERFISH Individual notations and their further configuration options are described bellow Rather then explaining rules for mapping XML constructs into JSON the notations will be described using a simple example Following are JAXB bean
48. core 1 9 ea01 jar or if using the jersey bundle e jersey bundle jar _ http download java net maven 2 com sun jersey jersey bundle 1 9 ea0 1 jersey bundle 1 9 ea01 jar The use of client with the Apache HTTP client to make HTTP request and receive HTTP responses requires a dependency on the jersey apache client http download java net maven 2 com sun jersey contribs jersey apache client 1 9 ea01 jersey apache client 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupId gt com sun Jersey contribs lt groupId gt lt artifactId gt jersey apache client lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt 11 3 Container 11 3 1 Grizzly HTTP Web server Maven developers deploying an application using the Grizzly HTTP Web server require a dependency on the jersey grizzly http download java net maven 2 com sun jersey jersey grizzly 1 9 ea0 1 jersey 71 Dependencies grizzly 1 9 ea01 pom and grizzly servlet webserver http download java net maven 2 com sun grizzly grizzly servlet webserver 1 9 18 1 grizzly servlet webserver 1 9 18 1 pom module Non maven developers require jersey grizzly jar http download java net maven 2 com sun jersey jersey grizzly 1 9 ea01 jersey grizzly 1 9 ea01 jar and grizzly servlet webserver jar http download java net maven 2 com sun grizzly grizzly servlet webserver 1 9 18 i grizzly servl
49. d status code and a Location header whose value is the URI to the newly created resource This may be achieved as follows 15 Overview of JAX RS 1 1 Example 2 22 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 2 23 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 7 Response building provides other functionality such as setting the entity tag and last modified date of the representation 2 6 Sub resources Path http jsr3 11 java net nonav releases 1 1 javax ws rs Path html may be used on classes and such classes are referred to as root resource classes Path http jsr3 11 java net nonav releases 1 1 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 jsr311 java net nonav releases 1
50. ddresses street S Long Street 1 4 town S Short Village Examples Download http download java net maven 2 com sun jersey samples json from jaxb 1 9 ea0 1 json from jaxb 1 9 ea01 project zip or http download java net maven 2 com sun jersey samples maki backend 1 9 ea01 maki backend 1 9 ea01 project zip to get a more complex example using JAXB based JSON support 5 3 Low Level JSON support Using this approach means you will be using JSONObject and or JSONArray classes for your data representations These classes are actually taken from Jettison project but conform to the description provided at http www json org java index html http www json org java index html The biggest advantage here is that you will gain full control over the JSON format produced and consumed On the other hand dealing with your data model objects will probably be a bit more complex than when taking the JAXB based approach Differencies are depicted at the following code snipets Example 5 23 JAXB bean creation MyJaxbBean myBean new MyJaxbBean Agamemnon 32 Above you construct a simple JAXB bean which could be written in JSON as name Agamemnon age 32 Now to build an equivalent JSONObject in terms of resulting JSON expression you would need several more lines of code 48 JSON Support Example 5 24 Constructing a JSONObject 1 JSONObject myObject new JSONOb ject 2 myObject JSONObject
51. deess seek gas ee ceaes eho hee cove dees seek lacie nit EASi 50 6 2 Binding Template Parameters oooconoconnconccnnccnnonnncnnncnnnronncnnconnconncnnncrnnconnconnconaconnss 50 6 3 Conditional Link Injection zsrsr enea corsa seen deeply den ghee ES ES NEE teense panes 51 64 Emk Headers csi dilo dto rior eee eee 51 AA A E ON 51 7 Jersey Test Framework ui iS Eas 53 7 1 What 1s different In Jersey Bcn iran tope 53 Tez Using test framework vii 53 Ro Creatine LOSES 2 a4 soph NN 54 1A Creating own Module a A N ved 55 7 5 Running tests outside Maven endep dereen ep ara E E EEAS pE TI NEE SR EE pE 55 8 OSG E E E E E S 57 8 Li Feature Overview menene ONO 57 8 22 WAB Example in A A eens 58 8 3 Http Service A NS 58 9 JRebel Support oir Tin cass A A 60 9 1 Howto use JRebel with Jersey csini a Son guyanen se ous hasan NEEESE 60 9 2 Using JRebel with the hello world sample ooooccocccnccnnconnccnnconnconnconoconacnnacnncnnnronnss 60 93 Limitations eege dsarenecen shee snenesoe bat a tusmesee ned E EE eeadueeheed oes EE 61 10 Experimental Feat iaa di RA A A aL a ae E 62 10 1 HypermediaACUO S svie si cites tinca gles o S E sues saunesen EE EE E e NAE ESAS 62 A e AAA NS 62 10 1 2 Hypermedia by Example yore pna en o pea E E ENEEK E 62 10 13 Server AP itis ae tee ees R esas Hanada eda gee 63 10 V4 Client AP 3 scoot Sods ch aeenesetdes dosed n Soh ssewue a EAE odedub en supe E 65 LOS Server EVO A ree ee
52. e 2 Produces text plain 3 public class SomeResource 4 GET 5 public String doGetAsPlainText 6 i 8 9 GET 10 Produces text html 11 public String doGetAsHtml 12 13 14 The doGetAsPlainText method defaults to the MIME type of the Produces http jsr3 11 java net nonav releases 1 1 javax ws rs Produces htm1 annotation at the class level The doGet AsHt m1 method s Produces http jsr3 1 1 java net nonav releases 1 1 javax ws rs Produces html annotation overrides the class level Produces http jsr3 11 java net nonav releases 1 1 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 doGetAsHtm1 method will be invoked More than one media type may be declared in the same Produces http jsr311 java net nonav releases 1 1 javax ws rs Produces html declaration for example
53. e Dose Te DE eee es 67 10 1 6 Configuring Hypermedia in Jersey ooocccooccnnnoccnnccnnnnccnnnncnnnccnnnnconnnccnnninnns 67 11 Dependencia ii EA Gab Goa Pelee Bae RR Sa 69 VU E seetiaae 69 112 Cores chent reei ni A E cc ude O Asa 71 ELIO Coti ais 71 11 3 1 Grizzly HTTP WebSite ns uote teeta teed 71 113 22 Simple HTTP Web Server ss sen esen2 ee S boaneueedened ots dav nave davenawet EAN 72 11 3 3 Light weight HTTP server 2 0 0 0 eee cee ce ee EE E EE A ES ES 72 USAS letal 72 TIA Entity anos A Sea o es lo aetna ee ea 72 O 72 PU A2 Atom ON 74 11 43 JSON codo ad id td ae 74 11 4 4 Mail and MIME multipart oooconnconccnnccnnncnncnnncnnncnnncnnccnnconnccnnconnccnnconacinacos 75 LAS ACTIVATION estonio trino aA dawety E der E E E 75 MUS LOOMS A OR he dui adele he aerate 75 F16 NN 76 TLT GUCE a IS SEE a ees Shean E ASE 76 111 8 Jersey Test Framework resnicno ee e aE ae a tirao dador ds 76 12 Jersey with GlassPishi id AE ROA ES inn 79 12 1 Overriding Jersey with war files ooocoooccnnconconoconccnnncnnncnnnonoroncnnccnnccnnccnnccnnions 79 12 2 Upgrading Jersey in GlassFish noirs aae cc cece ence ence ences E E O ERS 79 1v Jersey 1 9 ea01 User Guide IEEE EIA AAA oes pane abet ouuansspeien thay een teens eerenebeemens 79 12 22 GlassFish Dd a Rias 80 13 Building and testing Jersey tonto eat ile ironia loser tfno 82 13 1 Checking out the Source vii a iaa ER a 82 13 2 Buulding Use Mav
54. e a look at helloworld sample pom file There is declared dependency on 53 Jersey Test Framework lt dependency gt lt groupiId gt com sun jersey jersey test framework lt groupId gt lt artifactId gt jersey test framework grizzly2 lt artifactId gt lt version gt S project version lt version gt lt scope gt test lt scope gt lt dependency gt which means that Grizzly Web container version 2 x will be used for testing You can specify more than one module in dependencies and choose which module will be used by jersey test containerFactory property Every module should contain at least one container factory jersey test framework grizzly com sun jersey test framework spi container grizzly web Gr com sun jersey test framework spi container grizzly Grizzl jersey test framework grizzly2 com sun jersey test framework spi container grizzly2 web G com sun jersey test framework spi container grizzly2 Grizz jersey test framework http com sun jersey test framework spi container http HTTPConta jersey test framework com sun jersey test framework spi container inmemory InMem inmemory jersey test framework com sun jersey test framework spi container embedded glass embedded glassfish jersey test framework external com sun jersey test framework spi container external Exter Basically you can just add dependency on single module and its container factory would be used Probl
55. e cece ace n eens eeeeeeeeceeeeeeseaeeeaeeea seas eeges 39 5 1 POJO JSON support web xml configuration oocoocccnccnnconnccnnccnnconoconncnnncnnonnnronnrnnccnnccnninnno 40 5 2 POJO JSON support client configuration eee cee cece eee ce teen toca cena eeaeeeueeeneeeeeees 40 5 3 Simple JAXB bean implementation 2 0 0 0 eee cece cece cece cece a eece cena cena een eeeeeeeeeeeeeeeeeaees 41 5 4 JAXB bean used to generate JSON representation coooccncccnccnncnnncnnccnnccnnconnccnnccnnccnnconnconncos 41 5 5 Tweaking JSON format using JAX Boissieres sesioen iotas ipani reep sE PTR EEI TEIS EaR EDISE VS 42 5 6 An example of a JAXBContext resolver implementation ooocccoccnnccnnconiconncnnncnnnconocnninnnnnnns 42 5 7 JAXB beans for JSON supported notations description simple address bean 006 43 5 8 JAXB beans for JSON supported notations description contact bean ccc eee ee eee eee 43 5 9 JAXB beans for JSON supported notations description initialization 0c cece cece eee 43 Vil Jersey 1 9 ea01 User Guide 5 10 5 11 5 12 5 13 5 14 5 15 5 16 5 17 5 18 5 19 5 20 5 21 5 22 5 23 5 24 JSON expression produced using mapped notation oooconccnnccnnccnnncnncnnnrnnarnnccnnccnnccnnccnnioos 44 Force arrays in mapped JSON notation 20 0 0 0c ceeeeececc nec eceeceeeecaeeeecaeeeeeaeeeeaeeneeaeeneeas 44 Force non string values in mapped JSON notation ooco
56. ea01 contribs jersey apache client index html for details on how to use the Jersey client API with the Apache HTTP client 3 5 Overview of the API 3 5 1 To utilize the client API it is first necessary to create an instance of a Client http jersey java net nonav apidocs 1 9 ea01 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 get Properties 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 1 9 ea01 jersey com sun jersey api client config ClientConfig html object for example ClientConfig cc new DefaultClientConfig cc getProperties put ClientConfig PROPERTY_FOLLOW_REDIRECTS true 28 Client API 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 1 9 ea01 jersey com sun jersey api client WebResource html instance which will inhe
57. ed to generate JSON representation 1 GET Produces application json 2 public MyJaxbBean getMyBean 3 return new MyJaxbBean Agamemnon 32 4 Notice that JSON specific mime type is specified in Produces annotation and the method returns an instance of MyJaxbBean which JAXB is able to process Resulting JSON in this case would look like name Agamemnon age 32 Configuration Options JAXB itself enables you to control output JSON format to certain extent Specifically renaming and ommiting items is easy to do directly using JAXB annotations E g the following example depicts changes in the above mentioned MyJaxbBean that will result in king Agamemnon JSON output 41 JSON Support Example 5 5 Tweaking JSON format using JAXB 1 XmlRootElement 2 public class MyJaxbBean 3 4 XmlElement name king 5 public String name 6 a XmlTransient 8 public int age 9 10 several lines removed 11 To achieve more important JSON format changes you will need to configure Jersey JSON procesor itself Various configuration options could be set on an JSONConfiguration http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api json JSONConfiguration html instance The instance could be then further used to create a JSONConfigurated JSONJAXBContext http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api json JSONJAXBContext html which serves as a main
58. eleases 1 1 javax ws rs Path html value may or may not begin with a it makes no difference Likewise by default a Path http jsr311 java net nonav releases 1 1 javax ws rs Path html value may or may not end in a it makes no difference and thus request URLs that end or do not end in a will both be matched However Jersey has a redirection mechanism which if enabled automatically performs redirection to a request URL ending in a if a request URL does not end in a and the matching Path http jsr3 1 1 java net nonav releases 1 1 javax ws rs Path html does end ina HTTP Methods GET http jsr311 java net nonav releases 1 1 javax ws rs GET html PUT http jsr311 java net nonav releases 1 1 javax ws rs PUT html EPOST http sr311 java net nonav releases l 1 javax ws Overview of JAX RS 1 1 2 1 3 rs POST html DELETE http jsr311 java net nonav releases 1 1 javax ws rs DELETE html and HEAD http jsr311 java net nonav releases 1 1 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 contain
59. em is when you specify module which has more than one container factory or multiple modules If this happen test framework will choose factory using following rules if jersey test containerFactory not specified look for factories if factories count 1 use found factory else if com sun jersey test framework spi container grizzly2 web GrizzlyWebTest use it current default jersey test container factory else use first found and log warning else use factory class specified in jersey test containerFactory That means if your project depends on multiple test framework modules and you want to control which will be used you have to declare which one in property called jersey test containerFactory for example like this mvn clean install Djersey test containerFactory com sun jersey test framework spi container inmemory 7 3 Creating tests Jersey Test Framework uses JUnit version 4 X so if you can write standard unit tests you can easily create Jersey Test You need to declare test as a descendant of JerseyTest class 54 Jersey Test Framework public class MainTest extends JerseyTest public MainTest throws Exception super com sun jersey samples helloworld resources Test public void testHelloWorld WebResource webResource resource String responseMsg webResource path helloworld get String class assertEquals Hello World responseMsg Note supe
60. en sereen ce sesh vss sys sun des doi deep es yy Sue 82 INIA TESORO a E 83 13 4 Continuous building and testing with Hudson ooccoccnnccnccnnncnnccnnccnnconnccnnccnnccnncnnnoos 83 15 55 Using NetBeans ii ld eects Rea ety lett tes 83 List of Tables 7 1 Property name changes vi List of Examples 2 1 Simple hello world root resource Class oocoocccoccnnconnccnnccnncnnoconoconcnnncnnnonnroncrnnconnccnnccnnions 5 2 2 Specifying URI path parameter oooccoccnnccnnconnccnncnnnconnconncnnncnnnnnnrnnnrnn ron cono con ncrnnccnnconncnnncos 6 2 3 PUT Method air A ESEE A Ea aee REE VISE REPERES T 2 4 Specifying output MIME type 2 0 0 0 eee ceec nec ce cence cece ne ceneceeeeeeceeeeeesaeeeaeeea seen seas eeaes 8 2 5 Using multiple output MIME types 00 0 0 ee cece cece cece c nce ip iee TEE sean scans 8 2 6 Specifying input MIME type 0 00 0 eee ceee eee cnec ca eeca ceca cena eens een censeeeeeeeeeesseeseaeseaeeeaes 9 2 7 Deployment agnostic application model ocooocnnccnnccnnccnncnnncnnocnnccnnconnccnnccnnccnnconnconncnnncnnnss 9 2 8 Reusing Jersey implementation in your custom application model 0 ceeeeeee ee ee eee eee 9 2 9 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 10 2 10 Configuration of maven war plugin in pom xml with Servlet 3 0 0 0 cece eee eee eee 10 2 11 Deployment of a JAX RS application using web xm1 with Servlet 3 0 0 0 eee 10
61. er Example 2 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 noContent build 13 14 15 MemoryStore MS createContainer c 16 return r dept 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 jsr3 11 java net nonav releases 1 1 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 jsr311 java net nonav releases 1 1 javax ws rs Produces html can be applied at both the class and method levels Here s an example Overview of JAX RS 1 1 Example 2 4 Specifying output MIME type 1 Path myResourc
62. es 1 9 ea01 project zip and unzip it s content into the GlassFish installation directory 80 Jersey with GlassFish To be 100 sure the changes take effect you might also want to remove the felix cache which is located in glassfish domains domainl osgi cache directory This directory gets created upon the first start of the GlassFish instance 81 Chapter 13 Building and testing Jersey 13 1 Checking out the source The Jersey source code is available from the Subversion repository located at http java net projects jersey sources svn show To check out the trunk where active development on the next release occurs use the following command svn checkout https svn java net svn jersey svn trunk jersey jersey username lt u If you are new to Subversion you may want to visit the Subversion Project website http subversion tigris org and read Version Control with Subversion http svnbook red bean com Read more about how to checkout this project s repository http jersey java net servlets ProjectSource Stable releases of Jersey are tagged in the location http jersey java net svn jersey tags The source code may be browsed using FishEye http fisheye4 atlassian com browse jersey 13 2 Building using Maven Java SE 6 or greater is required Maven 2 2 1 or greater is recommended It is recommended to build the whole of Jersey after you have initially checked out the source code To build all
63. et webserver 1 9 18 i jar 11 3 2 Simple HTTP Web server Maven developers deploying an application using the Simple HTTP Web server require a dependency on the jersey simple server http download java net maven 2 com sun jersey contribs jersey simple server 1 9 ea01 ersey simple server 1 9 ea01 pom module 11 3 3 Light weight HTTP server Deploying an application using the light weight HTTP server requires no additional dependences as Java SE 6 already contains everything needed 11 3 4 Servlet Deploying an application on a servlet container requires a deployment dependency with that container See the Java documentation here http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey spi container servlet package summary html on how to configure the servlet container Using servlet com sun jersey spi container servlet ServletContainer requires no additional dependences Maven developers using servlet com sun jersey server impl container servlet ServletAdaptor in a non EE 5 servlet require a dependency on the persistence api http download java net maven 1 javax persistence poms persistence api 1 0 2 pom module Non Maven developers require persistence api jar http download java net maven 1 javax persistence jars persistence api 1 0 2 jar 11 4 Entity 11 4 1 JAXB XML serialization support of Java types that are JAXB beans requires a dependency on the JAXB reference implementation version
64. eturn uriArray 20 Dale 1 Urilnfo http jsr3 1 1 java net nonav releases 1 1 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 sr311 java net nonav releases l 1 javax ws rs core Urilnfo html can be used to obtain URIs and associated UriBuilder http jsr311 java net nonav releases 1 1 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 resource The URI is built from the absolute path of the request URI by calling Urilnfo getAbsolutePathBuilder http jsr311 java net nonav releases 1 1 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 sr311 java net nonav releases 1 1 javax ws rs core UriBuilder html can be used to build replace query or matrix parameters URI template
65. ey documentation and examples you would need to do the following steps Remove the existing Jersey files Stop all running server instances Then remove the following files from the GlassFish installation directory e glassfish modules jersey core jar glassfish modules jersey client jar glassfish modules jersey gf server jar glassfish modules jersey json jar glassfish modules jersey multipart jar glassfish modules jersey gf statsproviders jar glassfish modules jackson core asl jar glassfish modules jackson mapper asl jar glassfish modules jackson jaxrs jar e glassfish modules jettison jar Download the new Jersey version archive from http download java net maven 2 com sun jersey glassfish v3 jersey gfv3 core 1 9 ea01 jersey gfv3 core 1 9 ea01 project zip http download java net maven 2 com sun jersey glassfish v3 jersey gfv3 core 1 9 ea0 1 jersey gfv3 core 1 9 ea0 1 project zip and unzip it s glassfish modules content into the GlassFish installation directory to the glassfish modules subdirectory there To install also Jersey examples in addition download you can change the version in the link to get another non snapshot version of Jersey http download java net maven 2 com sun jersey glassfish v3 jersey gfv3 docs and samples 1 9 ea01 jersey gfv3 docs and samples 1 9 ea01 project zip http download java net maven 2 com sun jersey glassfish v3 jersey gfv3 docs and samples l 9 ea01 jersey gfv3 docs and sampl
66. he model to a URI Refer to hypermedia action sample http download java net maven 2 com sun jersey experimental hypermedia action hypermedia action sample for more information on how this mapping is implemented 10 1 3 Server API The server API introduces 3 new annotation types Action ContextualActionSet and HypermediaController The Action annotation identifies a sub resource as a named action The ContextualActionSet is used to support contextual contracts and must annotate a method that returns a set of action names Finally HypermediaController marks a resource class as a hypermedia controller class a class with one more methods annotated with Act ion and at most one method annotated with ContextualActionSet The following example illustrates the use of all these annotation types to define the OrderResource controller Path orders id HypermediaController model Order class linkType LinkType LINK_HEADERS public class OrderResource private Order order 0 J004asyuyNpa Several details about this class are omitted for clarity The reader is referred to the hypermedia sample for more details 63 Experimental Features 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 21 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 GET Produces application xml public Order getOrder PathParam id String id return order POST Actio n revie
67. his chapter will present how to get started with Jersey using the embedded Grizzly server The last section of this chapter presents a reference to equivalent functionality for getting started with a Web application First it is necessary to depend on the correct Jersey artifacts as described in Chapter 11 Dependencies Maven developers require a dependency on e the jersey server http download java net maven 2 com sun jersey jersey server 1 9 ea0 1 jersey server 1 9 ea01 pom module e the grizzly servlet webserver http download java net maven 2 com sun grizzly grizzly servlet webserver 1 9 18 i grizzly servlet webserver 1 9 18 i pom module e and optionally for WADL support if using Java SE 5 the jaxb impl http download java net maven 1 com sun xml bind poms jaxb impl 2 1 12 pom module The following dependencies need to be added to the pom lt dependency gt lt groupId gt com sun jJersey lt groupld gt lt artifactId gt jersey server lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt lt dependency gt lt groupId gt com sun grizzly lt groupld gt lt artifactlid gt grizzly servlet webserver lt artifactld gt lt version gt 1 9 18 i lt version gt lt dependency gt And the following repositories need to be added to the pom lt repository gt lt id gt maven2 repository java net lt id gt lt name gt Java net Repository for Maven lt name gt lt url gt http download java
68. ion gt lt dependency gt lt dependency gt lt groupId gt com sun jersey experimental hypermedia action lt groupld gt lt artifactId gt hypermedia action client lt artifactId gt lt version gt S jersey version lt version gt lt dependency gt Last even though the annotation HypermediaController has a linkType element only the LinkType LINK_H EAD ERS option is currently supported and must be used by both clients and servers 68 Chapter 11 Dependencies 11 1 Jersey is built assembled and installed using Maven Jersey is deployed to the Java Net maven repository at the following location http download java net maven 2 http download java net maven 2 com sun jersey The Jersey modules can be browsed at the following location http download java net maven 2 com sun jersey http download java net maven 2 com sun jersey Jars Jar sources Jar JavaDoc and samples are all available on the java net maven repository A zip file containing all maven based samples can be obtained here http download java net maven 2 com sun jersey samples jersey samples 1 9 ea01 jersey samples 1 9 ea01 project zip Individual zip files for each sample may be found by browsing the samples http download java net maven 2 com sun jersey samples directory An application depending on Jersey requires that it in turn includes the set of jars that Jersey depends on Jersey has a pluggable component arch
69. itecture 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 explain 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 html very useful For the convenience of non maven developers the following are provided e A zip of Jersey http download java net maven 2 com sun j ersey jersey archive 1 9 ea01 jersey archive 1 9 ea01 zip containing the Jersey jars core dependencies it does not provide dependencies for third party jars beyond the those for JSON support and JavaDoc e A jersey bundle jar http download java net maven 2 com sun jersey jersey bundle 1 9 ea0 1 jersey bundle 1 9 ea01 jar to avoid the dependency management of multiple jersey based jars Jersey s runtime dependences are categorized into the following e Core server The minimum set of dependences that Jersey requires for the server e Core client The minimum set of dependences that Jersey requires for the client e Container The set of container dependences Each c
70. ivalent Ref value widgets id bindings Binding name id value resource id Ref widgets resource id 6 3 Conditional Link Injection Link value injection can be made conditional by use of the condition property The value of this property is a boolean EL expression and a link will only be injected if the condition expression evaluates to true E g Ref value widgets S instance id offers condition S instance offers URI offers In the above a URI will only be injected into the offers field if the of fers property of the instance is true 6 4 Link Headers HTTP Link headers http tools ietf org html draft nottingham http link header 09 can also be added to responses using annotations Instead of annotating the fields of an entity class with Ref you instead annotate the entity class itself with Link E g Link value Ref widgets S resource nextId rel next The above would insert a HTTP Link header into any response whose entity was thus annotated The Link annotation contains properties that map to the parameters of the HTTP Link header The above specifies the link relation as next All properties of the Re f annotation may be used as described above Multiple link headers can be added by use of the Links annotation which can contain multiple Link annotations 6 5 Configuration Declarative hyperlinking support is provided in the form of a filter First the ap
71. jar http download java net maven 2 org jvnet mimepull 1 3 mimepull 1 3 jar e jersey multipart jar http download java net maven 2 com sun jersey contribs jersey multipart 1 9 ea01 jersey multipart 1 9 ea01 jar 11 4 5 Activation The use of the Java type javax activation DataSource requires no additional dependencies as Java SE 6 ships everything needed 11 5 Tools By default WADL for resource classes is generated dynamically at runtime WADL support requires a dependency on the JAXB reference implementation version 2 x or higher Deploying an application for WADL support requires no additional dependences since Java SE 6 ships with JAXB 2 x support The WADL ant task requires the same set of dependences as those for runtime WADL support T9 Dependencies 11 6 Spring Maven developers using Spring 2 0 x or Spring 2 5 x require a dependency on the jersey spring http download java net maven 2 com sun jersey contribs jersey spring 1 9 ea01 jersey spring 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupId gt com sun jJersey contribs lt groupId gt lt artifactId gt jersey spring lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt See the Java documentation here http jersey java net nonav apidocs 1 9 ea0 1 contribs jersey spring com sun jersey spi spring container servlet package summary html on how to integrate Jersey ba
72. ject developers More details can be found on the project website http zeroturnaround com jrebel http www zeroturnaround com jrebel Jersey currently supports JRebel version 3 1 2 9 1 How to use JRebel with Jersey The jersey jrebel dependency is required in the pom file lt dependency gt lt groupId gt com sun jersey lt grouplid gt lt artifactId gt jersey jrebel lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt The javarebel maven plugin plugin can be added to the pom to automatically configure JRebel for the case when java is executed from maven lt plugin gt lt groupId gt org zeroturnaround lt grouplId gt lt artifactId gt javarebel maven plugin lt artifactId gt lt executions gt lt execution gt lt id gt generate rebel xml lt id gt lt phase gt process resources lt phase gt lt goals gt lt goal gt generate lt goal gt lt goals gt lt execution gt lt executions gt lt plugin gt 9 2 Using JRebel with the hello world sample The following assumes that JRebel has been set up correctly a JRebel informational message will be output if JRebel is enabled Download the hello world sample http download java net maven 2 com sun jersey samples helloworld 1 9 ea01 helloworld 1 9 ea01 project zip and modify the pom file in accordance with the prevous chapter Compile Helloworld sample with mvn clean install and run it with mvn exec java The Hellow
73. jettison jar http repo1 maven org maven2 org codehaus jettison jettison 1 1 jettison 1 1 jar jaxb impl jar http download java net maven 1 com sun xml bind jars jaxb impl 2 1 12 jar jaxb api jar http download java net maven 1 javax xml bind jars jaxb api 2 1 jar e activation jar http download java net maven 1 javax activation jars activation 1 1 jar e stax api jar http download java net maven 1 javax xml stream jars stax api 1 0 2 jar and additionally if not depending on the jersey bundle jar http download java net maven 2 com sun jersey jersey bundle 1 9 ea0 1 jersey bundle 1 9 ea01 jar non maven developers require jersey json jar http download java net maven 2 com sun jersey jersey json 1 9 ea0 1 jersey json 1 9 ea01 jar Maven developers using Fast Infoset serialization support of JAXB beans with using the MIME media type application fastinfoset require a dependency on the jersey fastinfoset http download_ java net maven 2 com sun jersey jersey fastinfoset 1 9 ea0 1 jersey fastinfoset 1 9 ea01 pom module no dependency on jaxb impl is required The following dependency needs to be added to the pom lt dependency gt lt groupid gt com sun jersey lt grouplid gt lt artifactId gt jersey fastinfoset lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt Non maven developers require e FastInfoset jar http download java net maven 1 com sun xml fastinfoset jars Fa
74. l may be used to add the following to the ant document such that the dependencies do not need to be downloaded explicitly lt artifact dependencies pathId dependency classpath gt lt dependency groupId com sun jersey artifactld jersey server version 1 9 ea01 gt lt dependency groupId com sun grizzly artifactld grizzly servlet webserver version 1 8 6 4 gt lt artifact remoteRepository id maven2 repository java net url http download java net maven 2 gt lt artifact remoteRepository id maven repository java net url http download java net maven 1 layout legacy gt lt artifact dependencies gt The path id dependency classpath may then be referenced as the classpath to be used for compiling or executing Second create a new project using your favourite IDE or just ant maven and add the dependences For those who want to skip the creation of their own project take a look at Section 1 4 Here s one Paul created earlier 1 1 Creating a root resource Create the following Java class in your project 1 The Java class will be hosted at the URI path helloworld 2 Path helloworld 3 public class HelloWorldResource 4 5 The Java method will process HTTP GET requests 6 GET 7 The Java method will produce content identified by the MIME Media 8 type text plain 9 Produces text plain 10 public String getClichedMessage
75. lass name or you can set name property XmlRootElement name yourName Our resource class will respond to GET planet with lt xml version 1 0 encoding UTF 8 standalone yes gt lt planet gt lt id gt 1 lt id gt lt name gt Earth lt name gt lt radius gt 1 0 lt radius gt lt planet gt which might be exactly what we want or not Or we might not really care because we can use Jersey client for making requests to this resource and this is easy as Planet planet webResource path planet accept MediaType APPLICATION_XML_TYPE get Planet class There is pre created WebResource object which points to our applications context root and we simpli add 36 XML Support path in our clase its planet accept header not mandatory but service could provide different content based on this header for example text html can be served for web browsers and at the end we specify that we are expecting Planet class via GET request There may be need for not just producing XML we might want to consume it as well Example 4 4 Method for consuming Planet 1 POST 2 Consumes MediaType APPLICATION_XML 3 public void setPlanet Planet p 4 System out println setPlanet p 5 6 After valid request is made with Jersey client you can do webResource path planet post p service will print out string representation of Planet which can look like Planet id 2 name Mars radius 1 51
76. lassfish stop The testHelloWorld method tests that the response to a GET request to the Web resource returns Hello World 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 3 9 Security with Http s URLConnection 3 9 1 With Http s URLConnection 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 java sun 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 java sun com javase 6 docs technotes guides net http cookie html document for more details To utilize HTTP with SSL it is necessary to
77. lic MyApplication 3 super org foo rest org bar rest 4 ai There are multiple deployment options for the class that implements Application http jsr311 java net nonav releases 1 1 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 ApplicationPath http sr311 java net nonav Overview of JAX RS 1 1 releases 1 1 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 2 9 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 1 ApplicationPath resources 2 public 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 failOnMissingWebXml http maven apache org plugins maven war plugin war mojo html failOnMissingWebXml to false in pom xml when building war without web xml file using maven Example 2 10 Configuration of maven war plugin in pom xm1 with Servlet 3 0 1 lt plugins gt 2 bed 3 lt plugin gt 4 lt groupId gt org apache maven plugins lt grouplId 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 c
78. lt id gt 1 lt id gt ED state i e an order that can only be reviewed or Link lt http orders 1 review gt rel review op POST Link lt http orders 1 cancel gt rel cancel op POST lt customer gt http customers 21 lt customer gt lt shippingAddress gt http customers 21 address 1 lt shippingAddress gt lt orderltems gt lt product gt http products 3345 lt product gt lt quantity gt 1 lt quantity gt 64 Experimental Features lt orderItems gt lt status gt RECEIVED lt status gt lt order gt Without a method annotated with ContextualActionSet all actions are available at all times regardless of the state of an order The following method can be provided to define a contextual contract for this resource OANA OPBPWN FE wo 10 11 12 13 14 15 16 17 18 19 20 21 ContextualActionSet public Set lt String gt getContextualActionSet Set lt String gt result switch return result case REC resu resu brea case REV lt new HashSet lt String gt order getStatus EIVED add review add cancel EWED resu resu brea case PAY resu brea case CAN case SHI brea Us add pay lt add cancel add ship W Q A a a Ae ER E UO This method returns a set of action names based on the order s internal state the val
79. n http jsr311 java net nonav releases 1 1 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 2 3 Extracting Request Parameters Parameters of a resource method may be annotated with parameter based annotations to extract information from a request A previous example presented the use PathParam http jsr311 java net 11 Overview of JAX RS 1 1 nonav releases 1 1 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 jsr3 1 1 java net nonav releases 1 1 javax ws rs Path html QueryParam http jsr3 11 java net nonav releases 1 1 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 Example 2 14 Query parameters 1 Path smooth 2 GET 3 public Response smooth 4 DefaultValue 2 QueryParam step int step 5 DefaultValue true QueryParam min m boolean hasMin 6
80. n ROME version 0 9 or higher Maven developers require a dependency on the jersey atom http download java net maven 2 com sun jersey jersey atom 1 9 ea01 jersey atom 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupid gt com sun jersey lt grouplid gt lt artifactId gt jersey atom lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt Non maven developers require e rome jar http download java net maven 1 rome jars rome 0 9 jar e jdom jar http repol maven org maven2 jdom jdom 1 0 jdom 1 0 jar and additionally if not depending on the jersey bundle jar http download java net maven 2 com sun jersey jersey bundle 1 9 ea0 1 jersey bundle 1 9 ea01 jar non maven developers require jersey atom jar http download java net maven 2 com sun jersey jersey atom 1 9 ea0 1 jersey atom 1 9 ea01 jar 11 4 3 JSON The use of the Java types org codehaus jettison json JSONObject and org codehaus jettison json JSONArray requires Jettison version 1 1 or higher Maven developers require a dependency on the jersey json http download java net maven 2 com sun jersey jersey json 1 9 ea01 jersey json 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt 74 Dependencies lt groupId gt com sun jersey lt grouplid gt lt artifactId gt jersey json lt artifactId gt lt version gt 1 9 ea01
81. n com j2se 1 5 0 docs api java net URL html which is why JAX RS has the UriBuilder http jsr311 java net nonav releases 1 1 javax ws rs core UriBuilder html class that makes it simple and easy to build URIs safely 18 Overview of JAX RS 1 1 UriBuilder http sr311 java net nonav releases 1 1 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 jsr311 java net nonav releases 1 1 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 jsr311 java net nonav releases 1 1 javax ws rs core Urilnfo html and UriBuilder http jsr3 1 1 java net nonav releases 1 1 javax ws rs core UriBuilder html from the bookmark sample Example 2 26 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 15 path userEntity getUserid 16 build 17 uriArray put userUri toASCIIString 18 19 r
82. n take some time to execute all the tests so 1t is recommended that you pick the appropriate tests to run related to the particular area that is being investigated For example using mvn Dtest lt pattern gt test where pattern may be a comma separated set of names matching tests 13 4 Continuous building and testing with Hudson Jersey is built tested and deployed on Solaris Windows and Linux using an interal Hudson server The Jersey Hudson jobs are available publically at http hudson glassfish org job Jersey trunk multiplatform http hudson glassfish org job Jersey trunk multiplatform 13 5 Using NetBeans NetBeans 6 8 or greater has excellent maven support The Jersey maven modules can be loaded built and tested in NetBeans without any additional project specific requirements 83
83. nav apidocs 1 9 ea01 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 java sun com j2se 1 5 0 docs api java net HttpURLConnection 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 3 1 POST request with form parameters Form f new Form ELadd x 5 VEO f add y bar 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 27 Client API In the above code a Form http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api representation Form html is created with two parameters a new WebResource http jersey java net nonav apidocs 1 9 ea01 jersey
84. nce into your Jersey application Download http download java net maven 2 com sun jersey samples jacksonjsonprovider 1 9 ea01 jacksonjsonprovider 1 9 ea01 project zip to get a complete example using POJO based JSON support 5 2 JAXB Based JSON support Taking this approach will save you a lot of time if you want to easily produce consume both JSON and XML data format Because even then you will still be able to use a unified Java model Another advantage 40 JSON Support 5 2 1 is simplicity of working with such a model as JAXB leverages annotated POJOs and these could be handled as simple Java beans A disadvantage of JAXB based approach could be if you need to work with a very specific JSON format Then it could be difficult to find a proper way to get such a format produced and consumed This is a reason why a lot of configuration options are provided so that you can control how things get serialized out and deserialized back Following is a very simple example of how a JAXB bean could look like Example 5 3 Simple JAXB bean implementation 1 XmlRootElement 2 public class MyJaxbBean 3 public String name 4 public int age 5 6 public MyJaxbBean JAXB needs this 7 8 public MyJaxbBean String name int age 9 this name name 10 this age age 11 2 Using the above JAXB bean for producing JSON data format from you resource method is then as simple as Example 5 4 JAXB bean us
85. net Hypermedia Actions Introduction It is generally understood that in order to follow the REST style URIs should be assigned to anything of interest resources and a few well defined operations should be used to interact with these resources For example the state of a purchase order resource can be updated by POSTing or PATCHing a new value for the its state field However there are actions that cannot be easily mapped to read or write operations on resources These operations are inherently more complex and their details are rarely of interest to clients For example given a purchase order resource the operation of setting its state to REVIEWED may involve a number of different steps such as 1 checking the customer s credit status 2 reserving product inventory 3 verifying per customer quantity limits Clearly this workflow cannot be equated to simply updating a field on a resource Moreover clients are generally uninterested in the details behind these type of workflows and in some cases computing the final state of a resource on the client side as required for a PUT operation is impractical or impossible We call these operations actions and because they are of interest to us we turn them into action resources An action resource is a sub resource defined for the purpose of exposing workflow related operations on parent resources As sub resources action resources are identified by URIs that are relative
86. ntations 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 java sun com javase 6 docs api javax xml bind annotation XmlRootElement html or XmlType http java sun com javase 6 docs api javax xml bind annotation XmlType 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 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 14 Overview of JAX RS 1 1 Example 2 20 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
87. ntified by a URI and the use of a fixed set of HTTP methods A resource in the Jersey client API is an instance of the Java class WebResource http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api client WebResource html and encapsulates a URI The fixed 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 3 3 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 sr311 java net nonav releases l 0 javax ws rs core UriBuilder html and UriTemplate http jersey java net nonav apidocs 1 9 ea01 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 1 9 ea0 1 jersey com sun jersey api json package summary html support and MIME Multipart http jersey java net no
88. occoccoconcnoconcnononcnnnoncnoroncnaronanarononns 45 XML attributes as XML elements in mapped JSON notation ooccoccncnoconcnoconcnnconcnaconcnanonos 45 Keep XML root tag equivalent in JSON mapped JSON notation 0 00 0 cece cece ee eeees 45 XML root tag equivalent kept in JSON using mapped notation coooccnnccncconiconccnnncnnncnnnonose 45 XML namespace to JSON mapping configuration for mapped notation cooccconcccnnnccnnncnnnns 46 JSON expression produced using natural notation ooccoccnnccnncnnccnnccnnconnccnnccnncnnnconaconacos 46 Keep XML root tag equivalent in JSON natural JSON notation eee 46 JSON expression produced using Jettison based mapped notation cooccoccnnccnnccnnconnconnconncos 47 XML namespace to JSON mapping configuration for Jettison based mapped notation 47 JSON expression with XML namespaces mapped into JSON 2 0 0 0 cece cece cece eeeceeeeaeene cones 47 JSON expression produced using badgerfish notation 2 0 0 cece ee ce rece eece tees ener eee 48 JAXB beat creation 52258 shee eect esheets Sie a Wea ii wade eee 48 Constructing a JSONODJeCE ceromsidrnin reco cadp cipal ica beat ow sewed saz i ceeds ld 49 Vili Preface The user guide is not complete see the JavaDoc API for all details and will be added to on a continual basis If you want to contribute to the guide please email users jersey java net mailto users jersey java net 1X Chapter 1 Getting Started T
89. odules jettison jar e glassfish modules mimepull jar Download the new Jersey version archive from http download java net maven 2 com sun jersey glassfish v3 jersey gfv3 core 1 9 ea0 1 jersey gfv3 core 1 9 ea01 project zip http download java net 79 core javax Jersey with GlassFish maven 2 com sun jersey glassfish v3 jersey gfv3 core 1 9 ea0 1 jersey gfv3 core 1 9 ea0 1 project zip and unzip it s glassfish modules content into the GlassFish installation directory to the glassfish modules subdirectory there To install also Jersey examples in addition download http download java net maven 2 com sun jersey glassfish v3 jersey gfv3 docs and samples 1 9 ea0 1 jersey gfv3 docs and samples 1 9 ea01 project zip http download java net maven 2 com sun jersey glassfish v3 jersey gfv3 docs and samples 1 9 ea01 jersey gfv3 docs and samples 1 9 ea01 project zip and unzip it s content into the GlassFish installation directory To be 100 sure the changes take effect you might also want to remove the felix cache which is located in glassfish domains domainl osgi cache directory This directory gets created upon the first start of the GlassFish instance 12 2 2 GlassFish 3 1 GlassFish 3 1 is released GlassFish 3 1 builds can be downloaded from http glassfish java net downloads 3 1 final html If you want to update the Jersey bits in GlassFish with the latest Jersey snapshot version or if you want to install Jers
90. of Jersey use the following command from the checked out jersey directory mvn clean install To skip all the tests do mvn Dmaven test skip true clean install The following maven options are recommended Xmx1048m XX PermSize 64M XX MaxPermSize 128M Building the whole Jersey project including tests could take about an hour depending on your system performance of course Even if you have a pretty fast performant machine this could be quite annoying Especially if you just want to experiment with a limited amount of code To avoid building the whole Jersey project tree you can easily utilize the maven reactor plugin To build only the modules needed for the helloworld example you can launch mvn reactor make Dmake goals clean install Dmake folders samples helloworld which takes less then 2 minutes on my machine To switch testing off when building the same set of modules you will use 82 Building and testing Jersey mvn reactor make Dmake goals Dmaven test skip clean install Dmake folders sampl 13 3 Testing Jersey contains many unit tests Most of these are not really unit tests per say and are functional tests using the JUnit test framework because it is very convientient for execution and reporting Some modules have specific tests but most tests associated with testing the jersey core jersey client and jersey server modules are located in the jersey test module This module ca
91. on ocoooccnccnnccnnncnnccnoconoconccnnccnnconnccnnccnnccnnconncinicos 34 3 9 1 With Http s URLConnection occoococcnoccccnonocononocononoconococonororononoronroronanorinanos 34 3 9 2 With Apache HTTP client ierse reisat s eriei r ess EPE EREET sense steeds eaases 34 4 XML Support e eeii Sokol i eei E deso KEES KASST 35 4 1 Low level XML SUpport criscini i E AEE Ea E RE 35 4 2 Getting started with JAXB inorse ori erroni sereo Ees ESEE eE EVKE eK ESTESE 35 43 POJOS eeraa e ea Eae ii les ai trad risa 37 4 4 Using custom JAXBConte xt ooocooococccnccnnccnnconnconnccnnconnconnconncnnnrnnrnnnronncnnccnnccnnccnnions 38 JSON SUpport risas led rien atten E E E E E A motes ss anda deserts 40 DL POJO SUpport erii s e ea AA ee ee Ma eas 40 3 2 JAXB Based JSON Supports s cis 3ssescsees esos ogsedsseuss ovate sdssvssnbss sects ERENT shoot ngs SKEEF 40 lil Jersey 1 9 ea01 User Guide 32 17 Configuration Options 205 sSscesopesen asin veeases sete E EE ROEE SSE VEE SyarmeesnsSecets 41 5 2 2 JSON Notations 33 sine Bais Ses Se edd EE tases bed Na ii 42 D236 BXAMples criada e ida oh nest Oa ete ee SUMNER dpi 48 5 3 Low Level JSON support ooocoocnoccnoconocrnncnnnronnron E nro rr rro rre ron r norton E E A 48 O ses sotessdesnes does sikess ov esTed ew Sun cede See gan ee wean seek ved Tash A st wSee ated ESS heeds 49 6 Declarative Hy perlinking ta nt der ania MUR one ea eee 50 61 Links in Representations 33 sccve
92. on application xml and a non standard header X FOO of BAR If the request has a request entity or representation then an instance of a Java type can 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_ TYPE header X FOO BAR post String class request 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 t ype 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 GI 29 Client API post String class request or alternatively the request entity and type may be declared using the entity method as follows String response r accept MediaType APPLICATION_JSON_TYP MediaType APPLICATION_XML_TYPE header X FOO BAR entity request MediaType TEXT_PLAIN_TYP post String class ia GI 3 5 3 Receiving a response If the response has a entity or representation then the Java type of the instance
93. onfiguration gt 10 lt plugin gt EI aks 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 jsr3 11 java net nonav releases 1 1 javax ws rs core Application html may be declared in the lt servlet name gt element of the JAX RS application s web xm1 This is supported in a Web container implementing Servlet 3 0 as follows Example 2 11 Deployment of a JAX RS application using web xm1 with Servlet 3 0 1 lt web app gt 2 lt servlet gt 3 lt servlet name gt org foo rest MyApplication lt servlet name gt 4 lt servlet gt 5 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 Dga 11 lt web app gt 10 Overview of JAX RS 1 1 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
94. ontainer provider has it s own set of dependences e Entity The set of entity dependencies Each entity provider has it s own set of dependences e Tools The set of dependencies required for runtime tooling e Spring The set of dependencies required for Spring e Guice The set of dependencies required for Guice All dependences in this documented are referenced by hyper links Core server Maven developers require a dependency on the jersey server http download java net maven 2 com sun jersey jersey server 1 9 ea0 1 jersey server 1 9 ea01 pom module The following dependency needs to be added to the pom 69 Dependencies lt dependency gt lt groupid gt com sun jersey lt grouplid gt lt artifactId gt jersey server lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt And the following repositories need to be added to the pom lt repository gt lt id gt maven2 repository java net lt id gt lt name gt Java net Repository for Maven lt name gt lt url gt http download java net maven 2 lt url gt lt layout gt default lt layout gt lt repository gt lt repository gt lt id gt maven repository java net lt id gt lt name gt Java net Maven 1 Repository legacy lt name gt lt url gt http download java net maven 1 lt url gt lt layout gt legacy lt layout gt lt repository gt Non maven developers require e jersey server jar http download java net m
95. ork provides the following test container factories e com sun jersey test framework spi container for testing with the Light Weight HTTP server http HTTPContainerFactory com sun J for testing in ersey test memory without framework spi using HTTP container inmemory InMemoryTestContainerFactor com sun Jersey test framework spi container grizzly GrizzlyTestContainerFactory for testing with low level Grizzly com sun Jersey test framework spi container grizzly web GrizzlyWebTestContainerrF for testing with Web based Grizzly com sun Jersey test framework spi container grizzly2 GrizzlyTestContainerFactory for testing with low level Grizzly2 com sun Jersey test framework spi container grizzly2 web GrizzlyWebTestContainerl for testing with Web based Grizzly2 com sun Jersey test framework spi container embedded glassfish EmbeddedGlassFish for testing with embedded GlassFish v3 com sun J ersey test framework spi container external ExternalTestContainerFactor for testing with application deployed externally for example to GlassFish or Tomcat The system property jersey test containerFactory is utilized to declare the default test container factory that shall be used for testing the value of which is the fully qualified class name of a test container factory class If the property is not declared then the GrizzlyWebTestContainerFactory is utilized as default test container factory 77
96. orld application is deployed on Grizzly container Use a browser and goto the following URL http localhost 9998 helloworld Messages should be output indicating initialization of Jersey framework and the browser should display Hello World 60 JRebel support Modify the Hel loWorldResource java file such that the resource method get ClichedMessage returns a different String value Run mvn compile Reload the browser window and the browser should display the modified message 9 3 Limitations JRebel currently doesn t notify it s plugin about newly created classes that have no reference to existing classes such as newly created resource or provder classes However its possible to detect a newly created resource class and use it in your application when you are doing some other changes to existing code Why After a change has beed made Jersey re initializes itself and the new class can be detected in the process For this case you you have to use class or package scanning for detecting such resource classes 61 Chapter 10 Experimental Features 10 1 10 1 1 This chapter describes experimental features of Jersey that are only available in maven SNAPSHOT releases Such features are not intended to be utilized for stable development as the APIs may change Providing such experimental features allows developers to experiment and provide feedback please send feedback to users Ojersey java net mailto users jersey java
97. orts two filters 1 A GZIP content encoding filter GZIPContentEncodingFilter http jersey java net nonav apidocs 1 9 ea01 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 32 Client API compressed with a Content Encoding of gzip is decompressed The filter declares an Accept Encoding of gzip 2 A logging filter LoggingFilter http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api client filter LoggingFilter html If this filter is added then the request and response headers as well 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 http download java net maven 2 com sun jersey jersey client 1 9 ea0 1 jersey client 1 9 ea01 sources jar of the Jersey client for more details 3 8 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 c
98. otation JSONConfiguration based on mapped notation could be build with JSONConfiguration mapped build for usage in a JAXBContext resolver Example 5 6 An example of a JAXBContext resolver implementation Then a contact bean initialized with Example 5 9 JAXB beans for JSON supported notations description initialization will be serialized as Example 5 10 JSON expression produced using mapped notation 1 Wigston 2 name Bob 3 addresses street Long Street 1 4 town Short Village The JSON representation seems fine and will be working flawlessly with Java based Jersey client API However at least one issue might appear once you start using it with a JavaScript based client The information that addresses item represents an array is being lost for every single element array If you added another address bean to the contact contact addresses add new Address Short Street 1000 Long Village you would get Waste name Bob addresses street Long Street 1 town Short Village street Short Street 1000 town Long Village Ss WN E Both representations are correct but you will not be able to consume them using a single JavaScript client because to access Short Village value you will write addresses town in one case and addresses 0 town in the other To fix this issue you need to instruct the JSON processor what items need to be treated as arrays by
99. otes String notes 10 11 POST Action pay 12 public void pay QueryParam newCardNumber String newCardNumber 13 14 Action ship 15 public Order ship Address newShippingAddress 16 17 Action cancel 18 public void cancel Name notes String notes 19 The Action annotation associates an interface method with a link relation and hence an action resource on the server Thus invoking a method on the generated proxy results in an interaction with the corresponding action resource The way in which the method invocation is mapped to an HTTP request depends on the additional annotations specified in the interface For instance the pay action in the example above indicates that it must use a POST and that the St ring parameter newCardNumber must be passed as a query parameter This is an example of a static contract in which the client has built in knowledge of the way in which an action is defined by the server In contrast the review action only provides a name for its parameter using the Name annotation This is an example of a dynamic contract in which the client is only coupled to the review link relation and the knowledge that this relation requires notes to be supplied The exact interaction with the review action must therefore be discovered dynamically and the notes parameter mapped accordingly The Jersey client runtime uses WADL fragments that describe action resources to map these method calls into HTTP request
100. ove mentioned commands you should be able to access the deployed Jersey resource at http localhost 8080 helloworld webresources helloworld 8 3 Http Service Example OSGi Http Service support currently does not come out of the box with GlassFish but is provided with a separate OSGi bundle http download java net maven glassfish org glassfish osgi http 3 1 SNAPSHOT osgi http 3 1 SNAPSHOT jar You will need to enable the feature first by installing that bundle After that you can install and activate the Jersey application bundle Both bundles could be installed and activated as follows 58 OSGi g install http download java net maven glassfish org glassfish osgi http 3 1 SN Bundle ID 247 g install http download java net maven 2 com sun jersey samples osgi http servi Bundle ID 248 g start 247 248 Now you should be able to access the Jersey resource at http localhost 8080 osgi jersey http service status Finally to close the Felix console session just press Ctr1 d 59 Chapter 9 JRebel support Jersey provides basic support for JRebel JRebel can be used to reload java classes at runtime without requiring to redeploy an application This can improve developer productivity Java source can be modified recompiled and JRebel will ensure changes will be reflected at runtime JRebel isn t opensource and is not for free BUT Zeroturnaround JRebel s author provides a free license for open source pro
101. p lt String String gt ns2json new HashMap lt String String gt 2 ns2json put http example com example 3 context new JSONJAXBContext 4 JSONConfiguration mappedJettison 5 xml2JsonNs ns2json build types Resulting JSON will look like in the example bellow Example 5 21 JSON expression with XML namespaces mapped into JSON 1 contact example id 2 2 name Bob 3 addresses street Long Street 1 4 town Short Village Please note that id item became example id based on the XML namespace mapping If you have more XML namespaces in your XML you will need to configure appropriate mapping for all of them 47 JSON Support 5 2 2 4 Badgerfish notation 5 2 3 Badgerfish notation is the other notation based on Jettison From JSON and JavaScript perspective this notation is definitely the worst readable one You will probably not want to use it unless you need to make sure your JAXB beans could be flawlessly written and read back to and from JSON without bothering with any formatting configuration namespaces etc JSONConfiguration instance using badgerfish notation could be built with JSONConfiguration badgerFish build and the output JSON for Example 5 9 JAXB beans for JSON supported notations description initialization will be as follows Example 5 22 JSON expression produced using badgerfish notation Le recontact tid q US 2 4 2 name S Bob 3 a
102. plication must declare a dependency on the jersey server 1linking module lt dependency gt lt groupId gt com sun jJersey lt groupld gt lt artifactId gt jersey server linking lt artifactId gt 51 Declarative Hyperlinking lt version gt S jersey version lt version gt lt dependency gt Second the filter needs to be installed in the application either programmatically by adding com sun jersey server linking LinkFilter to the list defined by com sun jersey spi container ContainerResponseFilters or using a web xm1 init parameter lt init param gt lt param name gt com sun jersey spi container ContainerResponseFilters lt param name gt lt param value gt com sun jersey server linking LinkFilter lt param value gt lt init param gt See the jersey server linking sample http download java net maven 2 com sun jersey samples jersey server linking sample for more details 52 Chapter 7 Jersey Test Framework This chapter will present how to write tests for your resources using Jersey Test Framework and how to run them in various containers Additionally it will explain how to create new module for not yet supported container Jersey currently provides following modules e jersey test framework grizzly e jersey test framework grizzly2 e jersey test framework http e jersey test framework inmemory e jersey test framework embedded glassfish e jersey test framework exte
103. r you are used to 56 Chapter 8 OSGi 8 1 Feature Overview OSGi support was added to the Jersey version 1 2 Since then you should be able to utilize standard OSGi means to run Jersey based web applications in OSGi runtime as described in the OSGi Service Platform Enterprise Specification The specification could be downloaded from http www osgi org Download Release4V42 The two supported ways of running an OSGi web application are e WAB Web Application Bundle e Http Service WAB is in fact just an OSGified WAR archive Http Service feature allows you to publish Java EE Servlets in the OSGi runtime Two examples were added to the Jersey distribution to depict the above mentioned features and show how to use them with Jersey e Hello world WAB _ http download java net maven 2 com sun jersey samples helloworld osgi webapp 1 9 ea01 helloworld osgi webapp 1 9 ea01 project zip Simple OSGi Http Service application http download java net maven 2 com sun jersey samples osgi http service 1 9 ea0 1 osgi http service 1 9 ea01 project zip Both examples are multi module maven projects and both consist of an application OSGi bundle module and a test module The tests are based on Pax Exam http wiki ops4j org display paxexam Pax Exam framework Both examples also include a readme file containing instructions how to manually run the application using Apache Felix http felix apache org site index html framework The re
104. r call in constructor it passes list of package names to scan it really is a list JerseyTest constructor has variable argument count Another useful method is resource which returns WebResource instance with URI set to base URI of your application You can get preconfigured Jersey Client instance similarly by calling client method 7 4 Creating own module Creating your own module is pretty straightforward you just have to implement com sun jersey test framework spi container TestContainerFactory and com sun jersey test framework spi container TestContainer TestContainer factory is there basically for returning TestContainer instance and TestContainer has self explanatory methods start stop getClient andgetBaseURI Irecommend taking look at source code and read javadoc of these two classes all you need is there You should be avare of another thing when implementing own jersey test framework module If you want it to be usable by running justmvn clean install when only your module is specified you need to add META INF services com sun jersey test framework spi container TestContainerFactory file into your jar and put there your factory class fully classified name 7 5 Running tests outside Maven Since Jersey is Maven based project executing tests without Maven can be painful You have to have everything needed present on classpath and by everything is meant following list jersey server http download java net m
105. 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 a String instance If response meta data is required then the Java type ClientResponse http jersey java net nonav apidocs 1 9 ea01 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 If the Client Response 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 1 9 ea01 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 3 5 4 Creating new WebResources from a WebResource A new WebResource http jersey java net nonav apidocs 1 9 ea01 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
106. rit the configuration declared on the client instance For example the following creates a reference to a Web resource with the URI http 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 3 5 2 Building a request Requests to a Web resource are built using the builder pattern see RequestBuilder http jersey java net nonav apidocs 1 9 ea01 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 1 9 ea01 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 js
107. rnal 7 1 What is different in Jersey 1 2 There are some significant breaking changes in Jersey 1 2 In prior Jersey versions users were able to select container factory just by specifying it in some property That was convenient from user perspective but not good from build perspective Former test framework artifact was dependent on all containers which is useless in most cases usually you test only with one container Solution to this is modularization make module for each test container It has one drawback users will have to have other dependency in their applications for example if you want to test on embedded grizzly container you will declare only dependency on jersey test framework grizzly module You can declare multiple test containers this way and select one by defining property jersey test containerFactory Another change non breaking is renaming Jersey parameters which control container factory used port and host name for external container Old properties are still working but users are encouraged to use new ones Table 7 1 Property name changes Prior Jersey 1 2 Jersey 1 2 test containerFactory jersey test containerFactory JERSEY_HTTP_PORT jersey test port JERSEY _HOST_NAME used with external jersey test host container 7 2 Using test framework When you want test your resources in maven based project you need to add dependency on one of the Jersey Test Framework modules You can tak
108. s 17 return Color f get null getRGB 18 catch Exception e 19 throw new WebApplicationException 400 20 21 22 23 12 Overview of JAX RS 1 1 In general the Java type of the method parameter may 1 Be a primitive type 2 Have a constructor that accepts a single St ring argument 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 jsr311 java net nonav releases 1 1 javax ws rs DefaultValue html is not used in conjunction with QueryParam http jsr311 java net nonav releases 1 1 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 nul 1 for other object types and the Java defined default for primitive types The PathParam http jsr3 1 1 java net nonav releases 1 1 javax ws rs PathParam html and the other parameter based annotations MatrixParam http jsr3 1 1 java net nonav releases 1 1 javax ws rs MatrixParam html HeaderParam http jsr311 java net nonav releases 1 1
109. s The following sample shows how to use OrderController to generate a proxy to review pay and ship an order For the sake of the example we assume the customer that submitted the order has been suspended and needs to be activated before the order is reviewed For that purpose the client code retrieves the customer URI from the order s model and obtains an instance of CustomerController 1 Instantiate Jersey s Client class 2 Client client new Client 3 4 Create proxy for order and retrieve model 5 OrderController orderCtrl client view 6 http orders 1 OrderController class 7 8 Create proxy for customer in order 1 9 CustomerController customerCtrl client view 10 orderCtrl getModel getCustomer 11 CustomerController class 12 13 Activate customer in order 1 14 customerCtrl activate 15 16 Review and pay order 17 orderCtrl review approve 18 orderCtrl pay 123456789 customerController isa hypermedia controller interface akin to OrderController which is omitted since it does not highlight any additional feature 66 Experimental Features 19 20 Ship order 21 Address newAddress getNewAddress 22 orderCtrl ship newAddress The client runtime will automatically update the action set throughout a conversation for example even though the review action does not produce a result the HTTP response to that action still includes a list of link
110. s which will be used Example 5 7 JAXB beans for JSON supported notations description simple address bean 1 XmlRootElement 2 public class Address 3 public String street 4 public String town 5 6 public Address 7 8 public Address String street String town 9 this street street 10 this town town 11 12 Example 5 8 JAXB beans for JSON supported notations description contact bean 1 XmlRootElement 2 public class Contact 3 4 public int id 5 public String name 6 public List lt Address gt addresses 7 8 public Contact 9 10 public Contact int id String name List lt Address gt addresses 11 this name name 12 this id id 13 this addresses 14 addresses null new LinkedList lt Address gt addresses null 15 16 Following text will be mainly working with a contact bean initialized with Example 5 9 JAXB beans for JSON supported notations description initialization final Address addresses new Address Long Street 1 Short Village Contact contact new Contact 2 Bob Arrays asList addresses 43 JSON Support Le contact bean with id 2 name Bob containing a single address street Long Street 1 town Short Village All bellow described configuration options are documented also in apidocs at http jersey java net nonav apidocs 1 9 ea01 jersey com sun jersey api json JSONConfiguration html 5 2 2 1 Mapped n
111. s can also be declared for example the following will build the URI http localhost segment name value 19 Overview of JAX RS 1 1 Example 2 27 Building URIs using query parameters 1 UriBuilder fromUri http localhost 2 path a 3 queryParam name value 4 build segment value 2 8 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 The following example shows the throwing of a Not FoundException from the bookmark sample Example 2 28 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 returns 1 8 This exception is a Jersey specific exception that extends WebApplicationException http jsr311 java net nonav releases l 1 javax ws rs WebApplicationException html and builds a HTTP response with the 404 status code and an optional message as the body of the response Example 2 29 Jersey specific exception implementation 1 public class NotFoundException extends WebApplicationException 2 3 JERK 4 Create a
112. sed Web applications with Spring 11 7 Guice Maven developers using Guice 2 0 require a dependency on the jersey guice http download java net maven 2 com sun jersey contribs jersey guice 1 9 ea0 1 jersey guice 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupid gt com sun jersey contribs lt groupIid gt lt artifactId gt jersey guice lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt See the Java documentation here http jersey java net nonav apidocs 1 9 ea0 1 contribs jersey guice com sun jersey guice spi container servlet package summary html on how to integrate Jersey based Web applications with Guice The Jersey Guice support may also be used with GuiceyFruit http code google com p guiceyfruit a set of extensions on top of Guice 2 0 such as support for Java EE artifacts like PostConstruct PreDestroy Resource and PersistenceContext To avail of GuiceyFruit features exclude the guice dependency from the maven central repo and add the following lt dependency gt lt groupId gt org guiceyfruit lt groupId gt lt artifactId gt guiceyfruit lt artifactId gt lt version gt 2 0 lt version gt lt dependency gt lt repository gt lt id gt guice maven lt id gt lt name gt guice maven lt name gt lt url gt http guiceyfruit googlecode com svn repo releases lt url gt lt repository gt 11 8 Jersey Test Frame
113. ses 1 1 javax ws rs Consumes html can be applied at both the class and method levels and more than one media type may be declared in the same Consumes http jsr3 11 java net nonav releases 1 1 javax ws rs Consumes html declaration 2 2 Deploying a RESTful Web Service JAX RS provides a deployment agnostic abstract class Application http sr311 java net nonav releases 1 1 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 2 7 Deployment agnostic application model 1 public class MyApplication extends Application 2 public 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 T 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 get Classes For example the following scans for root resource and wow provider classes in packages org foo rest org bar rest and in any sub packages of those two Example 2 8 Reusing Jersey implementation in your custom application model 1 public class MyApplication extends PackagesResourceConfig 2 pub
114. setting an optional property arrays on your JSONConfiguration object For our case you would do it with Example 5 11 Force arrays in mapped JSON notation JSONConfiguration mapped arrays addresses build You can use multiple string values in the arrays method call in case you are dealing with more than one array item in your beans Similar mechanism one or more argument values applies also for all below desribed options Another issue might be that number value 2 for id item gets written as a string 2 To avoid this you can use another optional property on JSONConfiguration called nonStrings 44 JSON Support Example 5 12 Force non string values in mapped JSON notation JSONConfiguration mapped arrays addresses nonStrings id build It might happen you use XML attributes in your JAXB beans In mapped JSON notation these attribute names are prefixed with character If id was an attribute it s definition would look like XmlAttribute public int id and then you would get RACERS ki TZN at the JSON output In case you want to get rid of the prefix you can take advantage of another configuration option of JSONConfiguration called attributeAsElement Usage is similar to previous options Example 5 13 XML attributes as XML elements in mapped JSON notation JSONConfiguration mapped attributeAsElement id build Mapped JSON notation was designed to produce the simplest po
115. sion 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 dependent 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 2 7 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 java su
116. ssible JSON expression out of JAXB beans While in XML you must always have a root tag to start a XML document with there is no such a constraint in JSON If you wanted to be strict you might have wanted to keep a XML root tag equivalent generated in your JSON If that is the case another configuration option is available for you which is called rootUnwrapping You can use it as follows Example 5 14 Keep XML root tag equivalent in JSON mapped JSON notation JSONConfiguration mapped rootUnwrapping false build and get the following JSON for our Contact bean Example 5 15 XML root tag equivalent kept in JSON using mapped notation i o contackh if ide 2 2 name Bob 3 addresses street Long Street 1 4 town Short Village rootUnwrapping option is set to t rue by default You should switch it to false if you use inheritance at your JAXB beans Then JAXB might try to encode type information into root element names and by stripping these elements off you could break unmarshalling In version 1 1 1 ea XML namespace support was added to the MAPPED JSON notation There is of course no such thing as XML namespaces in JSON but when working from JAXB XML infoset is used as an intermediary format And then when various XML namespaces are used ceratin information related to the concrete namespaces is needed even in JSON data so that the JSON procesor could correctly unmarshal JSON to XML and JAXB To make it
117. st has been built the request is filtered by filterl1 filter2 and filter3 in that order After the response has been received the response is filtered by filter3 filter2 and filterl 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 1 9 ea01 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 a new ClientResponse or modifying the state of the returned C1ientResponse 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 supp
118. st of the chapter describes how to run the above mentioned examples on GlassFish 3 1 http glassfish java net application server Since GlassFish utilizes Apache Felix an OSGi runtime comes out of the box with GlassFish However for security reasons the OSGi shell has been turned off You can explicitly enable it There is a system property called org glassfish additionalOSGiBundlesToStart in domain xm1 that contains a list of additional bundles to be started by glassfish One has to add org apache felix shell remote there Here are a few ways to do it Option 1 You can delete the property and create it again using following asadmin commands asadmin delete jvm options target server config Dorg glassfish additionalOSGiBundlesToStart org apache felix shell org apache feli asadmin create jvm options target server config Dorg glassfish additionalOSGiBundlesToStart org apache felix shell org apache feli Option 2 You can use GlassFish Admin Console to edit the jvm option Option 3 You can edit the domain xml directly Presuming you have the default GlassFish instance running after enabling shell as described above you should now be able to connect to the Felix console with 57 OSGi telnet localhost 6666 You should then see Apache Felix prompt similar to following TRYING bin Trying 127 20 0 0 Connected to localhost Escape character is Welcome to Apache Felix Gogo g 8 2
119. stInfoset 1 2 2 jar e jaxb impl jar http download java net maven 1 com sun xml bind jars jaxb impl 2 1 12 jar e jaxb api jar http download java net maven 1 javax xml bind jars jaxb api 2 1 jar e activation jar http download java net maven 1 javax activation jars activation 1 1 jar e stax api jar http download java net maven 1 javax xml stream jars stax api 1 0 2 jar 73 Dependencies and additionally if not depending on the jersey bundle jar http download java net maven 2 com sun jersey jersey bundle 1 9 ea0 1 jersey bundle 1 9 ea01 jar _non maven developers require jersey fastinfoset jar http download java net maven 2 com sun jersey jersey fastinfoset 1 9 ea01 jersey fastinfoset 1 9 ea01 jar 11 4 2 Atom The use of the Java types org apache abdera model Categories Entry Feed Service requires a dependency on Apache Abdera Maven developers require a dependency on the jersey atom abdera http download java net maven 2 com sun jersey contribs jersey atom abdera 1 9 ea0 1 jersey atom abdera 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupId gt com sun jJersey contribs lt groupId gt lt artifactId gt jersey atom abdera lt artifactId gt lt version gt 1 9 ea01 lt version gt lt dependency gt The use of the Java types com sun syndication feed atom Entry and com sun syndication feed atom Feed requires a dependency o
120. t API and some features such as filters and how to use them with security features in the JDK The Jersey client API 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 developer to concisely and efficiently implement a reusable client side solution that leverages existing and well established client side HTTP implementations The Jersey 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 Jersey 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 Jersey 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 JAX RS makes it easy to build RESTful Web services and 3 Leverage artifacts of the JAX RS API for the client side Note that JAX RS is currently a server side only API The Jersey Client API supports a pluggable architecture to enable the use of different underlying HTTP client implementations Two such implementations are supported and leveraged the Http s U
121. t do JAXBElement lt Planet gt class so Jersey client API provides way how to workaround it by declaring subclass of GenericType Example 4 6 Client side JAXBElement 1 GET 2 GenericType lt JAXBElement lt Planet gt gt planetType new GenericType lt JAXBElem 3 4 Planet planet Planet webResource path planet accept MediaType A 5 System out println planet 6 7 POST 8 Planet p new Planet 9 10 11 webResource path planet post new JAXBElement lt Planet gt new QName pla 4 4 Using custom JAXBContext In some scenarios you can take advantage of using custom JAXBContext Creating JAXBContext is expensive operation and if you already have one created same instance can be used by Jersey Other possible usecase for this is when you need to set some specific things to JAXBContext for example set different classloader Example 4 7 Planet JA XBContextProvider 1 Provider 2 public class PlanetJAXBContextProvider implements ContextResolver lt JAXBContext gt 3 private JAXBContext context null 4 5 public JAXBContext getContext Class lt gt type 6 if type Planet class 7 return null we don t support nothing else than Planet 8 9 if context null 10 try 11 context JAXBContext newInstance Planet class 12 catch JAXBException e 13 log warning error null will be returned which indicates th 14 provider won t can t be used
122. tead of an absolute path then the annotation can be changed to Ref resource WidgetsResource class style ABSOLUTE The above usage works nicely when there s already a URI template on a class that you want to reuse If there s no such template available then you can use a literal value instead of a reference E g the following is equivalent to the earlier example Ref value widgets style ABSOLUTE 6 2 Binding Template Parameters Referenced or literal templates may contain parameters Two forms of parameters are supported e URI template parameters e g widgets id where id represents a variable part of the URI e EL expressions e g widgets instance id where instance id is an EL expression Parameter values can be extracted from three implicit beans instance Represents the instance of the class that contains the annotated field entity Represents the entity class instance returned by the resource method resource Represents the resource class instance that returned the entity Where context is the application deployment context 50 Declarative Hyperlinking By default URI template parameter values are extracted from the implicit instance bean i e the following two annotations are equivalent Ref widgets id Ref widgets finstance id The source for URI template parameter values can be changed using the Binding annotation E g the following two annotations are equ
123. tegerList data 3 DefaultValue 0 100 QueryParam limits Interval limits 4 Context Request request 5 Context Urilnfo 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 19 if rb null 20 throw new WebApplicationException rb build 21 22 The constructor of the SparklinesResouce root resource class computes an entity tag from the request URI and then calls the request evaluatePreconditions http jsr311 java net nonav releases 1 1 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 jsr311 java net nonav releases 1 1 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 jsr311 java net nonav releases 1 1 javax ws rs core Request html evaluatePreconditions javax ws rs core EntityTag returns null and the normal response can be re
124. through all resources 4 2 Getting started with JAXB Good start for people which already have some experience with JAXB annotations is JAXB sample You can see various usecases there This text is mainly meant for those who don t have prior experience with 35 XML Support JAXB Don t expect that all possible annotations and their combinations will be covered in this chapter JAXB JSR 222 implementation http jaxb java net is pretty complex and comprehensive But if you just want to know how you can interchange XML messages with your REST service you are looking at right chapter Lets start with simple example Lets say we have class Planet and service which produces Planets Example 4 2 Planet class 1 XmlRootElement 2 public class Planet 3 public int id 4 public String name 5 public double radius 6 7 Example 4 3 Resource class 1 Path planet 2 public class Resource 3 4 GET 5 Produces MediaType APPLICATION_XML 6 public Planet getPlanet 7 Planet p new Planet 8 p id 1 9 p name Earth 10 p radius 1 0 TI 12 return p7 13 14 You can see there is some extra annotation declared on Planet class Concretely XmlRootelement What it does This is a JAXB annotation which maps java class to XML element We don t need specify anything else because Planet is very simple class and all fields are public In this case XML element name will be derived from c
125. turned Notice that in this example the constructor of a resource class can be used perform actions that may otherwise have to be duplicated to invoked for each resource method 2 10 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 SparklinesResource 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 Instances of singleton root resource classes can be declared by an instance of Application http jsr311 java net nonav releases l 1 javax ws rs core Application html 22 Overview of JAX RS 1 1 2 11 2 12 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 resource class is annotated with PerSession then one instance is created per web session and stored as a session attribute
126. ues returned in this set correspond to the Act ion annotations in the controller For example this contextual contract prevents shipping an order that has not been payed by only including the ship action in the PAYED state 10 1 4 Client API Although action resources can be accessed using traditional APIs for REST including Jersey s client API the use of client side proxies and method invocations to trigger these actions seems quite natural As we shall see the use of client proxies also introduces a level of indirection that enables better support for server evolution permitting the definition of contracts with various degrees of coupling Client proxies are created based on hypermedia controller interfaces Hypermedia controller interfaces are Java interfaces annotated by HypermediaController that akin to the server side API specify the name of a model class and the type of serialization to use for action resource URIs The client side model class should be based on the representation returned by the server in particular in our example the client side model for an Order uses instances of URI to link an order to a customer an address and a list of products 1 2 3 4 2 6 HypermediaController model Order class linkType LinkType LINK_HEAD public interface OrderController public Order getModel ERS 65 Experimental Features 7 8 Action review 9 public void review fktName n
127. urrently over 1000 tests Embedded servers Grizzly and a special in memory server are utilized 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 Hel loWor1dWebAppTest of the helloworld webapp http download java net maven 2 com sun jersey samples helloworld webapp 1 9 ea01 helloworld webapp 1 9 ea01 project 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 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 33 Client API g
128. utilize the https scheme 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 3 9 2 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 1 9 ea01 contribs jersey apache client com sun jersey client apache package summary html ApacheHttpClientState http jersey java net nonav apidocs 1 9 ea0 1 contribs jersey apache client com sun jersey client apache config ApacheHttpClientState html and ApacheHttpClientConfig http jersey java net nonav apidocs 1 9 ea01 contribs jersey apache client com sun jersey client apache config ApacheHttpClientConfig html for more details 34 Chapter 4 XML Support As you probably already know Jersey uses MessageBodyWriters and MessageBodyReaders to parse incoming request and create outgoing responses Every user can create its own representation but this is not recommended way how to do things XML is proven standard for interchanging information especially in web services Jerseys supports low level data types used for direct manipulation and JAXB XML entities 4 1 Low level XML support
129. ves you the best fine grained control over the outcoming JSON data format 5 1 POJO support POJO suppport represents the easiest way to convert your Java Objects to JSON and back It is based on the Jackson library http jackson codehaus org To use this approach you will need to turn the JSONConfiguration FEATURE_POJO_MAPPING feature on This could be done in web xm1 using the following servlet init parameter Example 5 1 POJO JSON support web xml configuration lt init param gt lt param value gt true lt param value gt lt init param gt Ss 0 DN E The following snippet shows how to use the POJO mapping feature on the client side Example 5 2 POJO JSON support client configuration 1 ClientConfig clientConfig new DefaultClientConfig lt param name gt com sun jersey api json POJOMappingFeature lt param name 2 clientConfig getFeatures put JSONConfiguration FEATURE_POJO_MAPPING Boole 3 Client client Client create clientConfig Jackson JSON processor could be futher controlled via providing custom Jackson ObjectMapper http jackson codehaus org 1 7 0 javadoc org codehaus jackson map ObjectMapper html instance This could be handy if you need to redefine the default Jackson behaviour and to fine tune how your JSON data structures look like Detailed description of all Jackson features is out of scope of this guide The example bellow gives you a hint on how to wire your ObjectMapper insta
130. w Path review public void review HeaderParam notes String notes order se POST Actio tStatus REVI n pay Pa EWED th pay public void pay QueryParam newCardNumber String newCardNumber order se PUT Action tStatus PAYE Ship Pa D th ship Produces application xml Consumes application xml public Order ship Address newShippingAddress order setStatus SHIP return order POST Action cancel public void cancel QueryParam notes String notes PED Path cancel order setStatus CANCELED The HypermediaController annotation above indicates that this resource class is a hypermedia controller for the Order class Each method annotated with Act ion defines a link relationship and associated action resource These methods are also annotated with Path to make a sub resource There does not appear to be a need to use Action and Path simultaneously but without the latter some resource methods may become ambiguous In the future we hope to eliminate the use of Path when Action is present The element 1inkType selects the way in which URIs corresponding to action resources are serialized in this case using link headers These link headers become part of the an order s representation For instance an order in the RECEIV canceled will be represented as follows lt order gt
131. w of JAX RS 1 1 This chapter presents an overview of the JAX RS 1 1 features The JAX RS 1 1 API may be found online here http jsr3 11 java net nonav releases 1 1 index html The JAX RS 1 1 specification draft may be found online here http jsr311 java net nonav releases 1 1 spec spec html 2 1 Root Resource Classes Root resource classes are POJOs Plain Old Java Objects that are annotated with Path http jsr311 java net nonav releases l 1 javax ws rs Path html have at least one method annotated with Path http jsr3 11 java net nonav releases 1 1 javax ws rs Path html or a resource method designator annotation such as GET http jsr311 java net nonav releases 1 1 javax ws rs GET html PUT http jsr311 java net nonav releases 1 1 javax ws rs PUT html POST http jsr311 java net nonav releases 1 1 javax ws rs POST html DELETE http jsr3 11 java net nonav releases 1 1 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 http download java net maven 2 com sun jersey samples helloworld 1 9 ea01 helloworld 1 9 ea01
132. we shall illustrate their use via an example The complete example can found in hypermedia action sample http download java net maven 2 com sun jersey experimental hypermedia action hypermedia action sample The Purchase Ordering System exemplifies a system in which customers can submit orders and where orders are guided by a workflow that includes states like REVIEWED PAYED and SHIPPED The system s model is comprised of 4 entities Order Product Customer and Address These model entities are controlled by 3 resource classes OrderResource CustomerResource and ProductResource Addresses are sub resources that are also controlled by CustomerResource An order instance refers to a single customer a single address of that customer and one or more products The XML representation or view of a sample order is shown below lt order gt lt id gt 1 lt id gt lt customer gt http customers 21 lt customer gt lt shippingAddress gt http customers 21 address 1 lt shippingAddress gt lt orderltems gt lt product gt http products 3345 lt product gt lt quantity gt 1 lt quantity gt lt orderItems gt lt status gt RECEIVED lt status gt lt order gt Note the use of URIs to refer to each component of an order This form of serialization by reference is supported in Jersey using JAXB beans and the Xm1JavaTypeAdapter annotation An XmlAdapter is capable of mapping an object reference in t
133. work NOTE that breaking changes have occurred between 1 1 1 ea and 1 1 2 ea See the end of this section for details 76 Dependencies Jersey Test Framework allows you to test your RESTful Web Services on a wide range of containers It supports light weight containers such as Grizzly Embedded GlassFish and the Light Weight HTTP Server in addition to regular web containers such as GlassFish and Tomcat Developers may plug in their own containers A developer may write tests using the Junit 4 x framework can extend from the abstract JerseyTest http jersey java net nonav apidocs 1 9 ea0 1 jersey test framework com sun jersey test framework JerseyTest html class Maven developers require a dependency on the jersey test framework grizzly http download java net maven 2 com sun jersey jersey test framework jersey test framework grizzly 1 9 ea0 1 jersey test framework grizzly 1 9 ea01 pom module The following dependency needs to be added to the pom lt dependency gt lt groupid gt com sun jersey jersey test framework lt grouplId gt lt artifactId gt jersey test framework grizzly lt artifactId gt lt version gt 1 9 ea01 lt version gt lt scope gt test lt scope gt lt dependency gt When utilizing an embedded container this framework can manage deployment and testing of your web services However the framework currently doesn t support instantiating and deploying on external containers The test framew

Jersey 1.9-ea01 User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents