Home

Jersey 2.0.1 User Guide

image

Contents

1. Store the messag OUR UN HR Le you don t need to use the Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html annotation Another kind of injection is the BeanParam http jax rs spec java net nonav 2 0 apidocs javax ws rs BeanParam html which allows to inject the parameters described above into a single bean A bean annotated with O BeanParam http jax rs spec java net nonav 2 0 apidocs javax ws rs BeanParam htm containing any fields and appropriate param annotation like PathParam http jax rs spec java net nonav 2 0 apidocs javax ws rs PathParam html will be initialized with corresponding request values in expected way as if these fields were in the resource class Then instead of injecting request values like path param into a constructor parameters or class fields the BeanParam http jax rs spec java net nonav 2 0 apidocs javax ws rs BeanParam html can be used to inject such a bean into a resource or resource method The BeanParam http jax rs spec java net nonav 2 0 apidocs javax ws rs BeanParam htm is used this way to aggregate more request parameters into a single bean 11 ui getQue ui getPath hh getRe ies public void post MultivaluedMap lt String String gt formParams JAX RS Application Resources and Sub Resources Example 3 14 Example of the bean which will be used as BeanParam http jax rs spec java net nonav 2 0 apidocs javax ws
2. Chapter 1 Getting Started 1 1 This chapter provides a quick introduction on how to get started building RESTful services using Jersey The example described here uses the lightweight Grizzly HTTP server At the end of this chapter you will see how to implement equivalent functionality as a JavaEE web application you can deploy on any servlet container supporting Servlet 2 5 and higher Creating a New Project from Maven Archetype 1 2 1 3 1 4 1 5 1 6 If you want to depend on Jersey snapshot versions the following repository needs to be added to the pom lt repository gt lt id gt snapshot repository java net lt id gt lt name gt Java net Snapshot Repository for Maven lt name gt lt url gt https maven java net content repositories snapshots lt url gt lt layout gt default lt layout gt lt repository gt Now to create a new Jersey project based on Grizzly 2 container from a maven archetype execute the following in the directory where the new project should reside mvn archetype generat DarchetypeArtifactld jersey quickstart grizzly2 Darchetyp Feel free to adjust the group id package name and artifact id of your new project in the line above or you can change it after it gets generated by updating the project pom xml Exploring the Newly Created Project TODO Customizing the JAX RS Resource TODO instructions on how to make simple edits to the newly created resource Running the P
3. we add a new OPTIONS method to each resourc 30 note that we should check whether the metho 31 resourceBuilder addMethod OPTIONS 32 handledBy new Inflector lt ContainerRequestC 33 Override 34 public String apply ContainerRequestCo 35 return On this path the resource 36 methods is deployed 3 38 produces MediaType TEXT_PLAIN 39 40 we add to the model new resource which is a 41 by the OPTIONS method 42 newResourceModelBuilder addResource resourceBu 43 44 45 final ResourceModel newResourceModel newResourc 46 and we return new model 47 return newResourceModel 48 y 49 50 Override 51 public ResourceModel processSubResource ResourceModel 52 we just return the original subResourceModel wh 53 return subResourceModel 54 55 56 52 Programmatic API for Building Resources The MyOpt ionsModelProcessor from the example is a relatively simple model processor which iterates over all registered resources and for all of them builds a new resource that is equal to the old resource except it is enhanced with a new OPTIONS method Note that you only need to register such a ModelProcessor as your custom extension provider in the same way as you would register any standard JAX RS extension provider During an application deployment Jersey will look for any registered model processor and execute them As you can seem model processors are very powerful as they can do whatever manipulation with
4. weet i usus lava Peau ieee eases 44 9 Message Body Workers bom slakast ug pa Sa ENG koe bo naa vsa aka na s a SR aaa LS Saa vege 45 lil Jersey 2 0 1 User Guide 10 Asynchronous Services and Clients iiaaaaiaasaaasasasaaasananansnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnninni 46 11 Programmatic API for Building Resources aaaaaaaaaaaaasasasaasasasasaasasasaaaasasasasaadadasaaaaa 47 Hel O ee gt KNA NGA a E Re a ra 47 11 2 Programmatic Hello World example iaaaiaaaaaaaasaaassasasasasaasasasaaaasasasaaaadaaaaaaaaa 47 11 2 1 Deployment of programmatic resources 0 eee cece eee eeeee ence eeceeeeeeeeaeeeaes 49 113 Additional examples sarana pa SN sa a titles 50 11 4 Mod l processors ssi secre koe go Sas dees shee aa 51 12 Support for Common Media Types aaiaaaaaiaaaasaaasaaasasassaenannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnni 54 A Sasi see a na a an ga nag a a 54 12 2 KM Golob aa Gan ee ee ete Soe ye Bs Gages ah Seine dhl sad r ar 54 123 MUJU part isc idad lied 54 13 Support for Server Sent Events sinn sla pe ER AR Ere Na a De 55 NS 56 15 WADESUPPOT tit Anal 37 16 Jersey Test Framework cscs sec cos aan sees acs get r A Te Ng DG ra 58 17 Building and Testing Jersey se ere kr O 59 17 1 Checking Out the SOULCE Av saa aaa Ga vee R a Dobos een ass Se e Sales Tag KG ap aaa ap an 59 17 2 Building the Sources view nthe ais sit ee aa Se a BO as 59 17 3 Tes Bins 55005 cate
5. 16 The doGetAsPlainText method defaults to the MIME type of the Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation at the class level The doGetAsHtml method s Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation overrides the class level Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html setting and specifies that the method can produce HTML rather than plain text If a resource class is capable of producing more that one MIME media type then the resource method chosen will correspond to the most acceptable media type as declared by the client More specifically the Accept header of the HTTP request declares what is most acceptable For example if the Accept header is Accept text plain then the doGetAsPlainText method will be invoked Alternatively if the Accept header is Accept text plain q 0 9 text html which declares that the client can accept media types of text plain and text html but prefers the latter then the doGetAsHtml method will be invoked More than one media type may be declared in the same Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html declaration for example Example 3 5 Using multiple output MIME types GET public String doGetAsXmlOrJson WAHAB UN EH The doGetAsXm1OrJson method will get invoked if either of the media types application
6. Builder contains just a few methods like the path method used in the example which sets the name of the path Another useful method is a addMethod String path which adds a new method to the resource builder and returns a resource method builder for the new method Resource method builder contains methods which set consumed and produced media type define name bindings timeout for asynchronous executions etc It is always necessary to define a resource method handler i e he code of the resource method that will return Hello World There are more options how a resource method can be handled In the example the implementation of Inflector is used The Jersey Inflector interface defines a simple contract for transformation of a request into a response An inflector can either return a Response http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response html or directly an entity object the way it is shown in the example Another option is to setup a Java method handler using handledBy Class lt gt handlerClass Method method and pass it the chosen java lang reflect Method instance together with the enclosing class A resource method model construction can be explicitly completed by invoking build on the resource method builder It is however not necessary to do so as the new resource method model will be built automatically once the parent resource is built Once a resource model is built it is registered into the resource
7. aiissssssssssiii 6 3 1 3 Prod cese nicsen e ERE ti E ra IG ANNA oda seats 6 3 14 CONSUMES se GA Jall ala ven TET NENG ro een laa ee ad Kot a ra 8 3 2 Parameter Annotations Param ccccccecee cece ee cence cee eens sense ee tetke ee tete ee enere 8 3 3 SUD TESOUNCES sirake noi ii ts 13 3 4 Life cycle of Root Resource Classes 11555 15255 nts o oi Vsak la bai kka aaa a De cease 17 3 5 Rulles Of INJEGUON A Geje vie ker idete NA NENG GETEN GE GE E Gg ANG GE aa 18 3 6 Use Of CONTEKL ieee Na ssk sean Seta asa KN ansar AN AN oa a a ENEK 22 3 7 Programmatic resource model aiaaiaaaaaiaaasaaaaaasaasnansannnnnnnsnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnii 23 4 Representations and Responses iise sai a pa aa PING n IA pa NAGA aa a DE EGE ga a a AN aa Ka apaa a 24 4 1 Representations and Java Types iiaaaaiaaasassasasssasananannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnini 24 4 2 Building Responses s sara Pa NG ENG AKA IN NGE a aaa 25 4 3 WebApplicationException and Mapping Exceptions to Responses 25 4 4 Conditional GETs and Returning 304 Not Modified Responses 27 SURI Sand Links cima rie a has NAN GE AE come AE ga ga kalan 29 Xt Building URIS A O 29 6 Deploying a RESTful Web Service iaaiaaiaaaasaassasasaasaasnannannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnini 31 KECIL APL ddr ar 34 7 1 Uniform Interface Constraint a iaiaaaaiaaaaasassasa
8. jaxrs resources html Besides this standard JAX RS approach Jersey offers an API for constructing resources programmatically Imagine a situation where a deployed JAX RS application consists of many resource classes These resources implement standard HTTP methods like GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html EPOST http jax rs spec java net nonav 2 0 apidocs javax ws rs POST html DELETE http jax rs spec java net nonav 2 0 apidocs javax ws rs DELETE html In some situations it would be useful to add an OPTIONS http jax rs spec java net nonav 2 0 apidocs javax ws rs OPTIONS html method which would return some kind of meta data about the deployed resource Ideally you would want to expose the functionality as an additional feature and you want to decide at the deploy time whether you want to add your custom OPTIONS method However when custom OPTIONS method are not enabled you would like to be OPTIONS requests handled in the standard way by JAX RS runtime To achieve this you would need to modify the code to add or remove custom OPTIONS methods before deployment Another way would be to use programmatic API to build resource according to your needs Another use case of programmatic resource builder API is when you build any generic RESTful interface which depends on lot of configuration parameters or for example database structure Your resource classes would need to have different methods different
9. 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 GI 37 Client API 7 4 3 7 4 4 MediaType APPLICATION_XML_TYP header X FOO BAR type MediaType TEXT_PLAIN_TYP post String class request GI H or alternatively the request entity and type may be declared using the entity method as follows String response r accept MediaType APPLICATION_JSON_TYPE MediaType APPLICATION_XML_ TYPE header X FOO BAR entity request MediaType TEXT_PLAIN_TYP post String class GI Receiving a response If the response has a entity or representation then the Java type of the instance required is declared in the terminating HTTP method In the above examples a response entity is expected and an instance of String is requested The response entity will be de serialized to a String instance If response meta data is required then the Java type ClientResponse http jersey java net nonav apidocs 2 0 1 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 getEnti
10. 1 Simple hello world root resource class 1 2 package org glassfish jersey examples helloworld 3 4 import javax ws rs GET 5 import javax ws rs Path 6 import javax ws rs Produces 7 8 Path helloworld 9 public class HelloWorldResource 10 public static final String CLICHED_MESSAGE Hello Wo 11 12 GET 13 Produces text plain 14 public String getHello 15 return CLICHED_ MESSAGE 16 17 18 Let s look at some of the JAX RS annotations used in this example JAX RS Application Resources and Sub Resources 3 1 1 Path The Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html annotation s value is a relative URI path In the example above the Java class will be hosted at the URI path helloworld This is an extremely simple use of the Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html annotation What makes JAX RS so useful is that you can embed variables in the URIs URI path templates are URIs with variables embedded within the URI syntax These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI Variables are denoted by curly braces For example look at the following Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html annotation Path users username In this type of example a user will be prompted to enter their nam
11. 1 Using File with a specific MIME type to produce a response 1 GET 2 Path images image 3 Produces image 4 public Response getImage PathParam image String image 5 File f new File image 6 y if f exists 8 throw new WebApplicationException 404 9 10 dvi String mt new MimetypesFileTypeMap getContentType f 12 return Response ok f mt build 13 14 A File type can also be used when consuming a temporary file will be created where the request entity 1s stored The Content Type if not set see next section can be automatically set from the MIME media types declared by Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html if the most acceptable media type is not a wild card one that contains a for example application or Given the following method the most acceptable MIME type is used when multiple output MIME types allowed 1 GET 24 Representations and Responses Produces application xml application json public String doGetAsXmlOrJson DoF WN If application xml is the most acceptable then the Content Type of the response will be set to application xml 4 2 Building Responses Sometimes it is necessary to return additional information in response to a HTTP request Such information may be built and returned using Response http jax rs spec java net nonav 2 0 apidocs javax w
12. 6 or greater The build is based on Maven Maven 3 or greater is recommended Also it is recommended you use the following Maven options when building the workspace can be set in MAVENT_OPTS environment variable Xmx1048m XX PermSize 64M XX MaxPermSize 128M It is recommended to build all of Jersey after you cloned the source code repository To do that execute the following commands in the directory where jersey source repository was cloned typically the directory named jersey code mvn Dmaven test skip true clean install This command will build Jersey but skip the test execution If you don t want to skip the tests execute the following instead mvn clean install Building the whole Jersey project including tests could take significant amount of time Testing Jersey contains many tests Unit tests are in the individual Jersey modules integration and end to end tests are in jersey code tests directory You can run tests related to a particular area using the following command 59 Building and Testing Jersey mvn Dtest lt pattern gt test where pattern may be a comma separated set of names matching tests 17 4 Using NetBeans NetBeans IDE http netbeans org has excellent maven support The Jersey maven modules can be loaded built and tested in NetBeans without any additional NetBeans specific project files 60 Chapter 18 Migrating from Jersey 1 x This chapter is a migration guid
13. as a standard resource and then add it as a child resource to a selected parent resource This means that child resource objects can be reused to define child resources in different parent resources you just build a single child resource and then register it in multiple parent resources Each child resource groups methods with the same sub resource path Note that a child resource cannot have any child resources as there is nothing like sub sub resource method concept in JAX RS For example if a sub resource method contains more path segments in its path e g root sub resource method where root is a path of the resource and sub resource method is the sub resource method path then parent resource will have path root and child resource will have path sub resource method so there will not be any separate nested sub resources for sub resource and method See the javadocs of the resource builder API for more information 11 4 Model processors Jersey gives you an option to register so called model processor providers These providers are able to modify or enhance the application resource model during application deployment This is an advanced feature and will not be needed in most use cases However imagine you would like to add OPTIONS resource method to each deployed resource as it is described at the top of this chapter You would want to do it for every programmatic resource that is registered as well as for all standard JAX R
14. config at the last line of the MyResourceConfig constructor in the example 11 2 1 Deployment of programmatic resources Let s now look at how a programmatic resource are deployed The easiest way to setup your application as well as register any programmatic resources in Jersey is to use a Jersey ResourceConfig utility class an extension of Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html class If you deploy your Jersey application into a Servlet container you will need to provide a Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html subclass that will be used for configuration You may use a web xml where you would define a org glassfish jersey servlet ServletContainer Servlet entry there and specify initial parameter javax ws rs Application with the class name of your JAX RS Application that you wish to deploy In the example above this application will be MyResourceConfig class This is the reason why MyResourceConfig extends the ResourceConfig which if you remember extends the javax ws rs Application The following example shows a fragment of web xm1 that can be used to deploy the ResourceConfig JAX RS application 49 Programmatic API for Building Resources Example 11 3 A programmatic resource 1 2 ae 3 lt servlet gt 4 lt servlet name gt org glassfish jersey examples hellow 5 lt servlet class gt org glassfish je
15. during the deployment in the resource model validation phase In order to pertain the consistency of the final model a model processor implementation would have to be more robust than what is shown in the example 53 Chapter 12 Support for Common Media Types 12 1 JSON TODO Describe support for JSON various notations options 12 2 XML TODO Describe support for XML 12 3 Multipart TODO Describe support for multipart Chapter 13 Support for Server Sent Events TODO Describe support for SSE Chapter 14 Security Security information is available by obtaining the SecurityContext http jax rs spec java net nonav 2 0 apidocs javax ws rs core SecurityContext html using Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html which is essentially the equivalent functionality available on the HttpServletRequest http docs oracle com javaee 5 api javax servlet http HttpServletRequest html SecurityContext http jax rs spec java net nonav 2 0 apidocs javax ws rs core SecurityContext html can be used in conjunction with sub resource locators to return different resources if the user principle is included in a certain role For example a sub resource locator could return a different resource if a user is a preferred customer Example 14 1 Accessing SecurityContext 1 Path basket 2 public ShoppingBasketResource get Context SecurityContext sc 3 if sc i
16. e 14 throw new WebApplicationException 400 15 16 else 17 ELY A 18 Field f Color class getField s 19 return Color f get null getRGB 20 catch Exception e 21 throw new WebApplicationException 400 22 23 24 25 26 In general the Java type of the method parameter may JAX RS Application Resources and Sub Resources 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 4 Have a registered implementation of javax ws rs ext ParamConverterProviderJAX RS extension SPI that returns a javax ws rs ext ParamConverter instance capable of a from string conversion for the type or 5 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 5 may be used to obtain all values If the DefaultValue http jax rs spec java net nonav 2 0 apidocs javax ws rs DefaultValue html is not used in conjunction with QueryParam http jax rs spec java net nonav 2 0 apidocs javax ws rs QueryParam html and the query parameter is not present in the request then value will be an empty collection forLi st Set or SortedSet n
17. name gt com sun jersey config property packages lt param nam lt param value gt org foo rest org bar rest lt param value gt lt init param gt lt servlet gt lt web app gt JAX RS also provides the ability to obtain a container specific artifact from an Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html instance For example Jersey supports using Grizzly http grizzly java net as follows SelectorThread st Jersey also provides Grizzly at a base URL for in process RuntimeDelegate createEndpoint new MyApplication SelectorTh http grizzly java net helper classes to deploy the ServletThread instance deployment The Jersey samples provide many examples of Servlet based and Grizzly in process based deployments 33 Chapter 7 Client API This section introduces the JAX RS Client API which is a high level Java based API for interoperating with RESTful Web services It makes it very easy to interoperate with RESTful Web services and enables a developer to concisely and efficiently implement a reusable client side solution that leverages existing and well established client side HTTP implementations The client API can be utilized to interoperate with any RESTful Web service implemented using one of many frameworks and is not restricted to services implemented using JAX RS However developers familiar with JAX RS should find the client API complementar
18. of application 8 inject request specific parameters in 9 10 GET 11 public String get 12 return query param param 13 14 15 The example above will cause validation failure during application initialization as singleton resources cannot inject request specific parameters The same example would fail if the query parameter would be 19 JAX RS Application Resources and Sub Resources injected into constructor parameter of such a singleton In other words if you wish one resource instance to server more requests in the same time it cannot be bound to a specific request parameter The exception exists for specific request objects which can injected even into constructor or class fields For these objects the runtime will inject proxies which are able to simultaneously server more request These request objects are HttpHeaders Request Urilnfo SecurityContext These proxies can be injected using the Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html annotation The following example shows injection of proxies into the singleton resource class Example 3 25 Injection of proxies into singleton 1 2 Path resource 3 Singleton 4 public static class MySingletonResource 5 Context 6 Request request this is ok the proxy of Request w 7 8 public MySingletonResource Context SecurityContext se 9 this is ok too the proxy of SecurityContext wi 10 11 1 2
19. rs BeanParam html 1 2 public class MyBeanParam 3 PathParam p 4 private String pathParam 5 6 MatrixParam m 7 Encoded 8 DefaultValue default 9 private String matrixParam 10 1 HeaderParam header 12 private String headerParam 13 14 private String queryParam 15 16 public MyBeanParam QueryParam q String queryParam 17 this queryParam queryParam 18 19 20 public String getPathParam 21 return pathParam 22 23 24 Ze Example 3 15 Injection of MyBeanParam as a method parameter POST public void post BeanParam MyBeanParam beanParam JOUVUVBR wW NH The example shows aggregation of injections PathParam http jax rs spec java net nonav 2 0 apidocs javax ws rs PathParam html QueryParam http jax rs spec java net nonav 2 0 apidocs javax ws rs QueryParam html MatrixParam http jax rs spec java net nonav 2 0 apidocs javax ws rs MatrixParam html and HeaderParam http jax rs spec java net nonav 2 0 apidocs javax ws rs HeaderParam html into one single bean The rules for injections inside the bean are the same as described above for these injections The DefaultValue http jax rs spec java net nonav 2 0 apidocs javax ws rs DefaultValue html is used to define the default value for matrix parameter matrixParam Also the Encoded http jax rs spec java net nonav 2 0 apidocs javax ws rs Encoded html annotation has the same behaviour as if it were
20. 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 https maven java net service local artifact maven redirect r releases amp g com sun jersey samples amp a jaxb amp v 2 0 1 amp c project amp e zip to see how JAXB with XML and JSON can be utilized with the client API more specifically see the unit tests 7 5 Adding support for new representations The support for 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 pr
21. 3 r Response noContent build 14 15 16 MemoryStore MS createContainer c 17 return r 18 19 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 A response returned for the OPTIONS method depends on the requested media type defined in the Accept header The OPTIONS method can return a response with a set of supported resource methods in the Allow header or return a WADL http wadl java net document See wadi section for more information Produces The Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation is used to specify the MIME media types of representations a resource can produce and send back to the client In this example the Java method will produce representations identified by the MIME media type text plain Produces http ax rs spec java net nonav 2 0 apidocs javax ws rs Produces html can be applied at both the class and method levels Here s an example JAX RS Application Resources and Sub Resources Example 3 4 Specifying output MIME type 1 2 Path myResource 3 Produces text plain 4 public class SomeResource 5 GET 6 public String doGetAsPlainText 7 8 9 10 GET LE Produces text htm1 12 public String doGetAsHtml 13 14 15
22. 4 1 Representations and Java Types Previous sections on Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html and Consumes http jax rs spec java net nonav 2 0 apidocs javax ws rs Consumes html referred to MIME media types of representations and showed resource methods that consume and produce the Java type String for a number of different media types However St ring is just one of many Java types that are required to be supported by JAX RS implementations Java types such asbyte java io InputStream java io Reader and java io File are supported In addition JAXB beans are supported Such beans are JAXBElement or classes annotated with XmlRootElement http docs oracle com javase 6 docs api javax xml bind annotation XmlRootElement html or XmlType http docs oracle 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 Example 4
23. 6 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 to the client Consumes http jax rs spec java net nonav 2 0 apidocs javax ws rs Consumes html can be applied at both the class and the method levels and more than one media type may be declared in the same Consumes http jax rs spec java net nonav 2 0 apidocs javax ws rs Consumes html declaration 3 2 Parameter Annotations Param Parameters of a resource method may be annotated with parameter based annotations to extract information from a request One of the previous examples presented the use of PathParam http jax rs spec java net nonav 2 0 apidocs javax ws rs PathParam html to extract a path parameter from the path component of the request URL that matched the path declared in Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html QueryParam http jax rs spec java net nonav 2 0 apidocs javax ws rs QueryParam html is used to extract query parameters from the Query component of the request URL The following example is an extract from the sparklines sample JAX RS Application Resources and Sub Resources Example 3 8 Query parameters 1 2 Path smooth 3 GET 4 public Re
24. AX RS concepts resources and sub resources The JAX RS 2 0 JavaDoc can be found online here http jax rs spec java net nonav 2 0 apidocs index html The JAX RS 2 0 specification draft can be found online here http jcp org en jsr summary 7id 339 3 1 Root Resource Classes Root resource classes are POJOs Plain Old Java Objects that are annotated with Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html have at least one method annotated with Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html or a resource method designator annotation such as GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html PUT http jax rs spec java net nonav 2 0 apidocs javax ws rs PUT html POST http jax rs spec java net nonav 2 0 apidocs javax ws rs POST html DELETE http jax rs spec java net nonav 2 0 apidocs javax ws rs DELETE html Resource methods are methods of a resource class annotated with a resource method designator This section shows how to use Jersey to annotate Java objects to create RESTful web services The following code example is a very simple example of a root resource class using JAX RS annotations The example code shown here is from one of the samples that ships with Jersey the zip file of which can be found in the maven repository here https maven java net content repositories releases org glassfish jersey examples helloworld 2 0 1 Example 3
25. ClientRequest mcr modifyRequest cr Call the next filter ClientResponse resp getNext handle mcr Modify the response return modifyResponse resp 40 Client API 7 6 1 The filter modifies the request if required by creating a new ClientRequest http jersey java net nonav apidocs 2 0 1 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 aClientResponse The filter modifies the response if required by creating a new ClientResponse or modifying the state of the returnedClientResponse Then the filter returns the modified response Filters are re entrant and may be called by multiple threads performing requests and processing responses Supported filters The Jersey Client API currently supports two filters 1 A GZIP content encoding filter GZIPContentEncodingFilter http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client filter GZIPContentEncodingFilter html If this filter is added then a request entity is compressed with the Content Encoding ofgzip and a response entity if compressed with a Content Encoding of gzip is decompressed The filter declares an Accept Encoding ofgzip 2 A logging filter LoggingFilter http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client filter LoggingFilter html If this fil
26. GET 13 public String get 14 return query param param 15 16 17 To summarize the injection can be done into the following constructs Table 3 2 Java construct Description Class fields Inject value directly into the field of the class The field can be private and must not be final Cannot be used in Singleton scope except proxiable types mentioned above Constructor parameters The constructor will be invoked with injected values If more constructors exists the one with the most injectable parameters will be invoked Cannot be used in Singleton scope except proxiable types mentioned above Resource methods The resource methods these annotated with GET POST can contain parameters that can be injected when the resource method is executed Can be used in any scope Sub resource locators The sub resource locators methods annotated with Path but not GET POST can contain parameters that can be injected when the resource method is executed Can be used in any scope 20 JAX RS Application Resources and Sub Resources Setter methods Instead of injecting values directly into field the value can be injected into the setter method which will initialize the field This injection can be used only with Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html annotation This means it cannot be used for example for injecting of query params but it ca
27. Jersey 2 0 1 User Guide Jersey 2 0 1 User Guide Table of Contents E E AEE polis ge dette rs a k et pee So GR dea eaters Vili Ve Preface sana anaa A A eS eee Vill 1 Getting Started iea asal aa ub a ke D a R sav dea a a r 1 1 1 Creating a New Project from Maven Archetype ooccooccnccnnccnnconnconnconnconnconncnnncnnncnnnonase 1 1 2 Exploring the Newly Created Project 2 725 sai Sasasa aa D oi aaa o a RO SG Roa Tail a asal 1 1 3 Customizing the JAX RS Resource aiaiaaaaaiaasasasasasasananannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnni 1 1 4 Running the Project sisi dede ka va voted Sas os corrio codes bv pada vets Coteus Mees dk 1 1 5 Creating a JavaEE Web Application a iiaaaaaisasaassasasaaaasaaataasaaaaasanaaanannnnnnnnnnnninnnni 1 1 6 Exploring Other Jersey Examples 5 sas 2 sv Ia Na Na a ga bt laa ION t aa Haa apan O a i a a alta 1 2 Jersey Modules and Dependencies aaaaaaaaiaaassiasassaasaanaasnnaaannnnnannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnni 2 2 1 Sample SCenariOs cooler ara 2 2 1 1 Basic Server Side Application aiiaaaaiasaassasasaaanasaaaanaanaanannnannnnnnnnnnnnnninnini 2 3 JAX RS Application Resources and Sub Resources aaaaiaasaassasaasssasaasansanannasnnnnnnnnnnnnsnninnnai 4 3 1 Root Resource Classes sa sce GE eds deka ge Siro se cabeza s a a a 4 O A dei te a yess Kad aa E yee odds Pend Got TAN E a 5 3 1 2 EGET PUT POST DELETE HTTP Methods
28. MyInject dc singleton binding Injections addBinding Injections newBinder MyInjectableSingleton class to MyInjecta dc singleton instance binding Injections addBinding Injections newBinder new MyInjectableSingleton to MyInjecta dc request scope binding with specified custom annotation Injections addBinding Injections newBinder MyInjectablePerRequest class to MyInject qualifiedBy new MyAnnotationImpl in RequestScoped class dc commits changes dc commit Override public Set lt Class lt gt gt getClasses return 62 Migrating from Jersey 1 x 18 1 2 ResourceConfig Reload In Jersey 1 the reload functionality is based on two interfaces 1 com sun jersey spi container ContainerListener 2 com sun jersey spi container ContainerNotifier Containers which support the reload functionality implement the ContainerListener interface so that once you get access to the actual container instance you could call it s onReload method and get the container re load the config The second interface helps you to obtain the actual container instance reference An example on how things are wired together follows Example 18 1 Jersey 1 reloader implementation 1 public class Reloader implements ContainerNotifier 2 List lt ContainerListener gt 1s 3 4 public Reloader 5 ls new ArrayList lt ContainerListener gt 6 7 8 pub
29. Path html may be used on classes and such classes are referred to as root resource classes Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html may also be used on methods of root resource classes This enables common functionality for a number of resources to be grouped together and potentially reused The first way Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html may be used is on resource methods and such methods are referred to as sub resource methods The following example shows the method signatures for a root resource class from the jmaki backend sample 13 JAX RS Application Resources and Sub Resources Example 3 17 Sub resource methods 1 2 Singleton 3 Path printers 4 public class PrintersResource 5 6 GET 7 Produces application json application xml 8 public WebResourceList getMyResources 9 10 GET Path list LE Produces application json application xm1 12 public WebResourceList getListOfPrinters 13 14 GET Path jMakiTable 15 Produces application json 16 public PrinterTableModel getTable 17 18 GET Path jMakiTree 19 Produces application json 20 public TreeModel getTree 21 22 GET Path ids printerid 23 Produces application json application xml 24 public Printer getPrinter PathParam printerid Stri 25 26 PUT Path ids printe
30. Precondition 19 if rb null 20 throw new WebApplicationException rb build 21 22 23 The constructor of the Spark linesResouce root resource class computes an entity tag from the request URI and then calls the request evaluatePreconditions http jax rs spec java net nonav 2 0 apidocs javax ws rs core Request html evaluatePreconditions javax ws rs core EntityTag with that entity tag If a client request contains an If None Match header with a value that contains the same entity tag that was calculated then the evaluatePreconditions http jax rs spec java net nonav 2 0 apidocs javax ws rs core Request html evaluatePreconditions javax ws rs core EntityTag returns a pre filled out response with the 304 status code and entity tag set that may be built and returned Otherwise evaluatePreconditions http jax rs spec java net nonav 2 0 apidocs javax ws rs core Request html evaluatePreconditions javax ws rs core EntityTag returns null and the normal response can be returned Notice that in this example the constructor of a resource class can be used perform actions that may otherwise have to be duplicated to invoked for each resource method 28 Chapter 5 URIs and Links 5 1 Building URIs A very important aspects of REST is hyperlinks URIs in representations that clients can use to transition the Web service to new application states this is otherwise known as hypermedia as the engine of application state HTML
31. S resources To do that you first need to register a model processor provider in your application which implements org glassfish jersey server model ModelProcessor extension contract An example of a model processor implementation is shown here 51 Programmatic API for ds Building Resources 2 import javax ws rs GET Example 11 6 A programmatic resourvex ws rs Path 4 import javax ws rs Produces 5 import javax ws rs container ContainerReguestContext 6 import javax ws rs core Application import javax ws rs core Configuration 8 import javax ws rs core MediaType 9 import javax ws rs core Response 10 import javax ws rs ext Provider 11 12 import org glassfish jersey process Inflector 13 import org glassfish jersey server model ModelProcessor 14 import org glassfish jersey server model Resource 15 import org glassfish jersey server model ResourceMethod 16 import org glassfish jersey server model ResourceModel 17 18 Provider 19 public static class MyOptionsModelProcessor implements Mod 20 21 Override 22 public ResourceModel processResourceModel ResourceMod 23 we get the resource model and we want to enhanc 24 ResourceModel Builder newResourceModelBuilder ne 25 for final Resource resourc resourceModel getR 26 for each resource in the resource model w 27 final Resource Builder resourceBuilder Resou 28 29
32. aasananannnnnnnnannnnnnnnnnnnnnnnnnnnnnnnnnnnnnni n 34 7 2 Ease of use and reusing JAX RS artifacts aane ce eee c ence ence e anna nenen ene 35 7 3 Getting started with the Jersey client aaiaiaaaaaaaasasssasasasanananannnnnnnnnnnnnnnnnnnnnnnnnii 36 TA Overview of the APD isomeri ss cass ori B a Tas 36 7 4 1 Configuring a Client and WebResource iaaaaiaaassssssaassasasasasaasanasaandaiaaaaa 36 14 2 Building request sas naa nga Rest kose iga SU V obese SR Gai EP RK kosa Pioi ps PTAS GE sess 37 7 4 3 Receiving A TESPONSE a ska eo sa lag lika ind 38 7 4 4 Creating new WebResources from a WebResource aee ene ee nean 38 7 4 5 Java instances and types for representations aaiaiaaiasssssssssssasaasaassanaasaaaaa 39 7 5 Adding support for new representations aa aiaaassssasasssasasassnasaaassaaanasaaananananananin 39 7 6 Using filters ss sansar lig PESEN ieee isa atadas gecesi 40 7 6 1 Supported filters sasaka a EGA yas bei s VJ aa S S R aa etch bas pate tt ROG 41 TT Testing SERVICES a saya nek alla a a Ba a ca A Ba Ka TE ee i Aa ERA koe AGA 41 7 8 Security with Http S URLConne tion 20 0 0 AKA NTEN NGANAN AAN NAN sean 05630 42 7 8 1 With Http s URLConmne ction iiiaaaaaaaaaassasasasaasasasaaaaaasasasaaaadaaaaaakakasaaa 42 7 8 2 With Apache HTTP clientes cosita ns ks avi t la ka ia abe a flet 43 8 Filters and Interceptors sasana EN A GETEN E blk k s t
33. ackage org glassfish jersey examples helloworld H H Be Be feo H H 3333333 pu port javax ws rs container ContainerRequestContext port javax ws rs core Application port javax ws rs core Response port org glassfish jersey process Inflector port org glassfish jersey server ResourceConfig port org glassfish jersey server model Resource port org glassfish jersey server model ResourceMethod blic static class MyResourceConfig extends ResourceConfi public MyResourceConfig final Resource Builder resourceBuilder Resourc resourceBuilder path helloworld final ResourceMethod Builder methodBuilder resou final ResourceMethod Builder methodBuilder resou methodBuilder produces MediaType TEXT_PLAIN_TYPE handledBy new Inflector lt ContainerRequestC Override public String apply ContainerRequestContext co return Hello World final Resource resource resourceBuilder build registerResources resource 48 Programmatic API for Building Resources First focus on the content of the MyResourceConfig constructor in the example The Jersey programmatic resource model is constructed from Resources that contain ResourceMethods In the example a single resource would be constructed from a Resource containing one GET resource method that returns Hello World The main entry point for building programmatic resources in Jersey is the Resource Builderclass Resource
34. anannnnnnnnnnnninnnni 25 4 4 Throwing Jersey specific exceptions to control response a iaaaaisasasssssassssnaaaaaassaanaaiaaaaa 26 4 5 Jersey specific exception implementation a aaaaaiaasssssassesassasaasaaaaasanananannnnnnannnnninnnniin 26 4 6 Mapping generic exceptions tO responses aaiainaassisasasssasasananananannnnnnnnnnnnnnnnnnnnnsnnnnnini 27 4 7 Conditional GET support aon sec a a aga a E Ba gg pos paved eri a aa a Sar 28 AL URI DulldinS peseta lee ka GE Seite la vav lala Vay VH O Aber ae eta ds 29 5 2 Building URIs using query parameters si sissies rieds res esi RSE e ESEE SPEDE PETES pE ESTDA fanans 30 6 1 Deployment agnostic application model iaaaavana ssssasasssasanaaananantnnnnnnnnnnnnnnnnnnnnnsnnnnnini 31 6 2 Reusing Jersey implementation in your custom application model a aaiavasassssssssssssasaaa 31 6 3 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 31 6 4 Configuration of maven war plugin in pom xm1 with Servlet 3 0 soenan anae eee 32 6 5 Deployment of a JAX RS application using web xml with Servlet 3 0 0 eee 32 6 6 Deployment of your application using Jersey specific servlet aiaiaaviaassssasssssasaaaaasnsaaaia 33 6 7 Using Jersey specific servlet without an application model instance 33 7 1 POST request with form parameters oooocoocconccnnronnconononon
35. and may only be utilized on resource and sub resource methods This is because it extracts information from a request entity 3 6 Use of Context Previous sections have introduced the use of Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html Chapter 5 of the JAX RS specification presents all the standard JAX RS Java types that may be used with Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html When deploying a JAX RS application using servlet then ServletConfig http docs oracle com javaee 5 api javax servlet ServletConfig html ServletContext http docs oracle com 22 JAX RS Application Resources and Sub Resources javaee 5 api javax servlet ServletContext html HttpServletRequest http docs oracle com javaee 5 api javax servlet http HttpServletRequest html and HttpServletResponse http docs oracle com javaee 5 api javax servlet http HttpServletResponse html are available using Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html 3 7 Programmatic resource model Resources can be constructed from classes or instances but also can be constructed from a programmatic resource model Every resource created from from resource classes can also be constructed using the programmatic resource builder api See resource builder section for more information 23 Chapter 4 Representations and Responses
36. bean setter methods The following presents an example of all such injection cases 18 JAX RS Application Resources and Sub Resources Example 3 23 Injection 1 2 Path id d 3 public class InjectedResource 4 Injection onto field 5 DefaultValue q QueryParam p 6 private String p 7 8 Injection onto constructor parameter 9 public InjectedResource PathParam id int id 10 11 Injection onto resource method parameter 12 GET 13 public String get Context Urilnfo ui 14 15 Injection onto sub resource resource method paramet 16 Path sub id 14 GET 18 public String get PathParam sub id String id 19 20 Injection onto sub resource locator method paramete 21 Path sub id 22 public SubResource getSubResource PathParam sub id 23 24 Injection using bean setter method 25 fHeaderParam X header 26 public void setHeader String header 27 28 There are some restrictions when injecting on to resource classes with a life cycle of singleton scope In such cases the class fields or constructor parameters cannot be injected with request specific parameters So for example the following is not allowed Example 3 24 Wrong injection into a singleton scope 1 2 Path resource 3 Singleton 4 public static class MySingletonResource 5 6 QueryParam query 7 String param WRONG initialization
37. content 7 public ItemContentResource getItemContentResourc 8 return new ItemContentResource 9 10 11 GET 12 Produces application xml 13 public Item get ere ous Es BE 16 17 public class ItemContentResource 18 19 GET 20 public Response get 21 22 PUT 23 Path version 24 public void put PathParam version int version 20 Context HttpHeaders headers 26 byte in 27 wW NN C gt A 00 The root resource class ItemResource contains the sub resource locator method getItemContentResource 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 A method can be annotated with the Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html annotation with empty path Path or Path which means that the sub resource locator is matched for the path of the enclosing resource without sub resource path Example 3 19 Sub resource locators with empty path 1 2 Path item 3 public class ItemResource 4 9 Path 6 public ItemContentResource getItemContentResourc 7 return new ItemContentResource 8 9 10 15 JAX RS Appl
38. d When an application throws an EntityNotFoundException http docs oracle com javaee 5 api javax persistence EntityNotFoundException html the toResponse method of the Ent it yNotFoundMapper instance will be invoked 4 4 Conditional GETs and Returning 304 Not Modified Responses Conditional GETs are a great way to reduce bandwidth and potentially server side performance depending on how the information used to determine conditions is calculated A well designed web site may return 304 Not Modified responses for the many of the static images it serves JAX RS provides support for conditional GETs using the contextual interface Request http jax rs spec java net nonav 2 0 apidocs javax ws rs core Request html The following example shows conditional GET support from the sparklines sample 27 Representations and Responses Example 4 7 Conditional GET support 1 public SparklinesResource 2 QueryParam d IntegerList data 3 DefaultValue 0 100 QueryParam limits Interval limi 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 evaluate
39. declaration This is a correct declaration utilizing the Servlet 3 0 extension mechanism Also note that lt servlet mapping gt is used to define the base resource URI When running in a Servlet 2 x then instead it is necessary to declare the Jersey specific servlet and pass the Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html implementation class name as one of the servlet s init param entries 32 Deploying a RESTful Web Service Example 6 6 Deployment of your application using Jersey specific servlet lt web app gt 1 2 3 4 3 6 7 8 9 10 11 12 lt servlet gt lt servlet name gt Jersey Web Application lt servlet name gt lt servlet class gt com sun jersey spi container servlet ServletCon lt init param gt lt param name gt Javax ws rs Application lt param name gt lt param value gt org foo rest MyApplication lt param value gt lt init param gt lt servlet gt lt web app gt Alternatively a simpler approach is to let Jersey choose the PackagesResourceConfig implementation automatically by declaring the packages as follows Example 6 7 Using Jersey specific servlet without an application model instance lt web app gt 1 2 3 4 5 6 7 8 9 10 11 12 lt servlet gt lt servlet name gt Jersey Web Application lt servlet name gt lt servlet class gt com sun jersey spi container servlet ServletCon lt init param gt lt param
40. e 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 jax rs spec java net nonav 2 0 apidocs javax ws rs PathParam html may be used on method parameter of a request method for example Example 3 2 Specifying URI path parameter 1 2 Path users username 3 public class UserResource 4 5 GET 6 Produces text xml 7 public String getUser PathParam username String us 8 eee 9 10 al 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 jax rs spec java net nonav 2 0 apidocs javax ws rs Path html value may or may not begin with a it makes no difference Likewise by default a Path http jax rs spec java net nonav 2 0 apidocs javax w
41. e for people switching from Jersey 1 x Since many of the Jersey 1 x features became part of JAX RS 2 0 standard which caused changes in the package names we decided it is a good time to do a more significant incompatible refactoring which will allow us to introduce some more interesting new features in the future As the result there are many incompatiblities between Jersey 1 x and Jersey 2 0 This chapter summarizes how to migrate the concepts found in Jersey 1 x to Jersey JAX RS 2 0 concepts 18 1 Server API Jersey 1 x contains number of proprietary server APIs This section covers migration of application code relying on those APIs 18 1 1 Injecting custom objects Jersey 1 x have its own internal dependency injection framework which handles injecting various parameters into field or methods It also provides a way how to register custom injection provider in Singleton or PerRequest scopes Jersey 2 x uses HK2 as dependency injection framework and users are also able to register custom classes or instances to be injected in various scopes Main difference in Jersey 2 x is that you don t need to create special classes or providers for this task everything should be achievable using HK2 API Custom injectables can be registered at ResourceConfig level by adding new HK2 Module or by dynamically adding binding almost anywhere using injected HK2 Services instance Jersey 1 x Singleton ResourceConfig resourceConfig new DefaultResourceCo
42. e time in the request processing always the same instance will be used This can 17 JAX RS Application Resources and Sub Resources Scope Annotation Annotation full class Description name happen when a resource is a sub resource is returned more times during the matching In this situation only on instance will server the requests Per lookup scope PerLookup org glassfish jersey proceshuthessabReqne stSouped instance is created every time it is needed for the processing even it handles the same request Singleton Singleton javax inject Singleton In this scope there is only one instance per jax rs application Singleton resource can be either annotated with Singleton and its class can be registered using the instance of Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html You can also create singletons by registering singleton instances into Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html 3 5 Rules of Injection Previous sections have presented examples of annotated types mostly annotated method parameters but also annotated fields of a class for the injection of values onto those types This section presents the rules of injection of values on annotated types Injection can be performed on fields constructor parameters resource sub resource sub resource locator method parameters and
43. entBunbtdpr html Fonthwsastalenticitends http jax rs spec java net nonav 2 0 SNAPSHOT apidocs javax ws rs client Client html fons jeatieapWtbTaWebResource http jexsey java net nonav apedgas a net hatasty 2 0 FAA pS HOT apid cs fandx jessey npi client WebRasgetrbemtm Mams paaien bbene methods by calling WebTarget request async http jexsey java net nonav apedgas a net tatasty 2 0 FAA pS HOT 65 Migrating from Jersey 1 x Jake RS gilhss Class apid cs fandx jessey api client Ms biEWatrtR solrce html The following sub sections show code examples 18 2 1 Making a simple client request Jersey 1 x way Client client Client create WebResource webResource client resource restURL path myres String result webResource pathParam param value get St JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL path myresource pa String result target pathParam param value get String 18 2 2 Registering filters Jersey 1 x way Client client Client create WebResource webResource client resource restURL webResource addFilter new HTTPBasicAuthFilter username passwo JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL target configuration
44. erUri ub 155 path userEntity getUserid 16 build 17 uriArray put userUri toASCIIString 18 19 return uriArray 20 21 22 Urilnfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo htm is obtained using the Context annotation and in this particular example injection onto the field of the root resource class is performed previous examples showed the use of Context on resource method parameters Urilnfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html can be used to obtain URIs and associated UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core 29 URIs and Links 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 jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html getA bsolutePathBuilder Q 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 detai
45. following configures the client to perform automatic redirection for appropriate responses c getProperties put ClientConfig PROPERTY_FOLLOW_REDIRECTS true which is equivalent to the following c setFollowRedirects true Alternatively it is possible to create a Client instance using a ClientConfig http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client config ClientConfig html object for example ClientConfig cc new DefaultClientConfig cc getProperties put ClientConfig PROPERTY_FOLLOW_REDIRECTS true 36 Client API 7 4 2 Client c Client create cc Once a client instance is created and configured it is then possible to obtain a WebResource http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client WebResource html instance which will inherit the configuration declared on the client instance For example the following creates a reference to a Web resource with the URI http 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 WebReso
46. forms present a good example of this in practice Building URIs and building them safely is not easy with java net URI http docs oracle com javase 1 5 0 docs api java net URL html which is why JAX RS has the UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html class that makes it simple and easy to build URIs safely UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html can be used to build new URIs or build from existing URIs For resource classes it is more than likely that URIs will be built from the base URI the web service is deployed at or from the request URI The class Urilnfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriInfo html provides such information in addition to further information see next section The following example shows URI building with Urilnfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html and UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html from the bookmark sample Example 5 1 URI building 1 Path users 2 public class UsersResource 3 4 Context Urilnfo urilnfo 5 6 7 8 GET 9 Produces application json 10 public JSONArray getUsersAsJsonArray 11 JSONArray uriArray new JSONArray 12 for UserEntity userEntity getUsers 13 UriBuilder ub urilnfo getAbsolutePathBuilder 14 URI us
47. ialize the response to the JAXB bean In addition further code would have to be written to make it easy to reuse the same resource http localhost 8080 form that is encapsulated in the WebResource type 7 3 Getting started with the Jersey client Refer to the dependencies chapter http jersey java net nonav documentation 2 0 1 chapter_deps html chapter_deps and specifically the Core client http jersey java net nonav documentation 2 0 1 chapter_deps html core_client section for details on the dependencies when using the Jersey client with Maven and Ant Refer to the Java API documentation http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client package summary html for details on the Jersey client API packages and classes Refer to the Java API Apache HTTP client documentation http jersey java net nonav apidocs 2 0 1 contribs jersey apache client index html for details on how to use the Jersey client API with the Apache HTTP client 7 4 Overview of the API 7 4 1 To utilize the client API it is first necessary to create an instance of a Client http jersey java net nonav apidocs 2 0 1 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
48. ication Resources and Sub Resources In the example above the sub resource locator method get ItemContentResource is matched for example for request path item locator or even for only item 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 So for example the following sub resource locator is valid Example 3 20 Sub resource locators returning sub type 1 2 Path item 3 public class ItemResource 4 5 Path 6 public Object getItemContentResource 7 return new AnyResource 8 9 10 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 If it is required that the runtime manages the sub resources as standard resources the Class should be returned as shown in the following example Example 3 21 Sub resource locators created from classes 1 2 import javax inject Singleton 3 4 Path item 5 public class ItemResource 6 Path content 7 public Class lt ItemContentSingletonResource gt getItemCont 8 return ItemCon
49. ing information that is POSTed by HTML forms for example the following extracts the form parameter named name from the POSTed form data Example 3 10 Processing POSTed HTML form POST Consumes application x www form urlencoded Store the messag WAHAB NR If it is necessary to obtain a general map of parameter name to values then for query and path parameters it is possible to do the following 10 public void post FormParam name String name JAX RS Application Resources and Sub Resources Example 3 11 Obtaining general map of URI path and or query parameters GET public String get Context Urilnfo ui MultivaluedMap lt String String gt queryParams MultivaluedMap lt String String gt pathParams JO UI BON EH For header and cookie parameters the following Example 3 12 Obtaining general map of header parameters GET public String get Context HttpHeaders hh MultivaluedMap lt String String gt headerParams Map lt String Cookie gt pathParams hh getCook WAHAB NR In general Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html can be used to obtain contextual Java types related to the request or response Because form parameters unlike others are part of the message entity it is possible to do the following Example 3 13 Obtaining general map of form parameters POST Consumes application x www form urlencoded
50. is more natural to use exceptions for HTTP errors 25 Representations and Responses The following example shows the throwing of a Not FoundException from the bookmark sample Example 4 4 Throwing Jersey specific exceptions to control response 1 2 3 4 5 6 7 8 9 Path items itemid public Item getItem PathParam itemid String itemid Item i getItems get itemid if i null throw new NotFoundException Item itemid is not return i This exception is a Jersey specific exception that extends WebApplicationException http jax rs spec java net nonav 2 0 apidocs 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 4 5 Jersey specific exception implementation 1 2 3 4 2 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 public class NotFoundException extends WebApplicationException AK Create a HTTP 404 Not Found exception A public NotFoundException super Responses notFound build AK Create a HTTP 404 Not Found exception param message the String that is the entity of the 404 ay public NotFoundException String message super Response status Responses NOT_FOUND entity message type text plain build In other cases it may not be appropriate to throw instances of WebApplicatio
51. kie 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 orHttpsURLConnection it is possible to configure system wide security settings which is obviously not sufficient for multiple client configurations For HTTP authentication the java net Authenticator can be extended and statically registered Refer to the Http authentication http docs oracle com javase 6 docs technotes guides net http auth html document for more details For cookie management the java net CookieHandler can be extended and statically registered Refer to the Cookie Management http docs oracle com javase 6 docs technotes guides net http cookie html document for more details To utilize HTTP with SSL it is necessary to utilize the https scheme For certificate based authentication see the class HTTPSProperties http jersey java net nonav apidocs latest jersey com sun jersey client 42 Client API 7 8 2 urlconnection HTTPSProperties html for how to set javax net ssl HostnameVerifier and javax net ssl SSLContext With Apache HTTP client The support for HTTP authentication and cookies is much better with the Apache HTTP client than withHttpURLConnection See the Java documentation for the package com sun jersey client apache h
52. lasses in packages org foo rest org bar rest and in any sub packages of those two Example 6 2 Reusing Jersey implementation in your custom application model 1 public class MyApplication extends PackagesResourceConfig 2 public MyApplication 3 super org foo rest org bar rest 4 9 6 There are multiple deployment options for the class that implements Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html interface in the Servlet 3 0 container For simple deployments no web xml is needed at all Instead an ApplicationPath http jax rs spec java net nonav 2 0 apidocs javax ws rs A pplicationPath html annotation can be used to annotate the user defined application class and specify the the base resource URI of all application resources Example 6 3 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 1 ApplicationPath resources 2 public class MyApplication extends PackagesResourceConfig 3 public MyApplication 4 super org foo rest org bar rest 5 6 a 7 8 31 Deploying a RESTful Web Service 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 6 4 Configuration of maven war plugin in pom xml with Servlet 3 0 1 lt plugins gt 2 pee 3 l
53. lic void addListener ContainerListener 1 9 1s add 1 10 11 12 public void reload 13 for ContainerListener 1 1s 14 l onReload 15 16 17 18 Example 18 2 Jersey 1 reloader registration 1 Reloader reloader new Reloader 2 resourceConfig getProperties put ResourceConfig PROP 3 In Jersey 2 two interfaces are involved again but these have been re designed 1 org glassfish jersey server spi Container 2 org glassfish jersey server spi ContainerLifecycleListener The Container interface introduces two reload methods which you can call to get the application re loaded One of these methods allows to pass in a new ResourceConfig instance You can register your implementation of ContainerLifecycleListener the same way as any other provider i e either by annotating it by Provider annotation or adding it to the ResourceConfig directly either using the class using 63 Migrating from Jersey 1 x ResourceConfig addClasses or registering a particular instance using ResourceConfig addSingletons method An example on how things work in Jersey 2 follows Example 18 3 Jersey 2 reloader implementation 1 2 3 4 9 6 7 8 9 10 11 T2 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 public class Reloader implements ContainerLifecycleListener Container container public void reload ResourceConfig newConfig container reload newConfig public void
54. ls UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html can be used to build replace query or matrix parameters URI templates can also be declared for example the following will build the URI http localhost segment name value Example 5 2 Building URIs using query parameters 1 UriBuilder fromUri http localhost 2 path a 3 queryParam name value 4 build segment value 5 30 Chapter 6 Deploying a RESTful Web Service JAX RS provides a deployment agnostic abstract class Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html for declaring root resource and provider classes and root resource and provider singleton instances A Web service may extend this class to declare root resource and provider classes For example Example 6 1 Deployment agnostic application model 1 public class MyApplication extends Application 2 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 s 6 7 8 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 byget Classes For example the following scans for root resource and provider c
55. mp c project amp e zip sample The setUp method called before a test is executed creates an instance of the Glassfish server deploys the application and a WebResource instance that references the base resource Override protected void setUp throws Exception super setUp Start Glassfish glassfish new GlassFish BASE_URI getPort 41 Client API 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 EN r c resource BASE_URI The tearDown method called after a test is executed stops the Glassfish server Override protected void tearDown throws Exception super tearDown glassfish stop The testHelloWorld method tests that the 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 baseWebResource 7 8 Security with Http s URLConnection 7 8 1 With Http s URLConnection The support for security specifically HTTP authentication and or coo
56. n be used for injections of request The setters will be called after the object creation and only once The name of the method does not necessary have a setter pattern Cannot be used in Singleton scope except proxiable types mentioned above The following example shows all possible java constructs into which the values can be injected 21 JAX RS Application Resources and Sub Resources Example 3 26 Example of possible injections 1 2 Path resource 3 public static class SummaryOfInjectionsResource 4 QueryParam query 5 String param injection into a class field 6 7 8 GET 9 public String get QueryParam query String methodQu 10 injection into a resource method parameter 11 return query param param 12 13 14 Path sub resource locator 15 public Class lt SubResource gt subResourceLocator QueryPar 16 injection into a sub resource locator parameter 17 return SubResource class 18 19 20 public SummaryOfInjectionsResource QueryParam query 21 injection into a constructor parameter 22 23 24 25 Context 26 public void setRequest Request request 27 injection into a setter method 28 System out println request null 29 30 31 32 public static class SubResource 33 GET 34 public String get 35 return sub resource 36 37 38 The FormParam http jax rs spec java net nonav 2 0 apidocs javax ws rs FormParam html annotation is special
57. nException http jax rs spec java net nonav 2 0 apidocs javax ws rs WebApplicationException html or classes that extend WebApplicationException http jax rs spec java net nonav 2 0 apidocs javax ws rs WebApplicationException html and instead it may be preferable to map an existing exception to a response For such cases it is possible to use the ExceptionMapper lt E extends Throwable gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ExceptionMapper html interface For example the following maps the EntityNotFoundException http docs oracle com javaee S api javax persistence EntityNotFoundException html to a HTTP 404 Not Found response 26 Representations and Responses Example 4 6 Mapping generic exceptions to responses 1 Provider 2 public class EntityNotFoundMapper implements 3 Except ionMapper lt javax persistence EntityNotFoundException gt 4 public Response toResponse javax persistence EntityNotFoun 5 return Response status 404 6 entity ex getMessage 7 type text plain 8 build 9 10 11 The above class is annotated with Provider http jax rs spec java net nonav 2 0 apidocs javax ws rs ext Provider html this declares that the class is of interest to the JAX RS runtime Such a class may be added to the set of classes of the Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html instance that is configure
58. nananasnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnaninni 5 3 3 PUT method sauna need sta a eee ad R Sess de uses a ten KASEP KA EEEO IAE EEE EPERE RETTES 6 3 4 Specifying output MIME type aaiaaaaaaaasasaasaasaasasaaasasaaananatnanannnannnnnnnnnnnnnnnnnnnnnnnnnannnni 7 3 5 Using multiple output MIME types 20 0 0 eee sats sta FV Dat TAG aaa a Ha STTS eens Ra 7 3 6 Server side content negotiation aaaiaasasssasasssanaasnsnaannnnannnnnannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnninnn 8 3 7 Specifying input MIME type sasa cs sees usfs asks ml sl at ak Sa GN EEEE EPT aaa laa akal gaa 8 3 8 Query parameters cintia 9 3 9 Custom Java type for consuming request parameters aiaaaaaiaasssasssseaasaasaasasaaasaaaaananaaaa 9 3 10 Processing POSTed HTML form aaiiaaaaaiaassassasasaaananaaananaannannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnii 10 3 11 Obtaining general map of URI path and or query parameters a iaaaaisasasssssasssssasaaaaaa 11 3 12 Obtaining general map of header parameters aiaaiaaasasaassssassssnasaaasasaaaaasaaaasnanansnaana 11 3 13 Obtaining general map of form parameters a aaiaaiaasssssssssassaasaasaaananaaaasnannnnnnnnnnnnnnni 11 3 14 Example of the bean which will be used as BeanParam 2 aaiaaiaaaaassasssssssasaasaaaaasaaa 12 3 15 Injection of MyBeanParam as a method parameter a aaiaaaaiaassssssssssasaasaasasanasanaasaaaa 12 3 16 Injection of more beans into one resource me
59. nfig resourceConfig getSingletons add new SingletonTypelnjectableProvider lt Context SingletonType gt SingletonType class new SingletonType Jersey 1 x PerRequest ResourceConfig resourceConfig new DefaultResourceConfig resourceConfig getSingletons add new PerRequestTypelnjectableProvider lt Context PerRequestType gt Override public Injectable lt PerRequestType gt getInjectable ComponentConte 4755 Jersey 2 0 HK2 Module public static class MyBinder extends AbstractBinder Override protected void configure request scope binding 61 Migrating from Jersey 1 x Jersey 2 0 dynamic binding public static class bind MyInjectablePerRequest class to MyInjectablePerRequest c singleton binding bind MyInjectableSingleton class in Singleton class singleton instance binding bind new MyInjectableSingleton to MyInjectableSingleton cla register module to ResourceConfig can be done also in cons ResourceConfig rc new ResourceConfig rc addClasses rc addBinders new MyBinder MyApplication extends Application Inject public MyApplication ServiceLocator serviceLocator System out println Registering injectables DynamicConfiguration dc Injections getConfiguration serviceL request scope binding Injections addBinding Injections newBinder MyInjectablePerRequest class to
60. oncnno nono rro ERE nn seen BIN AE KN NG KNA 35 11 1 A standard resource Classi esiis eee a kog os Olivia bils H ta Halal Gaja o alan S aL loa O aa aG a kt uma sa k alga 48 11 2 A programmatic 1es Urce so dona n Na GG NE as S Silakan BT aA O Ga NEG Ha S E e Epa bones 48 11 3 A programmatic TEes0Urce stimi saa Ge a E n bk Fala alv L a S VAS Ga b k G a aL A GUN GEN EE anlar 50 11 14 A programmatic o AAA otet DI ua TU soos a a i 50 11 5 A programmatic Tes0Urce i d ass bec Bas alaska AEE avatar bec Ol EEE leno tarn n Haa Taal 51 11 6 A progr mmatio TESOUTCEe so sboskasaussas DEN NGE salta U b a s pes DHENE aa R saa a bene 52 14 1 Accessing Security Context vis l va kela GO VE a A A aa 56 18 1 Jersey 1 reloader implementation isisisi smal KENANG EEN NGANG soba Sr t GK la ala Bs SU SNA l han Halka kra H U 63 vi Jersey 2 0 1 User Guide 18 2 Jersey 1 reloader registration 18 3 Jersey 2 reloader implementation 2 2 0 0 0 ska Maal t cece eee A a a a gag a s 18 4 Jersey 2 reloader registration Vil 1 Preface This is user guide for Jersey 2 0 1 We are trying to keep it up to date as we add new features When reading the user guide please consult also our Jersey API documentation http jersey java net nonav apidocs 2 0 1 org glassfish jersey index html as an additional source of information about Jersey features and API If you would like to contribute to the guide or have questi
61. ons on things not covered in our docs please contact us atusers jersey java net mailto users jersey java net Similarly in case you spot any errors in the Jersey documentation please report them by filing a new issue in our Jersey JIRA Issue Tracker http java net jira browse JERSEY under docs component Please make sure to specify the version of the Jersey User Guide where the error has been spotted by selecting the proper value for the Affected Version field Text formatting conventions First mention of any Jersey and JAX RS API component in a section links to the API documentation of the referenced component Any sub sequent mentions of the component in the same chapter are rendered using a monospace font Emphasised font is used to a call attention to a newly introduce concept when it first occurs in the text In some of the code listings certain lines are too long to be displayed on one line for the available page width In such case the lines that exceed the available page width are broken up into multiple lines using a at the end of each line to indicate that a break has been introduced to fit the line in the page For example This is an overly long line that might not fit the available page width and had to be broken into multiple lines This line fits the page width Should read as This is an overly long line that might not fit the available page width and had to This line fits the page width Vili
62. ovider https maven java net service local artifact maven redirect r releases amp g com sun jersey samples amp a entity provider amp v 2 0 1 amp c project amp e zip sample for such implementations utilized on the server side Classes or implementations of the provider based interfaces need to be registered 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 39 Client API The following registers an instance or singleton of MyReader ClientConfig cc new DefaultClientConfig MyReader reader cc getSingletons add reader Client c Client create cc 7 6 Using filters Filtering requests and responses can provide useful functionality that is hidden from the application layer of building and sending requests and processing responses Filters can read modify the request URI headers and entity or read modify the response status headers and entity The Client and WebResource classes extend from Filterable http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client filter Filterable html and that enables the addition of ClientFilter http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client filter ClientFilter html instances A WebRe source will inherit filters f
63. ponse as a JAXB object with such an API For example with the Jersey API this is very easy Example 7 1 POST request with form parameters 1 Form f new Form 2 Fuada E Tfoo 3 f add y bar 4 9 Client c Client create 6 WebResource r c resource http localhost 8080 form 7 8 JAXBBean bean r 9 type MediaType APPLICATION_FORM_URLENCODED_TYPE 10 accept MediaType APPLICATION_JSON_TYPE 11 post JAXBBean class f 12 In the above code a Form http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api representation Form html is created with two parameters a new WebResource http jersey java net 35 Client API nonav apidocs 2 0 1 jersey com sun jersey api client WebResource html instance is created from a Client http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client Client html then the Form instance isPOS Ted 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 ser
64. r application Ant developers are likely to find the Ant Tasks for Maven http maven apache org ant tasks index html very useful The following table provides an overview of all Jersey modules and their dependencies with links to the respective binaries Table 2 1 Jersey modules and dependencies Module Dependencies Description Core jersey server jersey commons http Base server functionality http maven java net service local maven java ngtlrtifact maven redirect service local r releases amp g org glassfish jersey amp a jersey artifact commons amp v 2 0 1 amp e pom maven redirect r releases amp g org glassfish jersey amp a jersey server amp v 2 0 1 amp e pom jersey client jersey commons Basic client functionality jersey Common functionality shared by client and server commons Containers 2 1 Sample Scenarios 2 1 1 Basic Server Side Application For a server side Jersey application you typically need to depend on jersey server module to provide the basic functionality then you may want to support JSON mapping and a standard JavaEE servlet container Jersey Modules and Dependencies you would deploy your application to So this would be the common set of dependencies for your project for this kind of scenario e jersey server e jersey commons Chapter 3 JAX RS Application Resources and Sub Resources This chapter presents an overview of the core J
65. raints are required 1 every resource is identified by a URI 2 aclient interacts with the resource via HTTP requests and responses using a fixed set of HTTP methods 3 one or more representations can be retured and are identified by media types and 4 the contents of which can link to further resources The above process repeated over and again should be familiar to anyone who has used a browser to fill in HTML forms and follow links That same process is applicable to non browser based clients Many existing Java based client APIs such as the Apache HTTP client API or java net HttpURLConnection supplied with the JDK place too much focus on the Client Server constraint for the exchanges of request and responses rather than a resource identified by a URI and the use of a fixed set of HTTP methods 34 Client API A resource in the Jersey client API is an instance of the Java class WebResource http jersey java net nonav apidocs 2 0 1 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 7 2 Ease of use and reusing JAX RS artifacts Since a resource is represented as a Java type it makes it ea
66. register new HttpBasicAuthFilter userna 18 2 3 Setting Accept header Jersey 1 x way Client client Client create WebResource webResource client resource restURL accept tex ClientResponse response webResource get ClientResponse class 66 Migrating from Jersey 1 x JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL Response response target request text plain get Response 18 2 4 Attaching entity to request Jersey 1 x way Client client Client create WebResource webResource client resource restURL ClientResponse response webResource post ClientResponse clas JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL Response response target request post Entity text payload 18 2 5 Setting SSLContext and or HostnameVerifier Jersey 1 x way HTTPSProperties prop new HTTPSProperties hostnameVerifier sslContext DefaultClientConfig dcc new DefaultClientConfig dcc getProperties put HTTPSProperties PROPERTY_HTTPS_PROPERT Client client Client create dcc E Jersey 2 0 way Client client ClientFactory newClient client configuration setProperty ClientProperties SSL_CONTEX client configuration setProperty ClientProperties HOSTNAME_V 67
67. reload container reload Override public void onStartup Container container this container container Override public void onReload Container container ignore or do whatever you want after reload has bee Override public void onShutdown Container container ignore or do something after the container has been Example 18 4 Jersey 2 reloader registration 1 Reloader reloader new Reloader 2 3 resourceConfig addSingletons reloader 18 1 3 MessageBodyReaders and MessageBodyWriters ordering JAX RS 2 0 defines new order of MessageBodyWorkers whole set is sorted by declaration distance media type and source custom providers have smaller priority than Jersey provided JAX RS 1 x ordering can still be forced by setting parameter MessageProperties LEGACY_WORKERS_ORDERING jersey config workers legacyOrdering to true in ResourceConfig or ClientConfig properties 18 2 Client API JAX RS 2 0 provides functionality that is equivalent to the Jersey 1 x proprietary client API Here is a rough mapping between the Jersey 1 x and JAX RS 2 0 Client API classes 64 Migrating from Jersey 1 x Table 18 1 Mapping of Jersey 1 x to JAX RS 2 0 client classes Ntkey RS lhss Class Fomthunjsiotkanfpinlme lldsatnd constructors http jexsey java net nonav apedgas a net imastv 2 0 fesAPS HOT apid cs fandx jessey api client Cli
68. rid 27 Consumes application json application xm1 28 public void putPrinter PathParam printerid String 29 30 DELETE Path ids printerid 31 public void deletePrinter PathParam printerid Stri 32 33 If the path of the request URL is printers then the resource methods not annotated with Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html will be selected If the request path of the request URL is printers list then first the root resource class will be matched and then the sub resource methods that match list will be selected which in this case is the sub resource methodget ListOfPrinters So in this example hierarchical matching on the path of the request URL is performed The second way Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html may be used is on methods not annotated with resource method designators such as GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html or POST http jax rs spec java net nonav 2 0 apidocs 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 14 JAX RS Application Resources and Sub Resources Example 3 18 Sub resource locators 1 2 Path item 3 public class ItemResource 4 Context Urilnfo urilnfo 6 Path
69. roject TODO instructions on how to run the project Creating a JavaEE Web Application TODO Exploring Other Jersey Examples Jersey codebase contains a number of useful samples on how to use various JAX RS and Jersey features Please refer to the TODO Examples section of this guide for more information on those Chapter 2 Jersey Modules and Dependencies Jersey is built assembled and installed using Maven Jersey is deployed to the Java Net maven repository at the following location http maven java net https maven java net index html The Jersey modules can be browsed at the following location https maven java net content repositories releases org glassfish jersey Jars Jar sources Jar JavaDoc and samples are all available on the java net maven repository An application depending on Jersey requires that it in turn includes the set of jars that Jersey depends on Jersey has a pluggable component architecture so the set of jars required to be include in the class path can be different for each application All Jersey components are built using Java SE 6 compiler It means you will also need at least Java SE 6 to be able to compile and run your application Developers using maven are likely to find it easier to include and manage dependencies of their applications than developers using ant or other build technologies This document will explain to both maven and non maven developers how to depend on Jersey for thei
70. rom its creator which canbe a Client or anotherwebResource Additional filters can be added to a WebResource after it has been created For requests filters are applied in reverse order starting with the WebResource filters and then moving to the inherited filters For responses filters are applied in order starting with inherited filters and followed by the filters added to theWebResource All filters are applied in the order in which they were added For instance in the following example the Client has two filters added filter1 andfilter2 in that order and the WebResource has one filter added filter3 ClientFilter filterl lt ClientFilter filter2 m Client c Client create c addFilter filterl c addFilter filter2 ClientFilter filter3 WebResource r c resource r addFilter filter3 After a request has been built the request is filtered byfilter3 filter2 and filterl in that order After the response has been received the response is filtered byfilterl filter2 and filter3 in that order before the response is returned Filters are implemented using the russian doll stack based pattern where a filter is responsible for calling the next filter in the ordered list of filters or the next filter in the chain of filters The basic template for a filter is as follows class AppClientFilter extends ClientFilter public ClientResponse handle ClientRequest cr Modify the request
71. rsey servlet Servl 6 lt init param gt 7 lt param name gt Javax ws rs Application lt param nam 8 lt param value gt org glassfish jersey examples hel 9 lt init param gt 10 lt load on startup gt 1 lt load on startup gt 11 lt servlet gt 12 lt servlet mapping gt 13 lt servlet name gt org glassfish jersey examples hellow 14 lt url pattern gt lt url pattern gt 15 lt servlet mapping gt 16 de If you use another deployment options and you have accessible instance of ResourceConfig which you use for configuration you can register programmatic resources directly by registerResources method called on the ResourceConfig Please note that the method registerResources replaces all the previously registered resources Because Jersey programmatic API is not a standard JAX RS feature the ResourceConfig must be used to register programmatic resources as shown above See deployment chapter for more information 11 3 Additional examples Example 11 4 A programmatic resource final Resource Builder resourceBuilder Resource builder resourceBuilder addMethod OPTIONS handledBy new Inflector lt ContainerRequestContext Resp Override public Response apply ContainerRequestContext cont return Response ok This is a response to an O final Resource resource resourceBuilder build H KO ATA Ii GT A he In the example above the Resource is built from a HelloWorldResource resource class The re
72. s a Mua dies eek Sac gee R Gde ra O aa Na A BG a a NA Seetuue dns 59 17 4 Using NetBeans ass nas ha ed a KR a 60 13 Migrating from Jersey IK aas pak kasta i sakar ge Haa a sh Seana ene E Re k 61 18 15 Servet APLI Ra a 61 18 1 1 Injecting custom Objects ss nas ENE NET E AA AE A BERAN r E he sass 61 18 1 2 ResourceConfig Reload aitia a U A gag NE NG bias Dat plak Ag SEN 63 18 1 3 MessageBodyReaders and MessageBodyWriters ordering 64 18222 Client APL oso asa ar a Gece ais 64 18 2 1 Making a simple client request aaiaiaaaaaaassasasssassasnaasaaaasnaananananananaaai 66 18 22 Registerino ter fist kaga Ng A Ga etnia aaa eee GEJE ete 66 18 2 3 Setting ACCept header vissa aa a 66 18 2 4 Attaching entity to request asos aan kka a R R Nn Aa a a NENENG 67 18 2 5 Setting SSLContext and or HostnameVerifier 2 aaaiaaaasaaasasssasssasssasaaasaaaa 67 1V List of Tables 2 1 Jersey modules and dependencies s12 mss bo aaa ga NG Na e pie Ss G S Ta aa A ROV ae aaa ries 2 BAE ake t a a r Ae r raki 17 LL a loca ng r r a edhe sented r as 20 18 1 Mapping of Jersey 1 x to JAX RS 2 0 client classes eaaa eee nenen nenen eee eee 65 List of Examples 3 1 Simple hello world root resource Class 2 0 00 cece cece pal Bal Ss eee SG Va pa BVT ala a Ba S Ba SS Ta aa Saga laa a 4 3 2 Specifying URI path parameter aaiaiaaaaaiaasassaasasaaataaanana
73. s 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 JAX RS Application Resources and Sub Resources 3 1 2 GET PUT POST DELETE HTTP Methods 3 1 3 GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html _ PUT http jax rs spec java net nonav 2 0 apidocs javax ws rs PUT html POST http jax rs spec java net nonav 2 0 apidocs javax ws rs POST html DELETE http jax rs spec java net nonav 2 0 apidocs javax ws rs DELETE html and HEAD http jax rs spec java net nonav 2 0 apidocs javax ws rs HEAD html are resource method designator annotations defined by JAX RS and which correspond to the similarly named HTTP methods In the example above the annotated Java method will process HTTP GET requests The behavior of a resource is determined by which of the HTTP methods the resource is responding to The following example is an extract from the storage service sample that shows the use of the PUT method to create or update a storage container uri toStrin Example 3 3 PUT method 1 2 APUT 3 public Response putContainer 4 System out println PUT CONTAINER container 5 6 URI uri uriInfo getAbsolutePath 7 Container c new Container container 8 9 Response r 10 if MemoryStore MS hasContainer c 11 r Response created uri build 12 else 1
74. s rs core Response html and Response ResponseBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response ResponseBuilder html For example a common RESTful pattern for the creation of a new resource is to support a POST request that returns a 201 Created status code and a Location header whose value is the URI to the newly created resource This may be achieved as follows Example 4 2 Returning 201 status code and adding Location header in response to POST request 1 2 Consumes application xml 3 public Response post String content 4 URI createdUri 5 create content 6 return Response created createdUri build 7 8 In the above no representation produced is returned this can be achieved by building an entity as part of the response as follows Example 4 3 Adding an entity body to a custom response 1 POST 2 Consumes application xml 3 public Response post String content 4 URI createdUri 5 String createdContent create content 6 return Response created createdUri entity createdContent 7 8 Response building provides other functionality such as setting the entity tag and last modified date of the representation 4 3 WebApplicationException and Mapping Exceptions to Responses Previous sections have shown how to return HTTP responses and it is possible to return HTTP errors using the same mechanism However sometimes when programming in Java it
75. sUserInRole PreferredCustomer 4 return new PreferredCustomerShoppingBaskestResource 5 else 6 return new ShoppingBasketResource 7 8 56 Chapter 15 WADL Support TODO Describe WADL support Chapter 16 Jersey Test Framework TODO Describe Test Framework Chapter 17 Building and Testing Jersey 17 1 17 2 17 3 Checking Out the Source Jersey source code is available in a Git repository you can browse at http java net projects jersey sources code show In case you are not familiar with Git we recommend reading on of the many Getting Started with Git articles you can find on the web For example this DZone RefCard http refcardz dzone com refcardz getting started git Before you can clone Jersey repository you have to sign up for a java net http java net account Once you are registered you have to add an SSH key to your java net profile see this article on how to do that http java net projects help pages ProfileSettings SSH_Keys_Tab To clone the Jersey repository you can execute the following command on the command line provided you have a command line Git client installed on your machine git clone ssh lt your_java_net_id gt java net jersey cod Milestones and releases of Jersey are tagged You can list the tags by executing the standard Git command in the repository directory git tag 1 Building the Source Jersey source code requires Java SE
76. source model built this way contains a GET method producing text plain responses with Hello World entity This is quite important as it allows you to whatever Resource objects based on introspecting existing JAX RS resources and use builder API to enhance such these standard resources In the example we used already implemented HelloWorldResource resource class and enhanced it by OPTIONS method The OPTIONS method is handled by an Inflector which returns Response http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response html The following sample shows how to define sub resource methods methods that contains sub path 50 Programmatic API for Building Resources Example 11 5 A programmatic resource final Resource Builder resourceBuilder Resource builder final Resource Builder childResource resourceBuilder add childResource addMethod GET handledBy new GetInflector final Resource resource resourceBuilder build OANA OBWN EF Sub resource methods are defined using so called child resource models Child resource models or child resources are programmatic resources build in the same way as any other programmatic resource but they are registered as a child resource of a parent resource The child resource in the example is build directly from the parent builder using method addChildResource String path However there is also an option to build a child resource model separately
77. sponse smooth 5 DefaultValue 2 QueryParam step int step 6 DefaultValue true QueryParam min m boolean hasMin F DefaultValue true QueryParam max m boolean hasMax 8 DefaultValue true QueryParam last m boolean hasLas 9 DefaultValue blue QueryParam min color ColorParam 10 DefaultValue green QueryParam max color ColorParam 11 DefaultValue red QueryParam last color ColorParam 12 13 14 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 Default Value http jax rs spec java net nonav 2 0 apidocs javax ws rs DefaultV alue html annotation will be assigned to the step method parameter If the step value cannot be parsed as a 32 bit signed integer then a HTTP 404 Not Found response is returned User defined Java types such as ColorParam may be used which as implemented as follows Example 3 9 Custom Java type for consuming request parameters 1 2 public class ColorParam extends Color 3 4 public ColorParam String s 5 super getRGB s 6 7 8 private static int getRGB String s 9 if s charAt 0 10 try 11 Color c Color decode 0x s substring 1 12 return c getRGB 13 catch NumberFormatException
78. structure for every new application deploy You could use more solutions including approaches where your resource classes would be built using Java byte code manipulation However this is exactly the case when you can solve the problem cleanly with the programmatic resource builder API Let s have a closer look at how the API can be utilized Programmatic Hello World example Jersey Programmatic API was designed to fully support JAX RS resource model In other words every resource that can be designed using standard JAX RS approach via annotated resource classes can be also modelled using Jersey programmatic API Let s try to build simple hello world resource using standard approach first and then using the Jersey programmatic resource builder API The following example shows standard JAX RS Hello world resource class 47 Programmatic API for Building Resources Example 11 1 A standard resource class H OS ATA UO BWN FE RoR Path helloworld public class HelloWorldResource GET Produ public ces text plain String getHello return Hello World This is just a simple resource class with one GET method returning Hello World string that will be serialized as text plain media type Now we will design this simple resource using programmatic API Example 11 2 A programmatic resource 0 SI OV OF WN FE WWWWWNHNNNNNNNNNRPRPRPRPRPEP gt pp BWNHEFPOODAIDAUVBWNHEOWOCDAINIADAUBWBNHEO WO p
79. sy to configure pass around and inject in ways that is not so intuitive or possible with other client side APIs The Jersey Client API reuses many aspects of the JAX RS and the Jersey implementation such as 1 URI building using UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html and UriTemplate http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api uri UriTemplate html to safely build URIs 2 Support for Java types of representations such as byte String InputStream File DataSource and JAXB beans in addition to Jersey specific features such as JSON http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api json package summary html support and MIME Multipart http jersey java net nonav apidocs 2 0 1 contribs jersey multipart index html support 3 Using the builder pattern to make it easier to construct requests Some APIs like the Apache HTTP client or java net HttpURLConnection http docs oracle com javase 1 5 0 docs api java net 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 res
80. t plugin gt 4 lt groupld gt org apache maven plugins lt groupld gt 9 lt artifactId gt maven war plugin lt artifactId gt 6 lt version gt 2 1 1 lt version gt E lt configuration gt 8 lt failOnMissingWebXml gt false lt failOnMissingWebXml gt 9 lt configuration gt 10 lt plugin gt 11 R 12 lt plugins gt Another deployment option is to declare JAX RS application details in theweb xml This is usually suitable in case of more complex deployments e g when security model needs to be properly defined or when additional initialization parameters have to be passed to Jersey runtime JAX RS 1 1 specifies that a fully qualified name of the class that implements Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html may be declared in the lt servlet name gt element of the JAX RS application s web xml This is supported in a Web container implementing Servlet 3 0 as follows Example 6 5 Deployment of a JAX RS application using web xm1 with Servlet 3 0 lt web app gt lt servlet gt lt servlet name gt org foo rest MyApplication lt servlet name gt lt servlet gt lt servlet name gt org foo rest MyApplication lt servlet name gt lt url pattern gt resources lt url pattern gt lt servlet mapping gt 1 2 3 4 5 Sisk 6 lt servlet mapping gt 7 8 9 0 1 1 Pees 1 lt web app gt Note that the lt servlet class gt element is omitted from the servlet
81. tentSingletonResource More complex programmatic resource can be returned as long they are valid resources 3 4 Life cycle of Root Resource Classes By default the life cycle of root resource classes is per request which namely that a new instance of a root resource class is created every time the request URI path matches the root resource This makes for a very natural programming model where constructors and fields can be utilized as in the previous section showing the constructor of the SoarklinesResource class without concern for multiple concurrent requests to the same resource In general this is unlikely to be a cause of performance issues Class construction and garbage collection of JVMs has vastly improved over the years and many objects will be created and discarded to serve and process the HTTP request and return the HTTP response Instances of singleton root resource classes can be declared by an instance of Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html Jersey supports two further life cycles using Jersey specific annotations Table 3 1 Scope Annotation Annotation full class Description name Request scope RequestScoped or org glassfish jersey procesMafteriial Requesifiaoptd none applied when no annotation is present In this scope the resource instance is created for each new request and used for processing of this request If the resource is used more than on
82. tentSingletonResource class 9 10 11 12 Singleton 13 public class ItemContentSingletonResource 14 this class is managed in the singleton life cyc 15 16 17 JAX RS resources are managed in per request scope by default which means that new resource is created for each request In this example the javax inject Singleton annotation says that the resource will be managed as singleton and not in request scope The sub resource locator method returns a class which means that the runtime will managed the resource instance and its life cycle If the method would return instance instead the Singleton annotation would have no effect and the returned instance would be used The sub resource locator can also return a programmatic resource model See resource builder section for information of how the programmatic resource model is constructed The following example shows very simple resource returned from the sub resource locator method 16 JAX RS Application Resources and Sub Resources Example 3 22 Sub resource locators returning resource model 1 2 import org glassfish jersey server model Resource 3 4 Path item 5 public class ItemResource 6 7 Path content 8 public Resource getItemContentResource 9 return Resource from ItemContentSingletonResource 10 11 12 The code above has exactly the same effect as previous example Resource is a resource simple resource constructed from ItemCon
83. ter 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 https maven java net service local artifact maven redirect r releases amp g com sun jersey amp a jersey client amp v 2 0 1 amp e jar of the Jersey client for more details 7 7 Testing services The Jersey client API was originally developed to aid the testing of the Jersey server side primarily to make it easier to write functional tests in conjunction with the JUnit framework for execution and reporting It is used extensively and there are currently over 1000 tests Embedded servers Grizzly and a special in memory server are 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 HelloWorldWebAppTest of the helloworld webapp https maven java net service local artifact maven redirect r releases amp g com sun jersey samples amp a helloworld webapp amp v 2 0 1 a
84. the resource model they like A model processor can even for example completely ignore the old resource model and return a new custom resource model with a single Hello world resource which would result in only the Hello world resource being deployed in your application Of course it would not not make much sense to implement such model processor but the scenario demonstrates how powerful the model processor concept is A better real life use case scenario would for example be to always add some custom new resource to each application that might return additional metadata about the deployed application Or you might want to filter out particular resources or resource methods which is another situation where a model processor could be used successfully Also mote that processSubResource ResourceModel subResourceModel Configuration configuration method is executed for each sub resource returned from the sub resource locator The example is simplified and does not do any manipulation but probably in such a case you would want to enhance all sub resources with anew OPTIONS method handlers too It is important to remember that any model processor must always return valid resource model As you might have already noticed in the example above this important rule is not followed If any of the resources in the original resource model would already have an OPTIONS method handler defined adding another handler would cause the application fail
85. thods aaiasaaassssssssssasasasanasansnaadannninanann 13 3 17 Sub resource methods sia aaa GK a NANG A NGA r S metas ee aaa a 14 3 18 Sub resource locators sis sisa atene a NGA Hs OSV L S V a lS Kala G labis essen Ka la tt a a Lali 15 3 19 Sub resource locators with empty path aiaaaaaiaasssisasssasaasaassanaasananananannnnnnnnnnnnnnnnnnni 15 3 20 Sub resource locators returning SUD tYPe 20 0 0 ee cece eaaa ence ence ence ences seeeeaeeea nenen nenen 16 3 21 Sub resource locators created from Classes 2aiaiaaasaisaiaasssaasaaanasaanaannnnnannnnnnnnnnnnnnnnnnnnii 16 3 22 Sub resource locators returning resource Model aiaaaaiaaasasaasaaasasananananannnnnnnnnnnnnnnii 17 3 23 DECOM ss om A goo prek Ka ANG need Sods Whe a a R ine Poea ses tad Kao S sls 19 3 24 Wrong injection into a singleton SCOPE 2 00 ee eect ee ence cece cece ce cence ne nne nenen nenen anane 19 3 25 Injection of proxies into singleton 2 115 020 aa KAN NAN IG kat ban ds TG NK a ba kala S a a a Da Va 20 3 26 Example of possible injections aaaaaaaiaassasaasssaasaataasaaaaasnnnnannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnni 22 4 1 Using File with a specific MIME type to produce a response asiaiiaassssssasssssasaasaasaaaa 24 4 2 Returning 201 status code and adding Location header in response to POST request 25 4 3 Adding an entity body to a custom response iaiaiaaaaassasasssssasaasaassanaasanan
86. ttp jersey java net nonav apidocs 2 0 1 contribs jersey apache client com sun jersey client apache package summary html ApacheHttpClientState http jersey java net nonav apidocs 2 0 1 contribs jersey apache client com sun jersey client apache config ApacheHttpClientState html and ApacheHttpClientConfig http jersey java net nonav apidocs 2 0 1 contribs jersey apache client com sun jersey client apache config ApacheHttpClientConfig html for more details 43 Chapter 8 Filters and Interceptors TODO Describe filters and interceptors name and dynamic bindings etc 44 Chapter 9 Message Body Workers TODO Describe message body readers and writers how to write custom ones 45 Chapter 10 Asynchronous Services and Clients TODO Describe asynchronous services ChunkedResponse and async client 46 Chapter 11 Programmatic API for Building Resources 11 1 11 2 Introduction A standard approach of developing JAX RS application is to implement resource classes annotated with Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html with resource methods annotated with HTTP method annotations like GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html or POST http jax rs spec java net nonav 2 0 apidocs javax ws rs POST html and implement needed functionality This approach is described in the chapter JAX RS Application Resources and Sub Resources
87. tyTag String entity response getEntity String class If the ClientResponse type is not utilized and the response status is greater than or equal to 300 then the runtime exception UniformInterfaceException http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client UniformInterfaceException html is thrown This exception may be caught and the ClientResponse obtained as follows EXYIA String entity r get String class catch UniformInterfaceException ue ClientResponse response ue getResponse Creating new WebResources from a WebResource A new WebResource http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client WebResource html can be created from an existing WebResource by building from the latter s URI Thus it is possible to build the request URI before building the request For example the following appends a new path segment and adds some query parameters WebResource r c resource http localhost 8080 xyz MultivaluedMap lt String String gt params MultivaluedMapImpl 38 Client API 7 4 5 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 Java instances and types for representations All the Java types for representations supported by the Jersey server
88. ull for other object types and the Java defined default for primitive types The PathParam http jax rs spec java net nonav 2 0 apidocs javax ws rs PathParam html and the other parameter based annotations MatrixParam http jax rs spec java net nonav 2 0 apidocs javax ws rs MatrixParam html HeaderParam http jax rs spec java net nonav 2 0 apidocs javax ws rs HeaderParam html CookieParam http ax rs spec java net nonav 2 0 apidocs javax ws rs CookieParam html FormParam http jax rs spec java net nonav 2 0 apidocs javax ws rs FormParam html obey the same rules as QueryParam http jax rs spec java net nonav 2 0 apidocs javax ws rs QueryParam html MatrixParam http jax rs spec java net nonav 2 0 apidocs javax ws rs MatrixParam html extracts information from URL path segments HeaderParam http jax rs spec java net nonav 2 0 apidocs javax ws rs HeaderParam html extracts information from the HTTP headers CookieParam http jax rs spec java net nonav 2 0 apidocs javax ws rs CookieParam html extracts information from the cookies declared in cookie related HTTP headers FormParam http jax rs spec java net nonav 2 0 apidocs javax ws rs FormParam html is slightly special because it extracts information from a request representation that is of the MIME media type application x www form urlencoded and conforms to the encoding specified by HTML forms as described here This parameter is very useful for extract
89. urce 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 Building a request Requests to a Web resource are built using the builder pattern see RequestBuilder http jersey java net nonav apidocs 2 0 1 jersey com sun jersey api client RequestBuilder html where the terminating method corresponds to an HTTP method see UniformInterface http jersey java net nonav apidocs 2 0 1 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 3son 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
90. used for injection in the resource method directly Injecting the bean parameter into Singleton resource class fields is not allowed injections into method parameter must be used instead BeanParam http jax rs spec java net nonav 2 0 apidocs javax ws rs BeanParam html can contain all parameters injections injections PathParam http jax rs spec java net nonav 2 0 apidocs javax ws rs PathParam html QueryParam http jax rs spec java net nonav 2 0 apidocs 12 String enti final String pathParam beanParam getPathParam cont JAX RS Application Resources and Sub Resources javax ws rs QueryParam html MatrixParam http ax rs spec java net nonav 2 0 apidocs javax ws rs MatrixParam html HeaderParam http jax rs spec java net nonav 2 0 apidocs javax ws rs HeaderParam html CookieParam http jax rs spec java net nonav 2 0 apidocs javax ws rs CookieParam html FormParam http jax rs spec java net nonav 2 0 apidocs javax ws rs FormParam html More beans can be injected into one resource or method parameters even if they inject the same request values For example the following is possible Example 3 16 Injection of more beans into one resource methods POST public void post BeanParam MyBeanParam beanParam BeanParam String entity beanParam getPathParam pathParam OANA l Br GX Ne 3 3 Sub resources Path http jax rs spec java net nonav 2 0 apidocs javax ws rs
91. xml and application json are acceptable If both are equally acceptable then the former will be chosen because it occurs first Optionally server can also specify the quality factor for individual media types These are considered if several are equally acceptable by the client For example Produces application xml application json JAX RS Application Resources and Sub Resources Example 3 6 Server side content negotiation GET Produces application xml qs 0 9 application jso public String doGetAsXmlOrJson OO BON EH In the above sample if client accepts both application xml and application json equally then a server always sends application json since application xml has a lower quality factor The examples above refers explicitly to MIME media types for clarity It is possible to refer to constant values which may reduce typographical errors see the constant field values of MediaType http jax rs spec java net nonav 2 0 apidocs javax ws rs core MediaType html 3 1 4 Consumes The Consumes http jax rs spec java net nonav 2 0 apidocs javax ws rs Consumes html annotation is used to specify the MIME media types of representations that can be consumed by a resource The above example can be modified to set the cliched message as follows Example 3 7 Specifying input MIME type 1 2 Consumes text plain 3 public void postClichedMessage String message 4 5
92. y to their services especially if the client API is utilized by those services themselves or to test those services The goals of the client API are threefold 1 Encapsulate a key constraint of the REST architectural style namely the Uniform Interface Constraint and associated data elements as client side Java artifacts 2 Make it as easy to interoperate with RESTful Web services as the JAX RS server side API makes it easy to build RESTful Web services and 3 Share common concepts of the JAX RS API between the server and the client side The Client API supports a pluggable architecture to enable the use of different underlying HTTP client implementations Several such implementations are supported by Jersey To name a few we have a client connectors for Http s URLConnection classes supplied with the JDK and the Grizzly client 7 1 Uniform Interface Constraint The uniform interface constraint bounds the architecture of RESTful Web services so that a client such as a browser can utilize the same interface to communicate with 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 const

Download Pdf Manuals

image

Related Search

Related Contents

User`s manual complete - Sea  Borland Software Water System silk perforator java explorer 2006 release 2 User's Manual    Antenne Active D`extérieure DVB-T SRT ANT 15  Manuel d`utilisation - psn  GBC Laminating film NAP II  

Copyright © All rights reserved.
Failed to retrieve file