Home

Jersey 2.1 User Guide

Contents

1. 12 Type genericType 13 Annotation annotations MediaType mediaType 14 MultivaluedMap lt String String httpHeaders 15 InputStream entityStream 16 throws IOException WebApplicationException 17 18 try 19 JAXBContext jaxbContext JAXBContext newInstance MyBean class 20 MyBean myBean MyBean jaxbContext createUnmarshaller 21 unmarshal entityStream 22 return myBean 23 catch JAXBException jaxbException 24 throw new ProcessingException Error deserializing a MyBean 25 jaxbException 26 27 28 67 JAX RS Entity Providers It is obvious that the MessageBodyReader lt T gt interface is similar to MessageBodyWriter lt T gt In the next couple of sections we will explore it s API methods 7 2 2 1 MessageBodyReader isReadable It defines the method isReadable which has a very simliar meaning as method isWriteable in MessageBodyWriter lt T gt The method returns t rue if it is able to de serialize the given type The annotations parameter contains annotations that are attached to the entity parameter in the resource method In our POST resource method postMyBean the entity parameter myBean is not annotated therefore no annotation will be passed to the isReadable The mediaType parameter contains the entity media type The media type in our case must be consumable by the POST resource method which is specified by placing a JAX RS Consumes http
2. esee 177 17 7 Using Template on a resource class 2 0 0 cece eee cence cece ee meme mene 177 17 8 Custom Template PrOCeSSOt ooi iret ree dre ure er De eoo re tre re EIER gosh HH SE RE EON DRe Pete eg 179 17 9 Registering custom TemplateProcessor 0 1 0 0 00 ceeeceee cece ence HH Heer 180 20 1 Jersey 1 reloader implementation isesi onner ee E emen mme 189 20 2 Jersey 1 reloader registration snis repe pE e E E E III em memmee ment eere 189 20 3 Jersey 2 reloader implementation esssssssssseee e ehem enm enne 190 20 4 Jersey 2 reload r registration eoe er eet ede tere e rene se decet 190 xi Preface This is user guide for Jersey 2 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 snapshot jersey 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 questions 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 sel
3. 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 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
4. 8 try 9 System out println inboundEvent getName 10 inboundEvent getData String class 11 catch IOException e 12 throw new RuntimeException 13 Error when deserializing of data 14 15 16 LB 18 19 eventSource close The code above is very similar to the code in Example 13 3 Registering EventListener with EventSource The EventSource is constructed without the second boolean open argument This means that the connection to the server is by default automatically opened in the event source constructor The implementation of the EventListener has been moved into the overridden 144 Server Sent Events SSE Support EventSource onEvent method However this time the listener method will be executed for all events unnamed as well as with any name Therefore the code checks the name whether it is an event with the name message to client that we want to handle Note that you can still register additional Event Listeners later on The overridden method on the event source allows you to handle messages even when no additional listeners are registered yet 145 Chapter 14 Security 14 1 Securing server 14 1 1 SecurityContext Security information is available by injecting a SecurityContext http jax rs spec java net nonav 2 0 apidocs Javax ws rs core SecurityContext html instance using Context http jax rs spec java net nonav 2 0 apidocs jav
5. gt 76 request 77 lt response gt 78 lt representation mediaType gt 79 lt response gt 80 lt method gt 81 lt resource path path gt 82 lt param xmlns xs http www w3 org 2001 XMLSchema 83 type xs string style template name path gt 84 method name GET id geExternalGrammar gt 85 response 86 representation mediaType application xml 87 response 88 method 89 method name OPTIONS id apply gt 90 request 91 representation mediaType gt 92 request 93 response 94 representation mediaType text plain 95 lt response gt 96 lt method gt 97 lt method name OPTIONS id apply gt 98 lt request gt 99 lt representation mediaType gt 100 lt request gt 101 lt response gt 102 lt representation mediaType gt 103 lt response gt 104 lt method gt 105 lt resource gt 106 lt resource gt 107 lt resources gt 108 lt application gt 156 WADL Support 15 2 The resource with path customer id is similar to the country resource from the previous example There is a path parameter which identifies the customer by id The resource contains 2 user declared methods and again auto generated OPTIONS methods added by Jersey THe resource declares 2 sub resource locators which are represented in the returned WADL document as nested resource elements Note that the sub resource locator get CustomerAddress re
6. 3 private static int numberOfSuccessResponses 0 4 private static int numberOfFailures 0 5 private static Throwable lastException null 6 7 GET 8 public void asyncGetWithTimeout Suspended final AsyncResponse asyncRespon 9 asyncResponse register new CompletionCallback 10 Override 11 public void onComplete Throwable throwable 12 if throwable null 13 no throwabl the processing ended successfully 14 response already written to the client T5 numberOfSuccessResponsestt 16 Bpoedse f 17 numberOfFailurestt 18 lastException throwable 19 20 21 22 23 new Thread new Runnable 24 Override 25 public void run 26 String result veryExpensiveOperation 27 asyncResponse resume result 28 29 30 private String veryExpensiveOperation 31 very expensive operation 32 33 start 34 395 A completion callback is registered using register method on the AsyncResponse instance A registered completion callback is bound only to the response s to which it has been registered In the example the CompletionCallback is used to calculate successfully processed responses failures and to store last exception This is only a simple case demonstrating the usage of the callback You can use completion callback to release the resources change state of internal resources or representations or handle failures The method has an argument Throwable which is set only in case of an error
7. 66 JAX RS Entity Providers The result of console output is Example 7 6 Result of MyBeanMessageBodyWriter test 200 lt xml version 1 0 encoding UTF 8 standalone yes gt lt myBean gt lt anyString gt Hello World lt anyString gt lt anyNumber gt 42 lt anyNumber gt lt myBean gt The returned status is 200 and the entity is stored in the response in a XML format Next we will look at how the Jersey de serializes this XML document into a MyBean consumed by our POST resource method 7 2 2 MessageBodyReader In order to de serialize the entity of MyBean on the server or the client we need to implement a custom MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html Note Please note that this is only a demonstration of how to write a custom entity provider Jersey already contains default support for entity providers that can serialize JAXB beans into XML Our MessageBodyReader lt T gt implementation is listed in Example 7 7 MessageBodyReader example Example 7 7 MessageBodyReader example public static class MyBeanMessageBodyReader implements MessageBodyReader lt MyBean gt public boolean isReadable Class lt gt type Type genericType Annotation annotations MediaType mediaType return type MyBean class ile 2 3 4 Override 5 6 7 8 9 10 Override 11 public MyBean readFrom Class lt MyBean gt type
8. exposed at myresource path Path myresource public class MyResource GI Method handling HTTP GET requests The returned object will be sent to the client as text plain media type return String that will be returned as a text plain response ET E Produces MediaType TEXT PLAIN public String getIt return Got dtl A JAX RS resource is an annotated POJO that provides so called resource methods that are able to handle HTTP requests for URI paths that the resource is bound to See Chapter 3 JAX RS Application Resources and Sub Resources for a complete guide to JAX RS resources In our case the resource exposes a single resource method that is able to handle HTTP GET requests is bound to myresource URI path and can produce responses with response message content represented in text plain media type In this version the resource returns the same Got it response to all client requests The last piece of code that has been generated in this skeleton project is a MyResourceTest unit test class that is located in the same com example package as the MyResource class however this unit test class is placed into the maven project test source directory src test java certain code comments and JUnit imports have been excluded for brevity r20 0 1o0014 0 P2 rn ere packag import import import import public com xample javax ws rs
9. 1 Invocation Builder invocationBuilder 2 helloworldWebTargetWithQueryParam request MediaType TEXT PLAIN TYP 3 invocationBuilder header some header true A new invocation builder instance is created using one of the request methods that are available on WebTarget A couple of these methods accept parameters that let you define the media type of the representation requested to be returned from the resource Here we are saying that we request a text plain type This tells Jersey to add a Accept text plain HTTP header to our request The invocationBuilder is used to setup request specific parameters Here we can setup headers for the request or for example cookie parameters In our example we set up a some header header to value t rue Once finished with request customizations it s time to invoke the request We have two options now We can use the Invocation Builder to build a generic Invocation http jax rs spec java net nonav 2 0 apidocs javax ws rs client Invocation html instance that will be invoked some time later Using Invocation we will be able to e g set additional request properties which are properties in a batch of several requests and use the generic JAX RS Invocation API to invoke the batch of requests without actually knowing all the details such as request HTTP method configuration etc Any properties set on an invocation instance can be read during the request processing For example in a c
10. Constraint annotations on fields 163 Bean Validation Support Example 16 4 Constraint annotations on fields Path class MyResourceClass NotNull FormParam firstName private String firstName NotNull FormParam lastName private String lastName private String email FormParam email public void setEmail String email this email email Email public String getEmail return email Note that in this version firstName and lastName are fields initialized via injection and emailisa resource class property Constraint annotations on properties are specified in their corresponding getters Constraint annotations are also allowed on resource classes In addition to annotating fields and properties an annotation can be defined for the entire class Let us assume that NonEmptyNames validates that one of the two name fields in MyResourceClass is provided Using such an annotation the example above can be extended to look like Example 16 5 Constraint annotations on class Example 16 5 Constraint annotations on class Path NonEmptyNames class MyResourceClass NotNull FormParam firstName private String firstName NotNull FormParam lastName private String lastName private String email 164 Bean Validation Support Constraint annotations on resource classes are useful for defining cross field a
11. Select the set of available MessageBodyReader lt T gt providers that support the media type of the request Iterate through the selected MessageBodyReader T classes and utilizing their isReadable method choose the first MessageBodyReader lt T gt provider that supports the desired combination of Java type media type annotations parameters If Step 4 locates a suitable MessageBodyReader T then use its readF rom method to map the entity body to the desired Java type e Otherwise the server runtime MUST generate a NotSupportedException HTTP 415 status code and no entity and the client runtime MUST generate an instance of ProcessingException 71 JAX RS Entity Providers 7 4 Jersey MessageBodyWorkers API In case you need to directly work with JAX RS entity providers for example to serialize an entity in your resource method filter or in a composite entity provider you would need to perform quite a lot of steps You would need to choose the appropriate MessageBodyWriter lt T gt based on the type media type and other parameters Then you would need to instantiate it check it by isWriteable method and basically perform all the steps that are normally performed by Jersey see Procedure 7 2 MessageBodyReader T Selection Algorithm To remove this burden from developers Jersey exposes a proprietary public API that simplifies the manipulation of entity providers The API is defined by MessageBod
12. de request scope binding with specified custom annotation Injections addBinding Injections newBinder MyInjectablePerRequest class to MyInjectablePerRequest class qualifiedBy new MyAnnotationImpl in RequestScoped class de commits changes dc commit 188 Migrating from Jersey 1 x Override public Set lt Class lt gt gt getClasses return 20 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 20 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 ContainerListener 6 7 8 public void addListener ContainerListener 1 9 ls add 1 10 11 12 public void reload 13 for ContainerListener 1 1s 14 l onReload 15 16 EIJ Example 20 2 Jersey 1 reloader registration 1 Reloader reloader new Reloader
13. List of common configuration properties that can be found in CommonProperties http jersey java net nonav apidocs snapshot Jersey org glassfish jersey CommonProperties html class All of these properties can be overridden by their server client counterparts Table A 1 List of common configuration properties Constant Value Description CommonProperties FEATURE AUSOs BySCONERY DISABIM u Dosabkes ofeatmye auto discovery http jersey java net nonav globally on client server Default apidocs snapshot jersey org value is false glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE CommonProperties JSON_PROCESSiNGy FEATURE d3ISABIdU s Disablese senfiguration of Json http jersey java net nonav Processing JSR 353 feature apidocs snapshot jersey org Default value is false glassfish jersey CommonProperties html JSON_RROCESSING_FEATURE_DISABLE CommonProperties METAINF_SERMI amp S LOOK GP di BB eRe Disables e rv METBAdoNE gervices http jersey java net nonav lookup globally on client server apidocs snapshot jersey org Default value is false glassfish jersey CommonProperties html METAINF SERVICES LOOKUP DISABLE CommonProperties MOXY_JSONjJEEAPWRibwWASABLEs ableMaEys bles configuration of MOXy http jersey java net nonav Json feature Default value is apidocs snapshot jersey org false glassfish jersey CommonProperties html MOXY JSON_FEATURE_DISABLE CommonProperties
14. param message the String that is the entity of the 404 response 13 ard 14 public CustomNotFoundException String message T5 super Response status Responses NOT FOUND 16 entity message type text plain build 17 18 In other cases it may not be appropriate to throw instances of WebApplicationException 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 a custom exception mapping provider The provider must implement 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 5 api javax persistence EntityNotFoundException html to a HTTP 404 Not Found response Example 6 6 Mapping generic exceptions to responses 1 Provider 2 public class EntityNotFoundMapper implements ExceptionMapper lt javax persistence 3 public Response toResponse javax persistence EntityNotFoundException ex return Response status 404 entity ex getMessage type text plain build O OANA OB The above class is annotated with Provider h
15. 19 2 19 3 Checking Out the Source Jersey source code is available on GitHub You can browse the sources at https github com jersey jersey In case you are not familiar with Git we recommend reading some 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 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 git github com jersey jersey git This creates read only copy of Jersey workspace If you want to contribute please use pull request https help github com articles creating a pull request 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 or by visiting https github com jersey jersey tags Building the Source Jersey source code requires Java SE 6 or greater The build is based on Maven Maven 3 or greater is highly recommended Also it is recommended you use the following Maven options when building the workspace can be set in MAVEN_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 reposit
16. 7 2 2 3 Testing a MessageBodyWriter T Now let s send a test request using the JAX RS Client API Example 7 8 Testing MyBeanMessageBodyReader final MyBean myBean new MyBean posted MyBean 11 Response response webTarget path resource request application xml post Entity entity myBean application xml System out println response getStatus final String responseEntity response readEntity String class System out println responseEntity 1 2 3 4 5 6 7 8 The console output is 68 JAX RS Entity Providers Example 7 9 Result of testing MyBeanMessageBodyReader 200 posted MyBean 7 2 2 4 Using Entity Providers with JAX RS Client API Both MessageBodyReader lt T gt and MessageBodyWriter lt T gt can be registered in a configuration of JAX RS Client API components typically without any need to change their code The example Example 7 10 MessageBodyReader registered on a JAX RS client is a variation on the Example 7 5 Client code testing MyBeanMessageBodyWriter listed in one of the previous sections Example 7 10 MessageBodyReader registered on a JAX RS client Client client ClientBuilder newBuilder register MyBeanMessageBodyReader class build Response response client target http example comm resource request MediaType APPLICATION XML get System out println response getStatus MyBean myBean response readEntity
17. and on the interceptor GZIPWriterInterceptor The interceptor will 110 Filters and Interceptors be executed only if any resource method with such a annotation will be executed In our example case the interceptor will be executed only for the get VeryLongString method The interceptor will not be executed for method getHello In this example the reason is probably clear We would like to compress only long data and we do not need to compress the short response of Hello World Name binding can be applied on a resource class In the example Hel loWorldResource would be annotated with Compress This would mean that all resource methods will use compression in this case There might be many name binding annotations defined in an application When any provider filter or interceptor is annotated with more than one name binding annotation then it will be executed for resource methods which contain ALL these annotations So for example if our interceptor would be annotated with another name binding annotation GZIP then the resource method would need to have both annotations attached 9 Compress and 9 GZIP otherwise the interceptor would not be executed Based on the previous paragraph we can even use the combination when the resource method get VeryLongString would be annotated with 9 Compress and resource class He1l1oWorldResource would be annotated from with GZIP This would also trigger the interceptor as annotations of reso
18. designed web site may for example return 304 Not Modified responses for many of 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 Example 6 7 Conditional GET support 1 public SparklinesResource 2 QueryParam d IntegerList data 3 DefaultValue 0 100 QueryParam limits Interval limits 4 Context Request request 5 6 7 8 Context Urilnfo ui if data null throw new WebApplicationException 400 9 10 this data data 11 this limits limits 12 13 if limits contains data 14 throw new WebApplicationException 400 15 16 17 this tag computeEntityTag ui getRequestUri 18 19 if request getMethod equals GET 20 Response ResponseBuilder rb request evaluatePreconditions tag 21 if rb null 22 throw new WebApplicationException rb build 23 24 25 5 The constructor of the SoarklinesResouce 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
19. ul li ConstraintValidationFactory so that validators are able to inject Jer lt li gt ParameterNameProvider if method input parameters are invalid this cl instead of the default ones code arg0 argl li ul public class ValidationConfigurationContextResolver implements ContextResolver lt Val Context private ResourceContext resourceContext QOverride public ValidationConfig getContext final Class lt gt type final ValidationConfig config new ValidationConfig config setConstraintValidatorFactory resourceContext getResource Injecting config setParameterNameProvider new CustomParameterNameProvider return config See ContactCardTest testAddInvalidContact private class CustomParameterNameProvider implements ParameterNameProvider private final ParameterNameProvider nameProvider public CustomParameterNameProvider nameProvider Validation byDefaultProvider configure getDefaultPa Override public List lt String gt getParameterNames final Constructor lt gt constructor return nameProvider getParameterNames constructor Override public List String getParameterNames final Method method See ContactCardTest testAddInvalidContact if addContact equals method getName return Arrays asList contact return nameProvider getParameterNames method Register this class im Your appo1 i cation new ResourceCon
20. 127 Programmatic API for Building Resources Example 12 1 A standard resource class 1 2 Path helloworld 3 public class HelloWorldResource 4 5 GET 6 Produces text plain 7 public String getHello 8 return Hello World 9 10 Wal 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 12 2 A programmatic resource 1 2 package org glassfish jersey examples helloworld 3 4 import javax ws rs container ContainerRequestContext 5 import javax ws rs core Application 6 import javax ws rs core Response 7 import org glassfish jersey process Inflector 8 import org glassfish jersey server ResourceConfig 9 import org glassfish jersey server model Resource 10 import org glassfish jersey server model ResourceMethod 11 12 13 public static class MyResourceConfig extends ResourceConfi 14 15 public MyResourceConfig 16 final Resource Builder resourceBuilder Resourc ie resourceBuilder path helloworld 18 19 final ResourceMethod Builder methodBuilder resou 20 methodBuilder produces MediaType TEXT PLAIN TYPE 21 handledBy new Inflector ContainerRequestC 22 23 Override 24 public String apply ContainerRequestContext co 25 return Hello World 26 27 28 29 final Reso
21. 24 MyBean class MyBean class new Annotation 25 MediaType APPLICATION_XML_TYPE new MultivaluedHashMap lt String 26 baos 2 catch IOException e 28 throw new RuntimeException 29 Error while serializing MyBean e 30 31 32 final String stringXmlOutput baos toString 33 stringXmlOutput now contains XML representation 34 lt xml version 1 0 encoding UTF 8 standalone yes gt 35 lt myBean gt lt anyString gt Hello World lt anyString gt 36 lt anyNumber gt 42 lt anyNumber gt lt myBean gt 37 38 return stringXmlOutput 39 40 In the example a resource injects MessageBodyWorkers and uses it for selection of the most appropriate MessageBodyWriter lt T gt Then the writer is utilized to serialize the entity into the buffer as XML document The String content of the buffer is then returned This will cause that Jersey will not use MyBeanMessageBodyWriter to serialize the entity as it is already in the String type MyBeanMessageBodyWriter does not support String Instead a simple St ring based MessageBodyWriter lt T gt will be chosen and it will only serialize the St ring with XML to the output entity stream by writing out the bytes of the String Of course the code in the example does not bring any benefit as the entity could have been serialized by MyBeanMessageBodyWriter by Jersey as in previous examples the purpose of the example was to show how to use MessageBodyWorkers in a resource met
22. 5 2 Using JAX RS Client API cedro Rr err hr HERR EE RR pre E erre ERR diei 51 5 3 Using JAX RS Client API fluently 2 0 0 cc cece HH hehehe 52 6 1 Using File with a specific media type to produce a response 00 cee eeeeeeeeeece eee eeeneees 37 6 2 Returning 201 status code and adding Location header in response to POST request 58 6 3 Adding an entity body to a custom response sssssessess eH He 58 6 4 Throwing exceptions to control response eee eee cece cece emen men herren 58 6 5 Application specific exception implementation ssessesee Hee 59 6 6 Mapping generic exceptions to responses ssssssse HH emere hene 59 6 7 Conditional GET support ied D rH e ERR MERE RREEREXTIR EXE POSER ERORA ES 60 7 1 Example resource class eee eeepc EEEa KOGE EAE E EEEE TEENE EES 63 7 2 MyBean entity class iuret itte ee Oe Oto EE onsets E EE eae EEES 63 7 3 MessageBodyWriter example sss ee He ee hehe hen rentrer 64 7 4 Example of assignment of annotations to a response entity esssssse eeceeeeeeeee ees 65 7 5 Client code testing MyBeanMessageBodyWriter sssssse e 66 7 6 Result of MyBeanMessageBodyWriter test sesesssssseseseseeeee seca sean eme enne 67 7 7 MessageBodyReader example esscr noe eiee serei eme I en ee mee eere rentre 67 7 8 Testing MyBeanMessageBodyReader ssssssessesseseee em em e He eme
23. JSONException ex 6 LOGGER log Level SEVERE Error ex FS Media modules that support the low level JSON parsing and generating approach are Java API for JSON Processing JSON P and Jettison Unless you have a strong reason for using the non standard Jettison API we recommend you to use the new standard Java API for JSON Processing JSON P API instead 8 1 2 MOXy 8 1 2 1 Dependency To use MOXy as your JSON provider you need to add jersey media moxy module to your pom xm1 file dependency groupId org glassfish jersey media c groupId artifactId jersey media moxy artifactId version 2 1 version dependency If you re not using Maven make sure to have all needed dependencies see jersey media moxy https jersey java net project info 2 1 jersey project jersey media moxy dependencies html on the classpath 8 1 2 2 Configure and register As stated in the Section 4 1 Auto Discoverable Features as well as earlier in this chapter MOXy media module is one of the modules where you don t need to explicitly register it s Features MoxyJsonFeature in your client server Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html as this feature is automatically discovered and registered when you add jersey media moxy module to your class path The auto discoverable jersey media moxy module defines a few properties that can be used to control the automatic reg
24. MyBean class System out println myBean OANA OB CO For The code above registers MyBeanMessageBodyReader to the Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html configuration using a ClientBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientBuilder html which means that the provider will be used for any WebTarget http jax rs spec java net nonav 2 0 apidocs Javax ws rs client WebTarget html produced by the client instance Note You could also register the JAX RS entity and any other providers to individual WebTarget instances produced by the client Then using the fluent chain of method invocations a resource target pointing to our MyResource is defined a HTTP GET request is invoked The response entity is then read as an instance of a MyBean type by invoking the response readEntity method that internally locates the registered MyBeanMessageBodyReader and uses it for entity de serialization The console output for the example is Example 7 11 Result of client code execution 200 MyBean anyString Hello World anyNumber 42 7 3 Entity Provider Selection Usually there are many entity providers registered on the server or client side be default there must be at least providers mandated by the JAX RS specification such as providers for primitive types byte array JAXB beans etc JAX RS defines an algorithm for selecting the m
25. Notice that it is not necessary to worry about the inclusion of characters or that the user ID may contain characters that need to be percent encoded UriBuilder takes care of such details UriBuilder 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 11 2 Building URIs using query parameters 1 UriBuilder fromUri http localhost 2 path a 3 queryParam name value 4 build segment value 11 2 Resolve and Relativize JAX RS 2 0 introduced additional URI resolution and relativization methods in the UriBuilder e Urilnfo resolve java net URI http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html resolve Gjava net URD e UriInfo relativize java net URI http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html relativize java net URI e UriBuilder resolveTemplate http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html resolveTemplate java lang String java lang Object various arguments Resolve and relativize methods in Urilnfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriInfo html are essentially counterparts to the methods listed above Urilnfo resolve java net URT http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriInfo htmlitresolve java net URT reso
26. Otherwise the parameter will be nu11 which means that the response was successfully written The callback is executed only after the response is written to the client not immediately after the response is resumed The AsyncResponse register method is overloaded and offers options to register a single callback as an Ob ject in the example as a Class or multiple callbacks using varags As some async requests may take long time to process the client may decide to terminate it s connection to the server before the response has been resumed or before it has been fully written to the client To deal with these use cases a Connect ionCallback can be used This callback will be executed only if the connection was prematurely terminated or lost while the response is being written to the back client Note 117 Asynchronous Services and Clients that this callback will not be invoked when a response is written successfully and the client connection is closed as expected See javadoc of ConnectionCallback http jax rs spec java net nonav 2 0 apidocs javax ws rs container ConnectionCallback html for more information 10 1 2 Chunked Output Jersey offers a facility for sending response to the client in multiple more or less independent chunks using a chunked output Each response chunk usually takes some longer time to prepare before sending it to the client The most important fact about response chunks is that you want to send them
27. and set values of needed properties For most common properties you can use a particular method to set the value of the property or you can use more generic methods to set the property MoxyJsonConfig property java lang String java lang Object http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy json MoxyJsonConfig html property java lang String java lang Object sets a property value for both Marshaller and Unmarshaller MoxyJsonConfig marshallerProperty java lang String java lang Object http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy json MoxyJsonConfig html marshallerProperty java lang String java lang Object sets a property value for Marshaller MoxyJsonConfig unmarshallerProperty java lang String java lang Object http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy json MoxyJsonConfig html unmarshallerProperty java lang String java lang Object sets a property value for Unmarshaller Example 8 7 MoxyJsonConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy json MoxyJsonConfig html Setting properties final Map lt String String gt namespacePrefixMapper new HashMap lt String String gt namespacePrefixMapper put http www w3 org 2001 XMLSchema instance xsi final MoxyJsonConfig configuration new MoxyJsonConfig SetNamespacePrefixMapper namespacePrefixMapper setNamespaceS
28. http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventInput html See the following code 1 Client client ClientBuilder newBuilder 2 register SseFeature class build 3 WebTarget target client target http localhost 9998 events 4 5 EventInput eventInput target request get EventInput class 6 while eventInput isClosed 7 final InboundEvent inboundEvent eventInput read 8 if inboundEvent null 9 connection has been closed 10 break 11 12 System out println inboundEvent getName 13 inboundEvent getData String class 14 In this example a client connects to the server where the SseResource from the Example 13 1 Simple SSE resource method is deployed At first a new JAX RS Jersey client instance is created with a SseFeature registered Then a WebTarget http jax rs spec java net nonav 2 0 apidocs javax ws rs client WebTarget html instance is retrieved from the client and is used to invoke a HTTP 141 Server Sent Events SSE Support request The returned response entity is directly read as a Event Input Java type which is an extension of Jersey ChunkedInput that provides generic support for consuming chunked message payloads The code in the example then process starts a loop to process the inbound SSE events read from the event Input response stream Each chunk read from the input is a Inboun
29. m 6 Encoded 7 DefaultValue default 8 private String matrixParam 9 10 HeaderParam header 11 private String headerParam 12 13 private String queryParam 14 15 public MyBeanParam GQueryParam q String queryParam 16 this queryParam queryParam 17 18 19 public String getPathParam 20 return pathParam 2l 22 23 Example 3 15 Injection of MyBeanParam as a method parameter 1 POST 2 public void post 8BeanParam MyBeanParam beanParam String entity 3 final String pathParam beanParam getPathParam contains injected pa 4 De 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 O 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 O apidocs javax ws rs 30 JAX RS Application Resources and Sub Resources 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
30. only method that does not override the annotation by defining custom role based security settings using the RolesAllowed http docs oracle com javaee 6 api javax annotation security RolesAllowed html annotation QRolesAllowed annotation present on other methods defines a role or a set of roles that are allowed to execute a particular method These Java EE security annotations are processed internally in the request filter registered using the Jersey RolesAllowedDynamicFeature The roles defined in the annotations are tested against current roles 148 Security set in the SecurityContext using the SecurityContext isUserInRole String role method In case the caller is not in the role specified by the annotation the HTTP 404 error response is returned 14 2 Client Security For details about client security please see the Client chapter Jersey client allows to define parameters of SSL communication using HTTPS protocol You can also use jersey built in authentication filter which performs HTTP Basic Authentication See the client chapter for more details 14 3 OAuth OAuth 1 x support has not been migrated from Jersey 1 x to Jersey 2 x yet The documentation will be updated once the OAuth support feature will be released in Jersey 2 149 Chapter 15 WADL Support 15 1 WADL introduction Jersey contains support for Web Application Description Language WADL http wadl java net WADL is a XML description of
31. target simple service webapp war and deploy it to a Servlet container of your choice Important To deploy a Jersey application you will need a Servlet container that supports Servlet 2 5 or later For full set of advanced features such as JAX RS 2 0 Async Support you will need a Servlet 3 0 or later compliant container 1 5 Exploring Other Jersey Examples In the sections above we have covered an approach how to get dirty with Jersey quickly Please consult the other sections of the Jersey User Guide to learn more about Jersey and JAX RS Even though we try our best to cover as much as possibly in the User Guide there is always a chance that you would not be able to get a full answer to the problem you are solving In that case consider diving in our examples that provide additional tips and hints to the features you may want to use in your projects Jersey codebase contains a number of useful examples on how to use various JAX RS and Jersey features Feel free to browse through the code of individual Jersey Examples https github com jersey jersey tree master examples in the Jersey source repository For off line browsing you can also download a bundle with all the examples from here https maven java net content repositories releases org glassfish jersey bundles jersey examples 2 1 Chapter 2 Modules and dependencies 2 1 Java SE Compatibility All Jersey components are compiled with Java SE 6 target It means yo
32. the connection to the requesting client and registers this eventOutput instance with the singleton broadcaster using its add EventOutput method The method then returns the eventOutput which causes Jersey to bind the event Out put instance with the requesting client and send the response HTTP headers to the client The client connection remains open and the client is now waiting ready to receive new SSE events All the events are written to the eventOutput by broadcaster later on This way developers can conveniently handle sending new events to all the clients that subscribe to them When a client wants to broadcast new message to all the clients listening on their SSE connections it sends a POST request to BroadcasterResource resource with the message content The method broadcastMessage String is invoked on BroadcasterResource resource with the message content as an input parameter A new SSE outbound event is built in the standard 140 Server Sent Events SSE Support way and passed to the broadcaster The broadcaster internally invokes write OutboundEvent on all registered EventOutputs After that the method just return a standard text response to the POSTing client to inform the client that the message was successfully broadcast As you can see the broadcastMessage String resource method is just a simple JAX RS resource method In order to implement such a scenario you may have noticed that the Jersey SseBroad
33. 1 jersey project jersey media moxy dependencies html jersey media multipart https jersey java net project info 2 1 jersey project jersey media multipart dependencies html Jersey Multipart entity providers support module jersey media sse https jersey java net project info 2 1 jersey project jersey media sse dependencies html Jersey Server Sent Events entity providers support module Table 2 5 Jersey Extensions Extensions jersey bean validation https jersey java net project info 2 1 jersey project jersey bean validation dependencies html Jersey extension module providing support for Bean Validation JSR 349 API jersey mvc https jersey java net project info 2 1 jersey project jersey mvc dependencies html Jersey extension module providing support for MVC jersey mvc freemarker https jersey java net project info 2 1 jersey project jersey mvc freemarker dependencies html Jersey extension module providing support for Freemarker templates jersey mvc jsp https jersey java net project info 2 1 jersey project jersey mvc jsp dependencies html Jersey extension module providing support for JSP templates 12 Modules and dependencies jersey proxy client https jersey java net project info 2 1 jersey project jersey proxy client dependencies html Jersey extension modu
34. 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 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 ContainerRequestC 33 Override 34 public String apply ContainerRequestCo 35 return On this path the resource 36 methods is deployed 37 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 49 50 Override 51 public ResourceModel processSubResource ResourceModel 52 we just return the original subResourceModel wh 53 return subResourceModel 54 55 56 132 Programmatic API for Building Resources The MyOptionsModelProcessor from the example is a relatively simple model processor
35. 2 0 apidocs javax ws rs ext WriterInterceptor html Reader interceptors are used to manipulate inbound 105 Filters and Interceptors entity streams These are the streams coming from the wire So using a reader interceptor you can manipulate request entity stream on the server side where an entity is read from the client request and response entity stream on the client side where an entity is read from the server response Writer interceptors are used for cases where entity is written to the wire which on the server means when writing out a response entity and on the client side when writing request entity for a request to be sent out to the server Writer and reader interceptors are executed before message body readers or writers are executed and their primary intention is to wrap the entity streams that will be used in message body reader and writers The following example shows a writer interceptor that enables GZIP compression of the whole entity body Example 9 5 GZIP writer interceptor public class GZIPWriterInterceptor implements WriterInterceptor 1 2 3 Override 4 public void aroundWriteTo WriterInterceptorContext context 5 throws IOException WebApplicationException 6 7 8 9 0 final OutputStream outputStream context getOutputStream context setOutputStream new GZIPOutputStream outputStream context proceed 10 The interceptor gets a output stream from the WriterInterceptorCo
36. 2 resourceConfig getProperties put ResourceConfig PROPERTY CONTAINER NOTIFIER 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 http jax rs spec java net nonav 2 0 189 Migrating from Jersey 1 x apidocs javax ws rs ext Provider html annotation or adding it to the Jersey ResourceConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ResourceConfig html directly either using the class using ResourceConfig addClasses or registering a particular instance using ResourceConfig addSingletons method An example on how things work in Jersey 2 follows Example 20 3 Jersey 2 reloader implementation 1 public class Reloader implements ContainerLifecycleListener 2 3 Container container 4 5 public void reload ResourceConfig newConfig 6 container reload newConfig 7 8 9 public void reload 10 container reload 11 i 13 Override 14 public void onStartup Container container 15 this containe
37. 5 throws IOException WebApplicationException 6 7 8 9 0 final InputStream originallnputStream context getInputStream context setInputStream new GZIPInputStream originallInputStream return context proceed 10 The GZIPReaderInterceptor wraps the original input stream with the GZIPInputStream All further reads from the entity stream will cause that data will be decompressed by this stream The interceptor method aroundReadFrom must return an entity The entity is returned from the proceed method of the ReaderInterceptorContext http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ReaderInterceptorContext html The proceed method internally calls the wrapped interceptor which must also return an entity The proceed method invoked from the last interceptor in the chain calls message body reader which deserializes the entity end returns it Every interceptor can change this entity if there is a need but in the most cases interceptors will just return the entity as returned from the proceed method As already mentioned above interceptors should be primarily used to manipulate entity body Similar to methods exposed by WriterInterceptorContext the ReaderInterceptorContext introduces a set of methods for modification of request response properties like HTTP headers URIs and or HTTP methods excluding getters and setters for entity as entity has not been read yet Again the same rules as for Writer
38. API complementary to their services especially if the client API is utilized by those services themselves or to test those services The JAX RS client API finds inspiration in the proprietary Jersey 1 x Client API and developers familiar with the Jersey 1 x Client API should find it easy to understand all the concepts introduced in the new JAX RS Client API 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 consume RESTful Web services exposed over HTTP same as the JAX RS server side API makes it easy to develop RESTful Web services and 3 Share common concepts and extensibility points of the JAX RS API between the server and the client side programming models As an extension to the standard JAX RS Client API the Jersey Client API supports a pluggable architecture to enable the use of different underlying HTTP client Connector http jersey java net nonav apidocs snapshot jersey org glassfish jersey client spi Connector html implementations Several such implementations are currently provided with Jersey We have a default client connector using Http s URLConnection supplied with the JDK as well as connector implementations based on Apache HTTP Client and Grizzly Asynchronous Client 5 1 Uniform Interface Constraint The uniform interface constraint boun
39. 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 ApplicationPath html annotation can be used to annotate the user defined application class and specify the the base resource URI of all application resources Example 4 3 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 1 ApplicationPath resources 2 public class MyApplication extends ResourceConfig 3 public MyApplication packages org foo rest org bar rest YHA OB Please note that there is more which can be set or called during execution of ResourceConfig descendants constructor see ResourceConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ResourceConfig html javadoc for more details 41 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 4 4 Configuration of maven war plugin in pom xm1 with Servlet 3 0 1 lt plugins gt 2 3 3 plugin 4 groupId org apache maven plugins groupId 2 lt artifactId gt maven war plugin lt artifactId gt 6 lt version gt 2 3 lt version gt 7 lt configuration gt 8 failOnMissingW
40. EntityManager 19 Modules and dependencies bookstore webapp https jersey java net project info 2 1 jersey project webapp example parent bookstore webapp dependencies html Jersey MVC Bookstore example cdi webapp https jersey java net project info 2 1 jersey project webapp example parent cdi webapp dependencies html extended wadl webapp https jersey java net project info 2 1 jersey project webapp example parent extended wadl webapp dependencies html Jersey CDI example Extended WADL example freemarker webapp https jersey java net project info 2 1 jersey project webapp example parent freemarker webapp dependencies html Jersey Freemarker example helloworld webapp https jersey java net project info 2 1 jersey project webapp example parent helloworld webapp dependencies html Jersey annotated resource class Hello world example https server glassfish https jersey java net project info 2 1 jersey project webapp example parent https Jersey HTTPS server on GlassFish example 20 Modules and dependencies server glassfish dependencies html jersey ejb https jersey java net project info 2 1 jersey project webapp example parent jersey ejb dependencies html Jersey EJB example json processing webapp https jersey java net project info 2 1
41. JAX RS Client API fluently Client client ClientBuilder newClient new ClientConfig register MyClientResponseFilter class register new AnotherClientFilter 1 2 3 4 5 String entity client target http example com rest 6 register FilterForExampleCom class 7 path resource helloworld 8 queryParam greeting Hi World 9 0 1 request MediaType TEXT_PLAIN_TYP header some header true get String class Gl The code above does the same thing except it skips the generic Response processing and directly requests an entity in the last get String class method call This shortcut method let s you specify that in case the response was returned successfully with a HTTP 2xx status code the response entity should be returned as Java String type This compact example demonstrates another advantage of the JAX RS client API The fluency of JAX RS Client API is convenient especially with simple use cases Here is another a very simple GET request returning a String representation entity 1 String responseEntity ClientBuilder newClient 2 target http example com path resource rest 3 request get String class 5 4 Java instances and types for representations 5 4 1 All the Java types and representations supported by default on the Jersey server side for requests and responses are also supported on the client side For example to process a response en
42. QueryParam http jax rs spec java net nonav 2 0 apidocs javax ws rs QueryParam html etc It also supports mapping of the request entity bodies into Java objects via non annotated parameters i e parameters without any JAX RS annotations The Bean Validation specification supports the use of constraint annotations as a way of declaratively validating beans method parameters and method returned values For example consider resource class from Example 16 3 Constraint annotations on input parameters augmented with constraint annotations Example 16 3 Constraint annotations on input parameters Path class MyResourceClass POST Consumes application x www form urlencoded public void registerUser NotNull FormParam firstName String firstName NotNull FormParam lastName String lastName Email FormParam email String email The annotations NotNull and Email impose additional constraints on the form parameters firstName lastName and email The QNotNull constraint is built in to the Bean Validation API the Email constraint is assumed to be user defined in the example above These constraint annotations are not restricted to method parameters they can be used in any location in which JAX RS binding annotations are allowed with the exception of constructors and property setters Rather than using method parameters the MyResourceClass shown above could have been written as in Example 16 4
43. an exception would be thrown at run time complaining about the missing chunk type definition In the next lines in the example individual chunks are being read from the response Chunks can come with some delay so they will be written to the console as they come from the server After receiving last chunk the nu11 will be returned from the read method This will mean that the server has sent the last chunk and closed the connection Note that the read is a blocking operation and the invoking thread is blocked until a new chunk comes Writing chunks with ChunkedOut put is simple you only call method write which writes exactly one chunk to the output With the input reading it is slightly more complicated The ChunkedInput does not know how to distinguish chunks in the byte stream unless being told by the developer In order to define custom chunks boundaries the ChunkedInput offers possibility to register a ChunkParser http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ChunkParser html which reads chunks from the input stream and separates them Jersey provides several chunk parser implementation and you can implement your own parser to separate your chunks if you need In our example above the default parser provided by Jersey is used that separates chunks based on presence of a r n delimiting character sequence Each incoming input stream is firstly parsed by the ChunkParser then each chunk is processe
44. application xml In our implementation of the isWriteable method we just check that the type is MyBean Please note that this method might be executed multiple times by Jersey runtime as Jersey needs to check whether this provider can be used for a particular combination of entity Java type media type and attached annotations which may be potentially a performance hog You can limit the number of execution by properly defining the Produces annotation on the MessageBodyWriter lt T gt In our case thanks to Produces annotation the provider will be considered as writeable and the method isWriteable might be executed only if the media type of the outbound message is application xml Additionally the provider will only be considered as possible candidate and its isWriteable method will be executed if the generic type of the provider is either a sub class or super class of t ype parameter 7 2 1 2 MessageBodyWriter writeTo Once a message body writer is selected as the most appropriate see the Section 7 3 Entity Provider Selection for more details on entity provider selection its writeTo method is invoked This method receives parameters with the same meaning as in isWriteable as well as a few additional ones In addition to the parameters already introduced the writeTo method defies also ht tpHeaders parameter that contains HTTP headers associated with the outbound message 65 JAX RS Entity Providers Note When a M
45. are built up programmatically It is possible to use the very same mechanism to return HTTP errors directly e g when handling exceptions in a try catch block However to better align with the Java programming model JAX RS allows to define direct mapping of Java exceptions to HTTP error responses The following example shows throwing CustomNotFoundi order to return an error HTTP response to the client Exception from a resource method in Example 6 4 Throwing exceptions to control response 1 Path items itemid 2 public Item getItem PathParam itemid 3 Item i getItems get itemid if i null throw new CustomNotFoundException 4 5 6 7 8 return i 9 String itemid Item itemid is not found This exception is an application specific exception that extends WebApplicationException http jax rs spec java net nonav 2 0 apidocs javax ws rs W ebApplicationException html and builds a HTTP response with the 404 status code and an optional message as the body of the response 58 Representations and Responses Example 6 5 Application specific exception implementation public class CustomNotFoundException extends WebApplicationException 1 2 3 4 Create a HTTP 404 Not Found exception 5 xf 6 7 8 public CustomNotFoundException super Responses notFound build 9 10 EA 11 Create a HTTP 404 Not Found exception 12
46. cee ceee cece eee c nec ceeece cece cena Here 23 3 2 Specifying URI path parameter sssssesese HH HH eere hene 24 3 3 PUT Method 4i d e rte o iere ERI NE PERSE PR ERE HA ERE RM IE 25 3 4 Specifying output MIME type 2 0 0 eee cee cee HH HI eme em mhem meet ent entren 25 3 5 Using multiple output MIME types cssses III emm eme eere 26 3 6 Server side content negotiation 2 2 0 0 cece cece cece cece cece ne een em e mee mee meme en he mee renes 26 3 7 Specifying input MIME type ierit ertet ERE ERIS SERE HR POR ERES ERR RAE 27 3 8 Query parameters ioc oriente deiabe ences la sdbes dy echt EE E S ES E E eee 27 3 9 Custom Java type for consuming request parameters sss 28 3 10 Processing POSTed HTML form ssessesseee IH HII Im ene hee rene 29 3 11 Obtaining general map of URI path and or query parameters essen 29 3 12 Obtaining general map of header parameters ssssssssee e 29 3 13 Obtaining general map of form parameters sssssssses eene 29 3 14 Example of the bean which will be used as BeanParam eA 30 3 15 Injection of MyBeanParam as a method parameter esssse ence eeceeeeeeeeneeeaes 30 3 16 Injection of more beans into one resource methods sssesA 31 3 LT Sub resource methods 332 ett ette Dp tei erre rax metas ee PCIE EU dates saber ERR Etpe 32 3 18 Sub resource locators
47. client Client javax ws rs client ClientBuilder javax ws rs client WebTarget org glassfish grizzly http server HttpServer class MyResourceTest Getting Started 12 13 private HttpServer server 14 private WebTarget target 1 5 16 Before 17 public void setUp throws Exception 18 server Main startServer 19 20 Client c ClientBuilder newClient 2l target c target Main BASE URI 22 23 24 After 25 public void tearDown throws Exception 26 server stop 27 28 29 30 Test to see that the message Got it is sent in the response 31 a 32 Test 33 public void testGetIt 34 String responseMsg target path myresource request get String cl 35 assertEquals Got it responseMsg 36 Sy In this unit test a Grizzly container is first started and server application is deployed in the test set Up method by a static call to Main startServer Next a JAX RS client components are created in the same test set up method First a new JAX RS client instance c is built and then a JAX RS web target component pointing to the context root of our application deployed at http localhost 8080 myapp a value of Main BASE URI constant is stored into a target field of the unit test class This field is then used in the actual unit test method testGetIt In the testGetIt method a fluent JAX RS Client API is used to connect to a
48. define the JAXBContextFactory from which a JAXBContext instance would be obtained for more on this topic read JavaDoc on JAXBContext http jaxb java net nonav 2 2 7 docs api javax xml bind JAXBContext html or you can add jersey media moxy module to your project and register configure MoxyXmlFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy xml MoxyXmlFeature html class instance in the Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html Example 8 37 Add jersey media moxy dependency dependency groupId org glassfish jersey media groupId artifactId jersey media moxy artifactId version 2 1 version dependency Example 8 38 Register the MoxyXmlFeature class 1 final ResourceConfig config new ResourceConfig 2 packages org glassfish jersey examples xmlmoxy 3 register MoxyXmlFeature class Example 8 39 Configure and register an MoxyXmlFeature instance Configure Properties final Map lt String Object properties new HashMap lt String Object gt Obtain a ClassLoader you want to use OANA OF CO Fo FE final ResourceConfig config new ResourceConfig 9 packages org glassfish jersey examples xmlmoxy 10 register new MoxyXmlFeature 11 properties 12 classLoader 13 true Flag to determine whether eclipselink oxm xml file should be 14 CustomClassA class Custom
49. ee Re eS 119 10 5 Simple client async invocation ssssssssese e mem em He mee ener 120 10 6 Simple client fluent async invocation essesseseeee eme Hee m emen 120 10 7 Chent asyne callback xs eti eu e eoo ede ori ve egt eoe vega 121 10 8 Client async callback for specific entity ssssssee Hee 121 10 9 ChunkedInput exaniple 1 eR ieee Ries Bae a BICI Ru 122 13 T URE building doceret rte terr e om redet ror eR i rei EE dee doge 124 11 2 Building URIs using query parameters ssssee m HH eere 125 12 T A standard resource class c kei e edet et dan cokes eee Loreto edo er eoo sedet eth ined 128 12 2 A programmatic resoUrCe morren nr etr eaa ede h Pena pe ee peo EE Ear ie dose D pee e be rent 128 12 3 A programmatic resource z 074550 nde ete pes pn ex evo deep Suma eta Sea gebe eR eot o eo Abe d edis te tox pet 130 12 4 A programmatic TESOULCe i d eee e e ach eas E weds Sas tiag ee tee de PR eoe ee end 130 12 5 A progr mmiatiC TeSOUICel i dee dee eet esee be AEE dee Toti eex uova spere lee greed dnd 131 12 6 A programmatic resource ssssssssse III ee e hee hen ent ent ente nennen 132 13 1 Simple SSE resource method e eoo eerte eoe repo crt eee drop seen shor EERE A 137 13 2 Broadcasting SSE messages srono ene o aE nene me e ene EE tee tee mne nenne 140 13 3 Registering Event Listener with EventSource sesssssrssseresrreereresrreeerreresrreererereree 143
50. element In other words sub resource methods are grouped in WADL as sub resources based on their path value Configuration WADL generation is enabled in Jersey by default This means that OPTIONS methods are added by default to each resource and an auto generated application wadl resource is deployed too To override this default behavior and disable WADL generation in Jersey setup the configuration property in your application jersey config server wadl disableWadl true This property can be setup ina web xm1 if the Jersey application is deployed in the servlet with web xm1 or the property can be returned from the Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html get Properties See Deployment chapter for more information on setting the application configuration properties in various deployments WADL support in Jersey is implemented via ModelProcessor http jersey java net nonav apidocs snapshot jersey org glassfish jersey server model ModelProcessor html extension This implementation enhances the application resource model by adding the WADL providing resources WADL ModelProcessor priority value is high i e the priority is low as it should be executed as one of the last model processors Therefore any ModelProcessor executed before will not see WADL extensions in the resource model WADL handling resource model extensions resources and OPTIONS resource methods are not added
51. etc to make the produced response concise but complete at the same time Clients are then able to query all the additional information they are interested in and are not forced to consume details they are not interested in At the same time this approach relieves the server resources as only the information that is truly requested is being served to the clients A Link can be serialized to an HTTP message tyically a response as additional HTTP header there might be multiple Link headers provided thus multiple links can be served in a single message Such HTTP header may look like Link lt http example com TheBook chapter2 gt rel prev title previous chapter Producing and consuming Links with JAX RS API is demonstrated in the following example server side adding links to a response Response r Response ok link http oracle com parent link new URI http jersey java net framework build client side processing final Response response target request get URI u response getLink parent getUri URI u response getLink framework getUri Instances of Link can be also created directly by invoking one of the factory methods on the Link http jax rs spec java net nonav 2 0 apidocs javax ws rs core Link html API that returns a Link Builder http jax rs spec java net nonav 2 0 apidocs javax ws rs core Link Builder html that can be used to configure and produc
52. example XmlRootElement public class JaxbBean private String value public JaxbBean public JaxbBean final String value this value value public String getValue return value public void setValue final String value this value value When you send a GET request with Accept header set to application javascript youll get a result entity that look like callback value jsonp There are of course ways to configure wrapping method of the returned entity which defaults to callback as you can see in the previous example JSONP has two parameters that can be configured callback and queryParam callback stands for the name of the JavaScript callback function defined by the application The second parameter queryParam defines the name of the query parameter holding the name of the callback function to be used if present in the request Value of queryParam defaults to callback so even if you do not set the name of the query parameter yourself client can always affect the result name of the wrapping JavaScript callback method Note queryParam value if set always takes precedence over callback value Lets modify our example a little bit Example 8 28 Example of JSONP with configured parameters GET Produces application json application javascript JSONP callback eval queryParam jsonpCallback public JaxbBean getSimpleJSONP return new JaxbBean j
53. for more information 12 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 RS 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 131 Programmatic API for ds Building Resources 2 import javax ws rs GET Example 12 6 A programmd tieceso rcex ws rs Path 4 import javax ws rs Produces 2 import javax ws rs container ContainerRequestContext 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
54. form data name hello hello Boundary 1 511262261 1369143433608 Content Type application xml Content Disposition form data name 2 xml lt xml version 1 0 encoding UTF 8 standalone yes gt lt jaxbBean gt lt value gt xml lt value Boundary 1 511262261 1369143433608 Content Type application json Content Disposition form data name json value json Boundary 1 511262261 1369143433608 A common use case for many users is sending files from client to server For this purpose you can use classes from org glassfish jersey jersey media multipart package such as FileDataBodyPart http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart file FileDataBodyPart html or StreamDataBodyPart http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart file StreamDataBodyPart html 98 Support for Common Media Type Representations Example 8 46 Multipart sending files MediaType of the body part will be derived from the file final FileDataBodyPart filePart new FileDataBodyPart my pom new File pom xml final FormDataMultiPart multipart new FormDataMultiPart field foo bar bodyPart filePart final WebTarget target Create WebTarget final Response response target request post Entity entity multipart multipart getMediaType 8 3 3 Server Returning a multipart response from server to client is not
55. http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientBuilder html factory methods Here s the most simple example Client client ClientBuilder newClient The ClientBuilder is a JAX RS API used to create new instances of Client In a slightly more advanced scenarios ClientBuilder can be used to configure additional client instance properties such as a SSL transport settings if needed see below A Client instance can be configured during creation by passing a ClientConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientConfig html to the newClient Configurable ClientBuilder factory method ClientConfig _ http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientConfig html implements Configurable http jax rs spec java net nonav 2 0 apidocs Javax ws rs core Configurable html and therefore it offers methods to register providers e g features or individual entity providers filters or interceptors and setup properties The following code shows a registration of custom client filters 47 Client API ClientConfig clientConfig new ClientConfig clientConfig register MyClientResponseFilter class clientConfig register new AnotherClientFilter Client client ClientBuilder newClient clientConfig 4 WDN FP In the example filters are registered using the ClientConfig register method There are multip
56. in Section 1 1 Creating a New Project from Maven Archetype In addition to the Grizzly based archetype Jersey provides also a Maven arcehtype for creating web application skeletons To create the new web application skeleton project execute the following Maven command in the directory where the new project should reside mvn archetype generat DarchetypeArtifactId jersey quickstart webapp DarchetypeGroupId org glassfish jersey archetypes DinteractiveMo DgroupId com exampl DartifactId simple service webapp Dpackage DarchetypeVersion 2 1 As with the Grizzly based project feel free to adjust the groupId package and or artifactId of your new web application project Alternatively you can change it by updating the new project pom xml once it gets generated Once the project generation from a Jersey maven archetype is successfully finished you should see the new simple service webapp project directory created in your current location The directory contains a standard Maven project structure similar to the simple service project content we have seen earlier except it is extended with an additional web application specific content Project build and management configuration is described in the pom xml located in the project root directory Project sources are located under src main java Project resources are located under src main resources Project web application files are located under src main webapp The proj
57. in the reverse order using descending manner so a provider with the priority defined with GPriority 2000 will be executed before another provider with priority defined with Priority 1000 Its a good practice to assign a priority to filters and interceptors Use Priorities http jax rs spec java net nonav 2 0 apidocs javax ws rs Priorities html class which defines standardized priorities in JAX RS for different usages rather than inventing your own priorities So when you for example write an authentication filter you would assign a priority 1000 which is the value of Priorities AUTHENTICATION The following example shows the filter from the beginning of this chapter with a priority assigned Example 9 9 Priorities example a 2 import javax annotation Priority 3 import javax ws rs Priorities 4 2 6 GPriority Priorities HEADER DECORATOR 7 public class ResponseFilter implements ContainerResponseFilter 8 9 Override 10 public void filter ContainerRequestContext requestContext 11 ContainerResponseContext responseContext 12 throws IOException 13 14 responseContext getHeaders add X Powered By Jersey 15 16 As this is aresponse filter and response filters are executed in the reverse order any other filter with priority lower than 3000 Priorities HEADER_DECORATOR is 3000 will be executed after this filter So for example AUTHENTICATION filter priority 1000 would be run aft
58. information 12 3 Additional examples Example 12 4 A programmatic resource final Resource Builder resourceBuilder Resource builder resourceBuilder addMethod OPTIONS handledBy new Inflector ContainerRequestContext Resp Override public Response apply ContainerRequestContext cont return Response ok This is a response to an O final Resource resource resourceBuilder build r20 w0 10014 0 Ph EH RoR In the example above the Resource is built from a HelloWorldResource resource class The resource 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 He110WorldResource 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 O apidocs javax ws rs core Response html The following sample shows how to define sub resource methods methods that contains sub path 130 Programmatic API for Building Resources Example 12 5 A programmatic resource final Resource Builder resourceBuilder Resource builder final Resource Builder childResource resourceBuilder add childResource addMethod GET handledBy new GetInflector
59. jax rs spec java net nonav 2 0 apidocs javax ws rs Consumes html annotation to the method The resource method postMyBean is annotated with Consumes application xml therefore for purpose of de serialization of entity for the postMyBean method only requests with entities represented as application xml media type will match the method However this method might be executed for for entity types that are sub classes or super classes of the declared generic type on the MessageBodyReader T will be also considered It is a responsibility of the isReadable method to decide whether it is able to de serialize the entity and type comparison is one of the basic decision steps Tip In order to reduce number of isReadable executions always define correctly the consumable media type s with the Consumes annotation on your custom MessageBodyReader T 7 2 2 2 MessageBodyReader readFrom The readForm method gets the parameters with the same meaning as in isReadable The additional ent it ySt ream parameter provides a handle to the entity input stream from which the entity bytes should be read and de serialized into a Java entity which is then returned from the method Our MyBeanMessageBodyReader de serializes the incoming XML data into an instance of MyBean using JAXB Important Do not close the entity input stream in your MessageBodyReader T implementation The stream will be automatically closed by Jersey runtime
60. jsp provided there exists a com 0oo Foo index jsp JSP page in the web application Jersey will assign the model instance to the attribute named it So in the case of the implicit example it is possible to referece the foo property on the Foo resource from the JSP template as follows lt h1 gt S it foo lt h1 gt 17 5 Custom Templating Engines To add support for other custom templating engines into Jersey MVC Templating facility you need to implement the TemplateProcessor http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc TemplateProcessor html and register this class into your application Tip When writing template processors it is recommend that you use an appropriate unique suffix for the processable template references In such case it is then possible to easily support mixing of multiple templating engines in a single application without any conflicts Example 17 8 Custom TemplateProcessor http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc TemplateProcessor html Provider class MyTemplateProcessor implements TemplateProcessor lt String gt Override public String resolve String path final MediaType mediaType final String extension testp if path endsWith extension path path extension final URL u this getClass getResource path return u null null path QOverride public void writeTo String tem
61. loader Example 8 35 PlanetJAXBContextProvider 1 Provider 2 public class PlanetJAXBContextProvider implements ContextResolver lt JAXBContext gt 3 private JAXBContext context null 4 2 public JAXBContext getContext Class lt gt type 6 if type Planet class g return null we don t support nothing else than Planet 8 9 10 if context null 11 try 12 context JAXBContext newInstance Planet class 13 catch JAXBException e 14 log warning error null will be returned which indicates th 15 provider won t can t be used 16 17 18 19 return context 20 BAT Sample above shows simple JAXBCont ext creation all you need to do is put this GP rovider annotated class somewhere where Jersey can find it Users sometimes have problems with using provider classes on client side so just to reminder you have to declare them in the client config client does not do anything like package scanning done by server 94 Support for Common Media Type Representations Example 8 36 Using Provider with JAX RS client 1 2 ClientConfig config new ClientConfig 3 config register PlanetJAXBContextProvider class 4 5 Client client ClientBuilder newClient config 6 8 2 5 MOXy If you want to use MOXy http www eclipse org eclipselink moxy php as your JAXB implementation instead of JAXB RI you have two options You can either use the standard JAXB mechanisms to
62. localhost 8080 May 26 2013 8 08 45 PM org glassfish grizzly http server HttpServer start INFO HttpServer Started Jersey app started with WADL available at http localhost 8080 myapp application Hit enter to stop it This informs you that the application has been started and it s WADL descriptor is available at http localhost 8080 myapp application wadl URL You can retrieve the WADL content by executing a curl http localhost 8080 myapp application wadl command in your console or by typing the WADL URL into your favorite browser You should get back an XML document in describing your deployed RESTful application in a WADL format To learn more about working with WADL check the Chapter 15 WADL Support chapter The last thing we should try before concluding this section is to see if we can communicate with our resource deployed at myresource path We can again either type the resource URL in the browser or we can use curl curl http localhost 8080 myapp myresource Got it As we can see the curl command returned with the Got it message that was sent by our resource We can also ask curl to provide more information about the response for example we can let it display all response headers by using the i switch curl i http localhost 8080 myapp myresource HTTP 1 1 200 OK Content Type text plain Date Sun 26 May 2013 18 27 19 GMT Content Length 7 Got it Here we see the whole content of the response
63. message that our Jersey JAX RS application returned including all the HTTP headers Notice the Content Type text plain header that was derived from the value of Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation attached to the MyResource class In case you want to see even more details about the communication between our cur1 client and our resource running on Jersey in a Grizzly I O container feel free to try other various options and switches Getting Started that cur 1 provides For example this last command will make cur1 output a lot of additional information about the whole communication curl v http localhost 8080 myapp myresource About to connect to localhost port 8080 0 i Trying i Leus Connection refused Trying 127 0 0 1 connected Connected to localhost 127 0 0 1 port 8080 0 gt GET myapp myresource HTTP 1 1 gt User Agent curl 7 25 0 x86 64 apple darwinl11 3 0 libcurl 7 25 0 OpenSSL 1 0 1 gt Host localhost 8080 gt Accept gt lt HTTP 1 1 200 OK lt Content Type text plain lt Date Sun 26 May 2013 18 29 18 GMT lt Content Length 7 lt Connection 0 to host localhost left intact Got it Closing connection 0 1 4 Creating a JavaEE Web Application To create a Web Application that can be packaged as WAR and deployed in a Servlet container follow a similar process to the one described
64. one can be found in the JavaDoc of Viewable http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc Viewable html class which in our case is com foo Foo index Jersey will then search all the registered template processors see Section 17 5 Custom Templating Engines to find a template processor that can resolve the absolute template reference further to a processable template reference If a template processor is found then the processable template is processed using the supplied data model Let s change the resource GET method in our Foo resource a little 176 MVC Templates Example 17 6 Using absolute path to template in Viewable GET public Viewable get return new Viewable index FOO In this case since the template reference begins with Jersey will consider the reference to be absolute already and will not attempt to absolutize it again The reference will be used as is when resolving it to a processable template reference as described earlier Tip All HTTP methods may return Viewable instances Thus a POST method may return a template reference to a template that produces a view that is the result of processing an HTML Form http jax rs spec java net nonav 2 0 apidocs javax ws rs core Form html 17 3 2 Template Implicit View Templates 17 3 2 1 Resource classes A resource class can have templates implicitly associated with it vi
65. path item locator or even for only item 33 JAX RS Application Resources and Sub Resources 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 GPath item 2 public class ItemResource 3 4 Path 5 public Object getItemContentResource 6 return new AnyResource 8 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 import javax inject Singleton 1 2 3 Path item 4 public class ItemResource 5 Path content 6 public Class lt ItemContentSingletonResource gt getItemContentResource 7 return ItemContentSingletonResource class 8 9 10 11 Singleton 12 public class ItemContentSingleton
66. returned similar to this one 152 WADL Support Example 15 3 OPTIONS method returning WADL 1 lt xml version 1 0 encoding UTF 8 standalone yes gt 2 application xmlns http wadl dev java net 2009 02 3 doc xmlns jersey http jersey java net 4 jersey generatedBy Jersey 2 0 SNAPSHOT buildNumber gt 5 lt grammars gt 6 lt resources base http localhost 9998 gt 7 lt resource path country 15 gt 8 lt method name GET id getCountry gt 9 lt response gt 10 representation mediaType application xml ET lt response gt T2 lt method gt T3 lt method name OPTIONS id apply gt 14 lt request gt 15 lt representation mediaType gt 16 lt request gt 17 lt response gt 18 representation mediaType application vnd sun wadl txml 19 lt response gt 20 lt method gt 21 lt method name OPTIONS id apply gt 22 lt request gt 23 lt representation mediaType gt 24 lt request gt 29 lt response gt 26 lt representation mediaType text plain gt 27 lt response gt 28 lt method gt 29 lt method name OPTIONS id apply gt 30 lt request gt 31 lt representation mediaType gt 32 lt request gt 33 lt response gt 34 lt representation mediaType gt 35 lt response gt 36 lt method gt 37 lt resource gt 38 lt resources gt 39 lt application gt The returned WADL document has the standard WADL s
67. root in our case represented by the webTarget instance while allowing for further configuration specialization based on the specific requirements of each individual resource The same configuration principles of inheritance to allow common config propagation and decoupling to allow individual config customization applies to all components in JAX RS Client API discussed below Lets say there is a sub resource on the path http example com rest resource helloworld You can derive a WebTarget for this resource simply by 1 WebTarget helloworldWebTarget resourceWebTarget path helloworld Let s assume that the helloworld resource accepts a query param for GET requests which defines the greeting message The next code snippet shows a code that creates a new WebTarget with the query param defined 49 Client API 5 3 5 1 WebTarget helloworldWebTargetWithQueryParam 2 helloworldWebTarget queryParam greeting Hi World Please note that apart from methods that can derive new WebTarget instance based on a URI path or query parameters the JAX RS WebTarget API contains also methods for working with matrix parameters too Invoking a HTTP request Let s now focus on invoking a GET HTTP request on the created web targets To start building a new HTTP request invocation we need to create a new Invocation Builder http jax rs spec java net nonav 2 0 apidocs Javax ws rs client Invocation Builder html
68. says that the method is wrapping the writing of the entity The method aroundWriteTo gets WriterInterceptorContext as a parameter This context contains getters and setters for header parameters request properties entity entity stream and other properties These are the properties which will be passed to the final MessageBodyWriter lt T gt Interceptors are allowed to modify all these properties This could influence writing of an entity by MessageBodyWriter lt T gt and even selection of such a writer By changing media type WriterInterceptorContext setMediaType the interceptor can cause that different message body writer will be chosen The interceptor can also completely replace the entity if itis needed However for modification of headers request properties and such the filters are usually more preferable choice Interceptors are executed only when there is any entity and when the entity is to be written So when you always want to add a new header to a response no matter what use filters as interceptors might not be executed when no entity is present Interceptors should modify properties only for entity serialization and deserialization purposes Let s now look at an example of aWriterInterceptor 106 Filters and Interceptors Example 9 6 GZIP reader interceptor public class GZIPReaderInterceptor implements ReaderInterceptor de 2 3 Override 4 public Object aroundReadFrom ReaderInterceptorContext context
69. server side and the client side Server filters ContainerRequestFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerRequestFilter html ContainerResponseFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerResponseFilter html Client filters ClientResponseFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientResponseFilter html ClientResponseFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientResponseFilter html 9 2 1 Server filters The following example shows a simple container response filter adding a header to each response Example 9 1 Container response filter import java io IOException import javax ws rs container ContainerRequestContext import javax ws rs container ContainerResponseContext import javax ws rs container ContainerResponseFilter import javax ws rs core Response public class PoweredByResponseFilter implements ContainerResponseFilter OANA 01 C0 For o Override public void filter ContainerRequestContext requestContext ContainerRespon throws IOException PRP NRO p w responseContext getHeaders add X Powered By Jersey ere ous uu ds 102 Filters and Interceptors In the example above the PoweredByResponseFilter always adds a header X Powered By to the response The filter must inherit from the
70. seryer iore e EU Creo ree Og REP Shel a e ERNEST 146 14 1 1 SCCULILY COMLEX ese ides eens cease sy ced tes Seeds Sedan gee vy stmece sy nodees ph Suede E ER ERE 146 14 1 2 Authorization securing resources 2 2 0 0 ee eee eee ee Hee 147 14 2 Chent Security x nd ciet er sa E ns ier eitee eedem dd 149 TAS OADtB ut ose AIhtem nS IE EUR m aen 149 15 WADE SUDDOELU cod tee dose en oret dosh eoe Oo rte acenyeed tee ro ep EON Re PP ER TE Per est 150 15 T WADE introduction s eoe eo C ER eec ee Ev deer ape ees 150 1522 Comme uration P EH 157 15 3 Extended WADL s pport rr reto etre Ene tet E EENS 158 16 Bean Validation Suppoft erroe ie eere eoe eee de an cor e este eR OOo mec d ee ox Pope rene 159 16 1 Bean Validation Dependencies 2 0 2 0 cece cece eee cn HH 159 16 2 Enabling Bean Validation in Jersey eese 159 16 3 Configuring Bean Validation Support sese 160 16 4 Validating JAX RS resources and methods sse eeea seen sean eeaes 163 16 4 1 Constraint Annotations 2 0 0 0 eee cence E RT TEE hen entente 163 16 4 2 Annotation constraints and Validators ss A 165 16 4 3 Entity Validation 4 ierit pner 165 16 44 Annotation Inheritance iere eee pred o Ene crees onvedes 167 16 5 e VahdateOnEXecution xe erre e de i es testi erre ures eee es ges 167 16 6 Injecting eee deseo ene deste at vede eie tee ee iden ede bee dus t
71. spec java net nonav 2 0 apidocs javax ws rs core Configurable html client server Example 8 23 ContextResolver lt ObjectMapper gt Provider and a public class JaxbContextResolver implements ContextResolver lt JAXBContext gt private final JAXBContext context private final Set lt Class lt gt gt types private final Class lt gt cTypes Flights class FlightType class AircraftTy public JaxbContextResolver throws Exception this types new HashSet lt Class lt gt gt Arrays asList cTypes this context new JettisonJaxbContext JettisonConfig D Override public JAXBContext getContext Class lt gt objectType return types contains objectType context null Example 8 24 Building client with Jettison JSON feature enabled final Client client ClientBuilder newBuilder p P FAULT cTypes register JaxbContextResolver class No need to register this provider register JettisonFeature class build 87 Support for Common Media Type Representations Example 8 25 Creating JAX RS application with Jettison JSON feature enabled Create JAX RS application final Application application new ResourceConfig packages org glassfish jersey examples jettison register JaxbContextResolver class No need to register this provider register JettisonFeature class 8 1 5 4 Examples 8 1 6 Jersey provides an JSON Jettison example htt
72. the Feature Auto discovery mechanism WadlFeature http jersey java net nonav apidocs snapshot jersey org glassfish Jersey server wadl WadlFeature html enables WADL processing UriConnegFilter http jersey java net nonav apidocs snapshot jersey org glassfish jersey server filter UriConnegFilter html a URI based content negotiation filter Note Auto discovery functionality is in Jersey supported by implementing an internal SPI AutoDiscoverable interface This interface is not public at the moment so be careful when using it 4 1 1 Configuring the Feature Auto discovery mechanism The auto discovery of features in Jersey that is enabled by default can be disabled by using special common server client properties Common auto discovery properties CommonProperties FEATURE AUTO DISCOVERY DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE Disables auto discovery globally on client server CommonProperties JSSON PROCESSING FEATURE DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey CommonProperties html JSON_PROCESSING_FEATURE_DISABLE Disables configuration of Json Processing JSR 353 feature CommonProperties MOXY_JSON_FEATURE_ DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey CommonProperties html MOXY_JSON_FEATURE_DISABLE Disables configuration of MOXy Jso
73. the invoked get method the responseFuture get is invoked which waits for the response to be finished this call is blocking as defined by the Java SE Future contract Asynchronous Client API in JAX RS is fully integrated in the fluent JAX RS Client API flow so that the async client side invocations can be written fluently just like in the following example Example 10 6 Simple client fluent async invocation 1 final Future lt Response gt responseFuture target path http example com reso 2 request async get To work with asynchronous results on the client side all standard Future API facilities can be used For example you can use the isDone method to determine whether a response has finished to avoid the use of a blocking call to Future get 10 2 1 Asynchronous Client Callbacks Similarly to the server side in the client API you can register asynchronous callbacks too You can use these callbacks to be notified when a response arrives instead of waiting for the response on Future get or checking the status by Future isDone ina loop A client side asynchronous invocation callback can be registered as shown in the following example 120 Asynchronous Services and Clients Example 10 7 Client async callback 1 final Future lt Response gt responseFuture target path http example com reso 2 request async get new InvocationCallback Response 3 Override 4 publi
74. to authenticate to servers which requires HTTP Basic Authentication Use HttpBasicAuthFilter http jersey java net nonav apidocs snapshot jersey org glassfish jersey client filter HttpBasicAuthFilter html to add authentication header to requests initiated from from the client See the example of how to configure and register the filter 1 client register new HttpBasicAuthFilter Homer SecretPassword 55 Chapter 6 Representations and Responses 6 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 annotations referred to media type of an entity representation Examples above depicted resource methods that could consume and or produce String Java type for a number of different media types This approach is easy to understand and relatively straightforward when applied to simple use cases To cover also other cases handling non textual data for example or handling data stored in the file system etc JAX RS implementations are required to support also other kinds of media type conversions where additional non String Java types are being utilized Following is a short listing of the Java types that are supported out of the box with respect to supported media type e All media types e byte java lang String java io Reader inbound onl
75. to receive more messages it would have to send a new request to the server to initiate a new SSE streaming connection A client connecting to our SSE enabled resource will receive the following data from the entity stream vent message to client data Hello world 0 vent message to client data Hello world 1 138 Server Sent Events SSE Support vent message to client data Hello world 2 vent message to client data Hello world 3 vent message to client data Hello world 4 vent message to client data Hello world 5 vent message to client data Hello world 6 vent message to client data Hello world 7 vent message to client data Hello world 8 vent message to client data Hello world 9 Each message is received with a delay of one second 13 4 2 Broadcasting with Jersey SSE Jersey SSE server API defines SseBroadcaster http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse SseBroadcaster html which allows to broadcast individual events to multiple clients A simple broadcasting implementation is shown in the following example 139 Server Sent Events SSE Support Example 13 2 Broadcasting SSE messages l oh 2 import org glassfish jersey media sse SseBroadcaster 3 4 5 Singleton 6 Path broadcast 7 public stati
76. to the application resource model if there is already a matching resource or a resource method detected in the model In other words if you define for example your own OPTIONS method that would produce application wadl response content this method will not be overridden by WADL model processor See Resource builder chapter for more information on ModelProcessor extension mechanism 157 WADL Support 15 3 Extended WADL support Please note that the API of extended WADL support is going to be changed in one of the future releases of Jersey 2 x see below Jersey supports extension of WADL generation called extended WADL Using the extended WADL support you can enhance the generated WADL document with additional information such as resource method javadoc based documentation of your REST APIs adding general documentation adding external grammar support or adding any custom WADL extension information The documentation of the existing extended WADL can be found here Extended WADL in Jersey 1 https wikis oracle com display Jersey WADL This contains description of an extended WADL generation in Jersey 1 x that is currently supported also by Jersey 2 x Again note that the extended WADL in Jersey 2 x is NOT the intended final version and API is going to be changed The existing set of features and functionality will be preserved but the APIs will be significantly re designed to support additional use cases This impacts mainly t
77. to the client immediately as they become available without waiting for the remaining chunks to become available too The first bytes of each chunked response consists of the HTTP headers that are sent to the client The size 1 is set in the response Content Length header to indicate that the response is chunked As noted above the entity of the response is then sent in chunks as they become available Client knows that the response is going to be chunked so it reads each chunk of the response separately processes it and waits for more chunks to arrive on the same connection After some time the server generates another response chunk and send it again to the client Server keeps on sending response chunks until it closes the connection after sending the last chunk when the response processing is finished In Jersey you can use ChunkedOutput http jersey java net nonav apidocs snapshot Jersey org glassfish jersey server ChunkedOuptut html to send response to a client in chunks Chunks are strictly defined pieces of a response body can be marshalled as a separate entities using Jersey JAX RS MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWiriter html providers A chunk can be String Long or JAXB bean serialized to XML or JSON or any other dacustom type for which a MessageBodyWriter lt T gt is available The resource method that returns ChunkedOutput informs the Jersey runtime that the respon
78. 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 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 note that processSubResource ResourceModel subResourceModel Configuration configuration methodis executed for each sub resource returned from the sub res
79. would have to be written to make it easy to reuse the logic when communicating with the same resource http localhost 8080 resource that is represented by the JAX RS WebTarget instance in our example 5 3 Overview of the Client API 5 3 1 Getting started with the client API 5 3 2 Refer to the dependencies for details on the dependencies when using the Jersey JAX RS Client support You may also want to use a custom Connector http jersey java net nonav apidocs snapshot jersey org glassfish jersey client spi Connector html implementation In such case you would need to include additional dependencies on the module s containing the custom client connector that you want to use See section Configuring custom Connectors about how to use and configure a custom Jersey client transport Connector Creating and configuring a Client instance JAX RS Client API is a designed to allow fluent programming model This means a construction of a Client instance from which a WebTarget is created from which a request Invocation http jax rs spec java net nonav 2 0 apidocs javax ws rs client Invocation html is built and invoked can be chained in a single flow of invocations The individual steps of the flow will be shown in the following sections To utilize the client API it is first necessary to build an instance of a Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html using one of the static ClientBuilder
80. 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 20 1 Server API Jersey 1 x contains number of proprietary server APIs This section covers migration of application code relying on those APIs 20 1 1 Injecting custom objects Jersey 1 x have its own internal dependency injection framework which handles injecting various parameters into field or methods It also provides a way how to register custom injection provider in Singleton or PerRequest scopes Jersey 2 x uses HK2 as dependency injection framework and users are also able to register custom classes or instances to be injected in various scopes Main difference in Jersey 2 x is that you don t need to create special classes or providers for this task everything should be achievable using HK2 API Custom injectables can be registered at ResourceConfig level by adding new HK2 Module or by dynamically adding binding almost anywhere using injected HK2 Services instance Jersey 1 x Singleton ResourceConfig resourceConfig new DefaultResourceConfig resourceConfig getSingletons add new SingletonTypeInjectableProvider lt Context SingletonType gt SingletonType class new SingletonType Jersey 1 x PerRequest ResourceConfig resourceConfig new DefaultResourceConfig resourceConfig getSingletons add new PerRequestTypeInjectableProvider Context PerRequestType gt Override public Inj
81. 13 4 Overriding EventSource onEvent InboundEvent method seessssss 144 14 1 Accessing Sec rdityCOnteXb nonet decer eter ree Meteor see come cose tero 146 14 2 Injecting SecurityContext into a singleton resource esse ceeeee esse teen es 146 14 3 Injecting SecurityContext into singletons 2 0 0 eee ce ee ce tece IH 147 14 4 Registering RolesAllowedDynamicFeature using ResourceConfig esee 148 14 5 Injecting SecurityContext into singletons eesesee IH 148 15 1 A simple WADL example JAX RS resource definition see 150 15 2 A simple WADL example WADL content 0 00 00 cece cece cece Hem eme 151 15 3 OPTIONS method returning WADL 1 00 0 eee cence HH HH HI III emere 153 15 4 More complex WADL example JAX RS resource definition eeeeeeee 154 15 5 More complex WADL example WADL content eseeee Hm 156 16 1 Configuring Jersey specific properties for Bean Validation eeeee 160 16 2 Using ValidationConfig to configure Validator eeseseee eect eeeeeees 162 16 3 Constraint annotations on input parameters cssessesee HH eme 163 16 4 Constraint annotations on fields sess eere 164 16 5 Constraint annotations on Clas Seisoene eera Er me e eem ente mee men hen nenne 164 16 6 Definition of a constraint annotation 2 2 0 0 cece eee cc cece ence III eee herren 165 16 7 Valid
82. 18 return Color f get null getRGB 19 catch Exception e 20 throw new WebApplicationException 400 21 22 23 24 In general the Java type of the method parameter may 1 Be a primitive type 2 Have a constructor that accepts a single St ring argument 3 Have a static method named valueOf or fromString that accepts a single String argument see for example Integer valueOf String and java util UUID fromString String 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 T Set lt T gt or SortedSet T 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 forList Set or SortedSet null for other object types and the Java defined default for primitive types The PathParam http jax rs spec java net nonav 2 O apidocs javax ws rs PathParam html and the other parameter based
83. 2 How to Write Custom Entity Providers ssesssssse eee 62 7 2 1 MessageBodyWRtet exes ooi ote eere eese Dor Rer ee IEEE sony 63 7 272 MessageBodyReader vss e e CREE eS e en S e nsade eae 67 7 3 Entity Provider Selection eo iecit mie bett eei e deste Sex terc N 69 7 4 Jersey MessageBodyWorkers API ssessseseeeee e m ee mener 72 7 5 Default Jersey Entity Providers ecce cro ertet erre oer cedro Ens 74 8 Support for Common Media Type Representations 2 0 0 0 cece ce eece ence IH 75 ORIG ATE 75 8 1 1 Approaches to JSON Support sese 75 Sil MOXY ER 78 8 1 3 Java API for JSON Processing JSON P ssssssseee 81 81 4 Jackson 52e ettet tet n tee eR hes Pub saet EE bee eb ent ek t oe edid eR o tes 82 81 5 Jettison sno OU BENI Rma WIS oes 84 8 1 6 QGJSONP JSON with Padding Support sssse cece een eene eens 88 8 2 XME 5 e Nave Aion ol ees d D eae eda een asad ex T s e deeds reek ER T EAS 90 8 221 Low level XME Support deesset text cete cure De Geet o eene NEE a OREe FORES 90 8 2 2 Getting started with JAXB sss emen ene 91 8 2 34 POJOS Rs 93 8 2 4 Using custom JAXBContext irnir nnn E e I em emere 94 8 25 MOXY o ise tese fexta deos den evt dese cot ient et haa dew egnabas Sot dete teo doe tSv bo dienes 95 8 3 Multipart 5 uv REO EID een vec ile e EI A 96 8 3 15 OVERVIEW acc 96 8 3 2 Client 3 itx tS
84. 3 exampleid 2 4 name Bob 2 addresses 6 street Long Street 1 7 town Short Village 8 9 10 Please note that id item became example id based on the XML namespace mapping If you have more XML namespaces in your XML you will need to configure appropriate mapping for all of them 8 1 5 2 2 Badgerfish notation From JSON and JavaScript perspective this notation is definitely the worst readable one You will probably not want to use it unless you need to make sure your JAXB beans could be flawlessly written and read back to and from JSON without bothering with any formatting configuration namespaces etc JettisonConfig instance using badgerfish notation could be built with JettisonConfig badgerFish build and the JSON output JSON will be as follows 86 Support for Common Media Type Representations Example 8 22 JSON expression produced using badgerfish notation Ici 2 contact 1 3 dv 4 WE US MM 5 6 name 7 WS e Bob 8 9 addresses 10 street 11 S Long Street 1 12 13 town 14 S Short Village 15 16 17 18 8 1 5 3 Configure and register In order to use Jettison as your JSON JAXB POJO provider you need to register JettisonFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey jettison JettisonFeature html ContextResolver T for JAXBContext if needed in your Configurable http jax rs
85. 3 1 Root Resource Classes 2 escoger entere asec OS EEEn eE e IEE ET EES 23 3 1 1 Path iiir Roi Pep EH ERR Pr err eS 23 3 1 2 GET PUT POST DELETE HTTP Methods 24 3 123 PrOdUCeS MEET 25 3 14 CONSUMES eise ete Ledger coh eos segete e E ET 26 3 2 Parameter Annotations Param ccececeec sence ec emen nemen eese e mere serene 27 3 3 SUD TESOUNCES vrnete Rn ee Ie eun ER UE ES E eerie 31 3 4 Life cycle of Root Resource Classes csiis onn iiaa HH emen 35 3 5 Rules otf Injection i 3 0 ife RA E E repere e eai E Inn 36 3 6 Use of CONTE ies cono e vt REEF E E REPRE 39 3 7 Programmatic resource model ssssessessese eem e mH meme enne 40 4 Deploying a RESTful Web Service screen Rte RR e RR ee epp aper rdg 41 4 1 Auto Discoverable Features 0 sess HI HH men e mee meer erenne 43 4 1 1 Configuring the Feature Auto discovery mechanism sees 44 5 Client APL ii user eei Ie entigcitee teste te eere ier 45 5 1 Uniform Interface Constraint ete petente tee per agre ceases ss Pres Tas 45 5 2 Ease of use and reusing JAX RS artifacts sssessessessee He 46 3 3 Overview of the Client API oss 5er tr Hed reed ehe RR ree ED ERR RR ERE 47 5 3 1 Getting started with the client API seseseeee HH 47 5 3 2 Creating and configuring a Client instance sse 47 5 3 3 Ta
86. 9 GET 10 public String get 11 return query param param 12 13 j 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 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 Htt pHeaders 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 Path resource 2 Singleton 3 public static class MySingletonResource 4 Context 5 Request request this is ok the proxy of Request will be injected into 6 7 public MySingletonResource GContext SecurityContext securityContext 8 this is ok too the proxy of SecurityContext will be injected 9 10 11 GET 12 public String get 13 return query param param 14 T5 To summ
87. AX RS Configurable API All methods for registration of filter or interceptor classes or instances can be used Such dynamically registered filters or interceptors will be bound only to the actual resource method In the example above the GZIPWriterInterceptor will 112 Filters and Interceptors be bound only to the method get VeryLongString which will cause that data will be compressed only for this method and not for the method get Hello The code of GZIPWriterInterceptor is in the examples above Note that filters and interceptors registered using dynamic binding are only additional filters run for the resource method If there are any name bound providers or global providers they will still be executed 9 7 Priorities In case you register more filters and interceptors you might want to define an exact order in which they should be invoked The order can be controlled by the Priority annotation defined by the javax annotation Priority class The annotation accepts an integer parameter of priority Providers used in request processing ContainerRequestFilter ClientRequestFilter ReaderInterceptors are sorted based on the priority in an ascending manner So a request filter with priority defined with Priority 1000 will be executed before another request filter with priority defined as Priority 2000 Providers used during response processing ContainerResponseFilter ClientResponseFilter WriterIntercepors are executed
88. BLE_VALIDATE_ON_EXECUTABLE OVERRIDE CHECK ServerProperties BV SEND ERRO amp r EN yRESPO NSEbeanValidEndables sendoige Validatiovadrictat ionErrorEnt http jersey java net nonav information to the client Default apidocs snapshot jersey org value is false glassfish jersey server ServerProperties html BV SEND ERROR IN RESPONSE ServerProperties FEATURE_AUT DISGOVERY DSARI e Au Dasables featurg agtexdrseovery on http jersey java net nonav server Default value is false apidocs snapshot jersey org glassfish jersey server ServerProperties html FEATURH_ AUTO DISCOVERY DISABLE ServerProperties HTTP METHOD 4Y ERBRH2Bfig server htjDefiatshodOvenfigurction of http jersey java net nonav HTTP method overriding apidocs snapshot jersey org This property is used by glassfish jersey server HttpMethodOverrideFilter http ServerProperties html HTTP_MHRTHOD_OVERRIDE jersey java net nonav apidocs snapshot jersey org glassfish jersey server filter HttpMethodOverrideFilter html to determine where it should look for method override information e g request header or query parameters ServerProperties JSON PROCESSIBN S FEATURE DISARI e J 3 Distiblese senfigurateanvef Json http jersey java net nonav Processing JSR 353 feature apidocs snapshot jersey org Default value is false glassfish jersey server ServerProperties html JSON_PROCESSING_FEATURE_DISABLE ServerPropert
89. ClassB class Classes to be bound 15 95 final ClassLoader classLoader Thread currentThread getContextClassLoader Support for Common Media Type Representations 8 3 Multipart 8 3 1 Overview The classes in this module provide an integration of mult ipart request and response bodies in a JAX RS runtime environment The set of registered providers is leveraged in that the content type for a body part of such a message reuses the same MessageBodyReader lt T gt MessageBodyWriter lt T gt implementations as would be used for that content type as a standalone entity The following list of general MIME MultiPart features is currently supported e The MIME Version 1 0 HTTP header is included on generated responses It is accepted but not required on processed requests A MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html implementation for consuming MIME MultiPart entities A MessageBodyWriter T implementation for producing MIME MultiPart entities The appropriate GP rovider is used to serialize each body part based on its media type e Optional creation of an appropriate boundary parameter on a generated Content Type header if not already present For more information refer to Multi Part http jersey java net nonav apidocs snapshot jersey org glassfish jersey media multipart package info html 8 3 1 1 Dependency To use mult
90. Coe RE ences ON Bec t etos dud 97 SRI Tp 99 9 Bilters and Interceptors ein ee roo i ee e eSI e He eee eect aerate 102 9 1 IntrodUcliOn 2 5 soot te rero Pec ee rero AE eS vet ee cto TE Desde du lon verbe see 102 PEPABOII RR mE ase 102 92 12 Server hlterss uoo ten bestiae eter ete Reste e n EA a oateniieekt estis 102 9 222 Chent hllers 35 5i Reads Secs La P I I TERR eke hh ei i Sty 105 9 3 Interceptors ae oec eee oe ette e EE Leber eum de EPA EE Peer UN EES 105 9 4 Filter and interceptor execution order ssssss Hee 107 9 5 Name bindmg nici te emunt inte dest cue doe queo eod atu rhe foo lee seen need 109 9 6 Dynamic binding 1 AR peer NE t E e E eerie pie eet 111 97 POLIS eare eoo pro treo sa Po ates endis ton oro exo b eode sth ene d o Eee EEEO EE 113 10 Asynchronous Services and Clients ssesssssss seca sean esas emm emm 114 10 T Asynchronous Server APE rensie t iuter te oet tire e cet desde eaten teet deseo 114 10 1 1 Asynchronous Server side Callbacks se sean eenes 116 10 1 2 Ch nked Qutput 9 rm ort oso ete exer eer tene E rir Ex depre gest 118 10 2 Chent API 5 vss EE Ee e tUe NE 120 10 2 1 Asynchronous Client Callbacks esee 120 10 2 2 Chunked inputs i5 oe Er et tU I RN E ties 122 Ws URIS and Ei CO 124 IT T Buildmg UR S SEP be e e A ee a ued ee pe eredi 124 11 2 Resolve and Relativize oos se
91. ContainerResponseFilter http jax rs spec java net nonav 2 0 apidocs Javax ws rs container ContainerResponseFilter html and must be registered as a provider The filter will be executed for every response which is in most cases after the resource method is executed Response filters are executed even if the resource method is not run for example when the resource method is not found and 404 Not found response code is returned by the Jersey runtime In this case the filter will be executed and will process the 404 response The filter method has two arguments the container request and container response The ContainerRequestContext http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerRequestContext html is accessible only for read only purposes as the filter is executed already in response phase The modifications can be done in the ContainerResponseContext http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerResponseContext html The following example shows the usage of a request filter Example 9 2 Container request filter 1 import java io IOException 2 import javax ws rs container ContainerRequestContext 3 import javax ws rs container ContainerRequestFilter 4 import javax ws rs core Response 5 import javax ws rs core SecurityContext 6 7 public class AuthorizationRequestFilter implements ContainerRequestFilter 8 9 Override 10 public void fil
92. Interceptor applies for changing these properties change only properties in order to influence reading of an entity 9 4 Filter and interceptor execution order Let s look closer at the context of execution of filters and interceptors The following steps describes scenario where a JAX RS client makes a POST request to the server The server receives an entity and sends a response back with the same entity GZIP reader and writer interceptors are registered on the client and the server Also filters are registered on client and server which change the headers of request and response 1 Client request invoked The POST request with attached entity is built on the client and invoked 2 ClientRequestFilters The ClientResponseFilters are executed on the client and they manipulate the request headers 3 Client WriterInterceptor As the request contains an entity writer interceptor registered on the client is executed before a MessageBodyWriter is executed It wraps the entity output stream with the GZipOutputStream 4 Client MessageBodyWriter message body writer is executed on the client which serializes the entity into the new GZipOutput stream This stream zips the data and sends it to the wire 5 Server server receives a request Data of entity is compressed which means that pure read from the entity input stream would return compressed data 6 Server pre matching ContainerRequestFilters ContainerRequestFilters are executed that
93. JAX RS application with MOXy JSON feature enabled Create JAX RS application final Application application new ResourceConfig packages org glassfish jersey examples jsonmoxy The line bellow that registers MOXy feature can be omitted if FEATURE AUTO DISCOVERY DISABLE is not disabled register MoxyJsonFeature class register JsonMoxyConfigurationContextResolver class 8 1 2 3 Examples Jersey provides an JSON MOXy example https github com jersey jersey tree master examples json moxy on how to use MOXy to consume produce JSON 8 1 3 Java API for JSON Processing JSON P 8 1 3 1 Dependency To use JSON P as your JSON provider you need to add jersey media json processing module to your pom xml file dependency groupId org glassfish jersey mediac groupId artifactId jersey media json processing artifactId version 2 1 version dependency If youre not using Maven make sure to have all needed dependencies see jersey media json processing __ https jersey java net project info 2 1 jersey project jersey media json processing dependencies html on the class path 8 1 3 2 Configure and register As stated in Section 4 1 Auto Discoverable Features JSON Processing media module is one of the modules where you don t need to explicitly register it s Features JsonProcessingFeature in your client server Configurable http jax rs spec java net no
94. Jersey 2 1 User Guide Jersey 2 1 User Guide Table of Contents Preface sette ar t be ioter Pre de sates ge T E aee Pi se Ee ERE ep se ec iuter tote ss A xii I Getting Started ree ee et p E IEEE INIRE E tes eee Ig 1 1 1 Creating a New Project from Maven Archetype ssessese eeeeeeeeeeeaees 1 1 2 Exploring the Newly Created Project 0c cece cece eeceeeceeecaeeea eme 1 1 3 Running the Project oct oet pe I e ERE EE E bak Peta eet tere Y 3 1 4 Creating a JavaEE Web Application 20 0 0 eee ceee cece cece HH mme 5 1 5 Exploring Other Jers y Examples etie entere reb ter PTRS eere 6 2 Mo dules and dependencies 1 2 erret ere yen rere ebay nuce e ETRAS TEE Eee gh 7 2 1 Java SE Compatibility e eee e e E Pete ER t E ER ete bau pantads stants 7 2 2 Introduction to Jersey dependencies sesssessesee Hee 7 2 3 Common Jersey Use Cases on reed erben red EE REESS ee dosi eh E ETERS 7 2 3 1 Servlet based application on Glassfish ss teen seen secu sean eeaes 7 2 3 2 Servlet based server side application ccc ceee cece eee ce eece ee 8 2 3 3 Client application on JDK vissi eninin e HH 8 2 3 4 Served side application on supported container cece eee ee eeceeece ener eeeee ee 9 244 Tast OF MOGUICS e o Dee See beste ias Deb loess eni Eie 9 3 JAX RS Application Resources and Sub Resources 2 0 0 0 cece cece nee e ee 23
95. JspMvcFeature new ResourceConfig register org glassfish jersey server mvc jsp JspMvcFeature class Further configuration of ResourceConfig register Important Jersey web applications that want to use MVC templating support feature should be registered as Servlet filters rather than Servlets in the application s web xm1 The web xm1 less deployment 174 MVC Templates style introduced in Servlet 3 0 is not supported at the moment for web applications that require use of Jersey MVC templating support Each of the three MVC modules contains a Properties e g FreemarkerMvcProperties file which defines a set of properties that could be set in a JAX RS Application ResourceConfig in order to take effect see the Example 17 3 Setting MvcProperties TEMPLATE_BASE_PATH value in ResourceConfig and Example 17 4 Setting FreemarkerMvcProperties TEMPLATE BASE PATH value in web xml Following list contains description of the available properties MvcProperties TEMPLATE BASE PATH jersey config server mvc templateBasepath The base path where templates are located FreemarkerMvcProperties TEMPLATE BASE PATH jJersey config server mvc templateBasepath freemarker The base path where Freemarker templates are located JspMvcProperties TEMPLATE BASE PATH jJersey config server mvc templateBasepath jsp The base path where JSP templ
96. MyResource 4 Context 5 Jersey will inject proxy of Security Context 6 SecurityContext securityContext 7 8 GET 9 public String getUserPrincipal 10 return securityContext getUserPrincipal getName 11 12 14 1 1 1 Initialize SecurityContext with Servlets As described above the SecurityContext by default if not overwritten by filters only offers information from an underlying container In the case you deploy a Jersey application in a Servlet 146 Security container you need to setup the security constraint auth constraint and user to roles mappings in order to pass correct information to the SecurityContext 14 1 1 2 SecurityContext in ContainerRequestContext The SecurityContext can be retrieved also from ContainerRequestContext http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerRequestContext html via getSecurityContext method You can also set the SecurityContext into the request using method setSecurityContext SecurityContext If you set a new SecurityContext in the ContainerRequestFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerRequestFilter html into the ContainerRequestContext then this security context will be used for injections in resource classes wrapped into the proxy This way you can implement a custom authentication filter that may setup your own SecurityContext to be used To ensure the early executio
97. ON data representations The biggest advantage of these low level APIs is that you will gain full control over the JSON format produced and consumed You will also be able to produce and consume very large JSON structures using streaming JSON parser generator APIs On the other hand dealing with your data model objects will probably be a lot more complex compared to the POJO or JAXB based binding approach Differences are depicted at the following code snippets Let s start with JAXB based approach Example 8 4 JAXB bean creation 1 MyJaxbBean myBean new MyJaxbBean Agamemnon 32 Above you construct a simple JAXB bean which could be written in JSON as name Agamemnon age 32 Now to build an equivalent JsonOb ject JSONOb ject in terms of resulting JSON expression you would need several more lines of code The following example illustrates how to construct the same JSON data using the standard Java EE 7 JSON Processing API Example 8 5 Constructing a JsonObject JSON Processing 1 JsonObject myObject Json createObjectBuilder 2 add name Agamemnon 3 add age 32 4 build And at last here s how the same work can be done with Jettison API 77 Support for Common Media Type Representations Example 8 6 Constructing a JSONObject Jettison 1 JSONObject myObject new JSONObject 2 try 3 myObject put name Agamemnon 4 myObject put age 32 5 catch
98. OUTBOUND _ cQN ENdoLENG EH BIERFER Agtintdgerf falne that defines the http jersey java net nonav buffer size used to buffer the apidocs snapshot jersey org outbound message entity in order glassfish jersey to determine its size and set CommonProperties html OUTBQUND_CONTENT_LENGTH_BU fikERplue of HTTP Content Length header Default value is 8192 A 2 Server configuration properties List of server configuration properties that can be found in ServerProperties http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html class 194 Configuration Properties Table A 2 List of server configuration properties Constant Value Description jersey config contentL4Aatintdgat falne shat wefines the buffer size used to buffer the outbound message entity in order to determine its size and set the value of HTTP Content Length header Default value is 8192 ServerProperties BV FEATURE DEYSBEEconfig beanValidBisables Bean Whkdateonvesipport http jersey java net nonav Default value is false apidocs snapshot jersey org glassfish jersey server ServerProperties html B V_FEATIUURE_DISABLE ServerProperties BV DISABLE VjiSEH2A TEcOIRSiBXECATIVSBEH BPS BRRIDEACHEGEKa1idateOnExecutableCI http jersey java net nonav ValidateOnExecution apidocs snapshot jersey org check Default value is false glassfish jersey server ServerProperties html B V_DISA
99. ObjectMapperProvider implements ContextResolver lt ObjectMapper gt 3 4 final ObjectMapper defaultObjectMapper 5 final ObjectMapper combinedObjectMapper 6 7 public MyObjectMapperProvider 8 defaultObjectMapper createDefaultMapper 9 combinedObjectMapper createCombinedObjectMapper 10 11 12 Override 1 3 public ObjectMapper getContext Class lt gt type 14 if type CombinedAnnotationBean class 15 return combinedObjectMapper 16 else T7 return defaultObjectMapper 18 19 20 21 private static ObjectMapper createDefaultMapper 22 final ObjectMapper result new ObjectMapper 23 result configure Feature INDENT OUTPUT true 24 2 5 return result 26 27 28 29 83 Support for Common Media Type Representations Example 8 15 Building client with Jackson JSON feature enabled 1 final Client client ClientBuilder newBuilder 2 register MyObjectMapperProvider class No need to register this p 3 register JacksonFeature class 4 build Example 8 16 Creating JAX RS application with Jackson JSON feature enabled 1 Create JAX RS application 2 final Application application new ResourceConfig 3 packages org glassfish jersey examples jackson 4 register MyObjectMapperProvider class No need to register this p 5 register JacksonFeature class 8 1 4 3 Examples Jersey provides an JSON Jackson example https github com jersey jersey tree
100. P2 OO xo 41 42 43 44 45 46 47 48 The Compress NameBinding Retention RetentionPolicy RUNTIM import j import j import j import javax import javax import javax import javax ws ws ws ws rs rs rs rs ava lang annotation Retention ava lang annotation RetentionPolicy ava util zip GZIPInputStream GET NameBinding Path Produces annotation is the name binding annotation GI public interface Compress Path helloworld public class HelloWorldResource GET Produces text plain public String getHello return GET Hello World Path too much data Compress public String getVeryLongString String str return str very long string interceptor will be executed only when resource methods annotated with Compress annotation will be executed Compress public class GZIPWriterInterceptor implements WriterInterceptor Override public void aroundWriteTo WriterInterceptorContext context throws IOException WebApplicationException final OutputStream outputStream context getOutputStream context setOutputStream new GZIPOutputStream outputStream context proceed example above defines a new Compress annotation which is a name binding annotation as it is annotated with NameBinding The Compress is applied on the resource method getVeryLongString
101. Resource 13 this class is managed in the singleton life cycle 14 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 34 JAX RS Application Resources and Sub Resources Example 3 22 Sub resource locators returning resource model 1 import org glassfish jersey server model Resource 2 3 Path item 4 public class ItemResource 5 6 Path content 7 public Resource getItemContentResource 8 return Resource from ItemContentSingletonResource class 9 10 The code above has exactly the same effect as previous example Resource is a resource simple resource constructed from ItemContentSingletonResource More complex programmatic resource can be returned as long they are valid resourc
102. Resource getItemContentResource uh return new ItemContentResource 8 9 10 GET ET Produces application xml 12 public Item get 13 14 15 16 public class ItemContentResource 17 18 GET 19 public Response get 20 21 PUT 22 Path version 23 public void put PathParam version int version 24 Context HttpHeaders headers 25 byte in 26 27 28 The root resource class ItemResource contains the sub resource locator method get ItemContentResource that returns a new resource class If the path of the request URL is item content then first of all the root resource will be matched then the sub resource locator will be matched and invoked which returns an instance of the ItemContentResource resource class Sub resource locators enable reuse of resource classes 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 GPath 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 GPath item 2 public class ItemResource 3 4 Path 5 public ItemContentResource getItemContentResource 6 return new ItemContentResource D 8 In the example above the sub resource locator method get ItemContentResource is matched for example for request
103. SAdNMhgrviteise http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html 4METAINF SERVICES_LOOKUP_DISABLE lookup on client Default value is false ClientProperties MOXY_JSON_HBATFBRE DISABEEdi sableMdBis bles configuration of MOXy http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html MOXY_JS ON_FEATURE_DISABLE Json feature Default value is false ClientProperties READ TIMEOU http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html READ_TIMEOUT lTersey config client reRdad me meout interval in milliseconds Default value is 0 infinity ClientProperties USE_LENCODINGersey config client ug amp iincatesing the http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html USE_ENCODING value of Content Encoding property the EncodingFilter http jersey java net nonav apidocs snapshot jersey org glassfish jersey client filter 198 dWorkaround Configuration Properties Constant Value Description EncodingFilter html should be adding Default value is not set 199
104. TestProperties CONTAINER_FACTORY http jersey java net nonav apidocs snapshot jersey org glassfish jersey test TestProperties html CONTAINER FACTORY has similar effect This way you may defer the decision on which containers you want to run your tests from the compile time to the test execution time Default implementation of Test ContainerFactory looks for container factories on classpath If more than one instance is found and there is a Grizzly test container factory among them it will be used if not a warning will be logged and the first found factory will be instantiated Following is a brief description of all containers supported in Jersey Test Framework Grizzly container can run as a light weight plain HTTP container Almost all Jersey tests are using Grizzly by default dependency groupId org glassfish jersey test framework providers groupId artifactld jersey test framework provider grizzly2 artifactlId version 2 1 version dependency n Memory container is not a real container It starts Jersey application and directly calls internal APIs to handle request created by client provided by test framework There is no network communication involved This containers does not support servlet and other container dependent features but it is a perfect choice for simple unit tests dependency groupId org glassfish jersey test framework providers groupId artifactld jersey test fra
105. X RS application with JSON Processing JSON feature enabled 82 8 14 ContextResolver ObjectMapper dne pene erre Ie re a vede nnb rdi 83 8 15 Building client with Jackson JSON feature enabled sseeeeA 84 8 16 Creating JAX RS application with Jackson JSON feature enabled esses 84 8 17 JAXB beans for JSON supported notations description simple address bean 85 8 18 JAXB beans for JSON supported notations description contact bean seeeeeeesss 85 8 19 JAXB beans for JSON supported notations description initialization eeeeeeeeee 85 8 20 XML namespace to JSON mapping configuration for Jettison based mapped notation 86 8 21 JSON expression with XML namespaces mapped into JSON 00 00 c cece ee ee teen eeee eee 86 8 22 JSON expression produced using badgerfish notation cece ce eece eect eter ence eee 87 8 23 ContextResolver lt Ob ject Mapper gt oie esse tes Mun E de ra de chee coat 87 8 24 Building client with Jettison JSON feature enabled sese 87 8 25 Creating JAX RS application with Jettison JSON feature enabled esses 88 8 26 Simplest case of using TSONP aisinn iee ai e E NE seca E EE mee ent ente meer eene 88 8 27 JaxbBean for JSONP example e cee cece cece nec a cece meme meme mH mH ener 89 8 28 Example of JSONP with config
106. _DISCOVERY_DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE e ServerProperties FEATURE AUTO DISCOVERY DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html FEATURE AUTO DISCOVERY DISABLE ServerProperties BV FEATURE DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html BV_FEATURE_DISABLE Note Jersey does not support Bean Validation on the client at the moment 16 3 Configuring Bean Validation Support Configuration of Bean Validation support in Jersey is twofold there are few specific properties that affects Jersey behaviour e g sending validation error entities to the client and then there is ValidationConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server validation V alidationConfig html class that configures Validator http docs jboss org hibernate beanvalidation spec 1 1 api javax validation Validator html used for validating resources in JAX RS application To configure Jersey specific behaviour you can use the following properties ServerProperties BV DISABLE VALIDIXAHIEs GN cEXHEUPABLIe OVERR I DikecKHMOkKe on this is http jersey java net nonav described in Section 16 5 ValidateOnExecution apidocs snapshot jersey org glassfish jersey server ServerProperties
107. _VALIDATE_ON_EXECUTABLE_OVERRIDE CHECK property Jersey specific to t rue 16 6 Injecting Jersey allows you to inject registered resources providers into your ConstraintValidator http docs jboss org hibernate beanvalidation spec 1 1 api javax validation ConstraintValidator html implementation and you can inject Configuration http docs jboss org hibernate beanvalidation spec 1 1 api javax validation Configuration html ValidatorFactory http docs jboss org hibernate beanvalidation spec 1 1 api javax validation V alidatorFactory html and Validator http docs jboss org hibernate beanvalidation spec 1 1 api javax validation V alidator html as required by Bean Validation spec Note Injected Configuration http docs jboss org hibernate beanvalidation spec 1 1 api javax validation Configuration html ValidatorFactory http docs jboss org hibernate beanvalidation spec 1 1 api javax validation ValidatorFactory html and Validator http docs jboss org hibernate beanvalidation spec 1 1 api Javax validation Validator html do not inherit configuration provided by ValidationConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server validation ValidationConfig html and need to be configured manually Injection of JAX RS components into ConstraintValidators is supported via a custom ConstraintValidatorFactory provided by Jersey An example is shown in Example 16 12 Injecting UriInfo i
108. a Template http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc Template html annotation For example take a look at the resource class listing in Example 17 7 Using Template on a resource class Example 17 7 Using Template on a resource class Path foo Template public class Foo public String getFoo return FOO The example above uses a lot of conventions and requires some more explanation First of all you may have noticed that there is no resource method defined in this JAX RS resource Also there is no template reference defined In this case since the femplate annotation placed on the resource class does not contain any information the default relative template reference index will be used Later it will get resolved to an absolute com foo Foo index template reference As for the missing resource methods a default GET method will be implicitly generated by Jersey for the Foo resource our MVC Controller The implementation of the implicitly added resource method performs the equivalent of the following explicit resource method GET public Viewable get return new Viewable index this As youcan see the resource class serves in this case also as a model Producible media types are determined based on the Produces annotation declared on the resource class if any 177 MVC Templates Note In case of a resource class based impli
109. a deployed RESTful web application It contains model of the deployed resources their structure supported media types HTTP methods and so on In a sense WADL is a similar to the WSDL Web Service Description Language which describes SOAP web services WADL is however specifically designed to describe RESTful Web resources Let s start with the simple WADL example In the example there is a simple CountryResource deployed and we request a wadl of this resource The context root path of the application is http localhost 9998 Example 15 1 A simple WADL example JAX RS resource definition 1 Path country id 2 public static class CountryResource 3 4 private CountryService countryService 5 6 public CountryResource Ju init countryService 8 9 10 GET 11 Produces MediaType APPLICATION_XML 12 public Country getCountry PathParam countryId int countryId 13 return countryService getCountry countryId 14 T5 The WADL of a Jersey application that contains the resource above can be requested by a HTTP GET requesttoht tp localhost 9998 application wadl TheJersey will return a response with a WADL content similar to the one in the following example 150 30 lt method name OPTIONS id apply gt 31 lt request gt 32 representation mediaType gt 33 lt requWaADL Support 34 lt response gt 35 lt representation mediaType gt Example 15 2 A
110. a set of three extension modules e jersey mvc https jersey java net project info 2 1 jersey project jersey mvc dependencies html The base module that provides API and extension SPI for MVC templating support in Jersey This module is required by any particular MVC templating engine integration module that implements the exposed SPI e jersey mvc freemarker https jersey java net project info 2 1 jersey project jersey mvc freemarker dependencies html An integration module with Freemarker based templating engine The module provides a custom TemplateProcessor for Freemarker templates and a set of related engine specific configuration properties e jersey mvc jsp https jersey java net project info 2 1 jersey project jersey mvc jsp dependencies html An integration module for JSP based templating engine The module provides a custom TemplateProcessor for JSP templates custom tag implementation and a set of related engine specific configuration properties Note In a typical set up projects using the Jersey MVC templating support would depend on the base module that provides the API and SPI and a single templating engine module for the templating engine of your choice These modules need to be mentioned explicitly in your pom xml file If you want to use just templating API infrastructure provided by Jersey for the MVC templating support in order to implement your custom support for a templating engine other than the ones pro
111. alatatainie http jersey java net nonav Default value is false 196 Configuration Properties Constant Value Description apidocs snapshot jersey org glassfish jersey server ServerProperties html RESOURC E_VALIDATION_DISABLE ServerProperties RESOURCE V AJ d bag TONDO IGNORE ERRORS Betennames a lutlter orvalidatione http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html RESOURC of application resource models should fail even in case of a fatal validation errors Default value is E VALIDATION IGNORE ERRORSje Errors ServerProperties WADL FEATU http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html WADL_FE EATURE_ DISABLE RiSdS3ESABIdnfig server waBisaBlesab WADAL generation Default value is false ServerProperties WADL_GENERA FORe CONFIGI g server waDefigeme thet o math f igenerator http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html W ADL_GENERATOR_CONFIG configuration that provides a WadlGenerator http jersey java net nonav apidocs snapshot jersey org glassfish jersey server wadl WadlGenerator html A 3 Client configuration properties List of client configuration properties that can be found in ClientProperties http jersey java net nonav apidocs snapshot jerse
112. an 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 38 JAX RS Application Resources and Sub Resources Example 3 26 Example of possible injections 1 Path resource 2 public static class SummaryOfInjectionsResource 3 QueryParam query 4 String param injection into a class field 5 6 7 GET 8 public String get QueryParam query String methodQueryParam 9 injection into a resource method parameter 10 return query param param 11 12 1 3 QPath sub resource locator 14 public Class SubResource subResourceLocator QueryParam query String s 15 injection into a sub resource locator parameter 16 return SubResource class 17 18 T9 public SummaryOfInjectionsResource GQueryParam query String constructor 20 injection into a constructor parameter 21 22 23 24 Context 29 public void setRequest Request request 26 injection into a setter method 27 System out println request null 28 29 30 31 public static class SubResource 32 GET 33 public String get 34 return sub resource 35 36 The FormParam http jax rs spec java net nonav 2 0 apidocs javax ws rs For
113. andler and setTimeout long TimeUnit methods The set TimeoutHandler TimeoutHandler method defines the handler that will be invoked when timeout is reached The handler resumes the response with the response code 503 from Response Status SERVICE UNAVAILABLE A timeout interval can be also defined without specifying a custom timeout handler using just the setTimeout long TimeUnit method In such case the default behaviour of Jersey runtime is to throw a ServiceUnavailableException that gets mapped into 503 Service Unavailable HTTP error response as defined by the JAX RS specification 10 1 1 Asynchronous Server side Callbacks As operations in asynchronous cases might take long time and they are not always finished within a single resource method invocation JAX RS offers facility to register callbacks to be invoked based on suspended async response state changes In Jersey you can register two JAX RS callbacks CompletionCallback http jax rs spec java net nonav 2 0 apidocs javax ws rs container CompletionCallback html that is executed when request finishes or fails and ConnectionCallback http jax rs spec java net nonav 2 0 apidocs javax ws rs container ConnectionCallback html executed when a connection to a client is closed or lost 116 Asynchronous Services and Clients Example 10 3 CompletionCallback example 1 Path resource 2 public class AsyncResource
114. 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 28 JAX RS Application Resources and Sub Resources 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 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 O0 apidocs javax ws rs FormParam html is slightly special because it extracts information from a request representation that is of the MIME media type application x www form urlencoded and conforms to the encoding specified by HTML forms as described here This parameter is very useful for extracting information that is POSTed by HTML forms for example the following extracts the form parameter named name from the POSTed fo
115. arize the injection can be done into the following constructs Table 3 2 Overview of injection types 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 37 JAX RS Application Resources and Sub Resources Java construct Description Constructor parameters Resource methods 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 The resource methods these annotated with 9 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 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 c
116. as if it were used for injection in the resource method directly Injecting the bean parameter into Singleton resource class fields is not allowed injections into method parameter must be used instead BeanParam http jax rs spec java net nonav 2 0 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 O apidocs javax ws rs QueryParam html 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 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 1 GPOST 2 public void post GBeanParam MyBeanParam beanParam BeanParam AnotherBean anot 3 String entity 4 beanParam getPathParam pathParam 5 6 3 3 Sub resources Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html may be used on classes and such classes are referred to as root resource classes Path
117. ass CompressionDynamicBinding implements DynamicFeature 28 29 Override 30 public void configure ResourceInfo resourceInfo FeatureContext context 31 if HelloWorldResource class equals resourceInfo getResourceClass 32 amp amp resourcelnfo getResourceMethod 33 getName contains VeryLongString 34 context register GZIPWriterInterceptor class 35 36 Sq i The example contains one HelloWorldResource which is known from the previous name binding example The difference is in the getVeryLongString method which now does not define the Compress name binding annotations The binding is done using the provider which implements DynamicFeature http jax rs spec java net nonav 2 0 apidocs javax ws rs container DynamicFeature html interface The interface defines one configure method with two arguments ResourceInfo and FeatureContext ResourceInfo contains information about the resource and method to which the binding can be done The configure method will be executed once for each resource method that is defined in the application In the example above the provider will be executed twice once for the get Hello method and once for get VeryLongString once the resourceInfo will contain information about getHello method and once it will point to get VeryLongString If a dynamic binding provider wants to register any provider for the actual resource method it will do that using provided FeatureContext which extends J
118. ates are located Example 17 3 Setting MvcProperties TEMPLATE BASE PATH value in ResourceConfig new ResourceC property register Furthe register onfig MvcProperties TEMPLATE BASE PATH templates MvcFeature class r configuration of ResourceConfig C s I Example 17 4 Setting FreemarkerMvcProperties TEMPLATE BASE PATH value in web xml lt servlet gt servlet servlet init par para para init pa init par para para init pa lt load on lt servlet gt name gt org glassfish jersey examples freemarker MyApplication lt servlet class org glassfish jersey servlet ServletContainer servlet class am m name gt javax ws rs Application lt param name gt m value gt org glassfish jersey examples freemarker MyApplication lt param ram gt am gt m name gt jersey config server mvc templateBasePath freemarker lt param na m value gt freemarker lt param value gt ram gt startup gt 1 lt load on startup gt 175 MVC Templates 17 3 Explicit vs Implicit View Templates Note Some of the passages examples from this and the next section was taken from MVCJ https blogs oracle com sandoz entry mvcj blog article written by Paul Sandoz earlier In Jersey 2 0 the base MVC API excluding the SPI part consists of two classes in the org glassfish jersey server mvc package in base MVC module that we will explore in more detai
119. ation 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 HttpHandler endpoint RuntimeDelegate getInstance createEndpoint new MyApplicat Jersey also provides Grizzly http grizzly java net helper classes to deploy the HttpHandler instance at a base URL for in process deployment The Jersey samples provide many examples of Servlet based and Grizzly in process based deployments 4 1 Auto Discoverable Features For a few modules provided by Jersey there is no need to explicitly register their Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature html s as these Features are discovered and registered in the Configuration http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configuration html on client server automatically by Jersey when the modules implementing these features are present on the classpath during the an application deployment The modules that are automatically discovered include jersey media moxy JSON part 43 Deploying a RESTful Web Service jersey media json processing jersey bean validation Besides these modules there are also few features providers present in jersey server module that are discovered by this mechanism and their availability is affected by Jersey auto discovery support configuration see Section 4 1 1 Configuring
120. ations serializes JSON in a different way Following is a list of supported notations JETTISON_MAPPED default notation 84 Support for Common Media Type Representations BADGERFISH You might want to use one of these notations when working with more complex XML documents Namely when you deal with multiple XML namespaces in your JAXB beans Individual notations and their further configuration options are described bellow Rather then explaining rules for mapping XML constructs into JSON the notations will be described using a simple example Following are JAXB beans which will be used Example 8 17 JAXB beans for JSON supported notations description simple address bean 1 GXmlRootElement 2 public class Address 3 public String street 4 public String town 5 6 public Address 7 8 public Address String street String town 9 this street street 10 this town town dea 12 Example 8 18 JA XB beans for JSON supported notations description contact bean 1 GXmlRootElement 2 public class Contact 3 4 public int id 5 public String name 6 public List Address addresses 7 8 public Contact 9 10 public Contact int id String name List lt Address gt addresses 11 this name name 12 this id id 13 this addresses 14 addresses null new LinkedList lt Address gt addresses null 15 16 Following text will be mainly working with a conta
121. ator implementations 4 cocto cer tg repe eon tiep o sed rete Roe Po pe tess er Ue RE oen 165 16 8 Entity Validation ceo c ee EUN o deae va dea cupo dee 166 16 9 Entity Validation 2 iecit euet estet tiex ten be given ten eed der eoe EE OUR SNNN ES 166 16 10 Response entity validation sssrin eeen an e Im Hmm emm e eere 167 16 11 Validate getter on execution syss ronnen III em emen ent ente mee nennen 167 16 12 Injecting UriInfo into a ConstraintValidator essese eeeeeeeeeeeeeeeaeeenes 168 16 13 Support for injecting Jersey s resources providers via ConstraintValidatorFactory 169 16 14 Val idationError to text plain ener endete ghe er ERR e P ERR i 171 16 15 Va lrdatio nbrrfor t0 text Btnml 2 etes epe encre pep ates 171 16 16 ValidationError to application XxIlaestose en UN E coin 171 Jersey 2 1 User Guide 16 17 ValidationEE rortoapplication JSODn sus iere repere shone EE N EEES PES 172 173 Registering MveF eat r ess voee ect grex d ertet sed tiene reed p d eet eet 174 17 2 Registering JspMyvekesatuEe ei Vestieciter tortue des eet ree tastes cheese dens MEE EES 174 17 3 Setting MvcProperties TEMPLATE BASE PATH value in ResourceConfig 175 17 4 Setting FreemarkerMvcProperties TEMPLATE BASE PATH value in web xml 175 17 5 Using Viewable in a resource class iriran ar E ee em eme nennen 176 17 6 Using absolute path to template in Viewable
122. ax ws rs core Context html annotation that provides essentially the equivalent of the functionality available on HttpServletRequest http docs oracle com javaee 5 api javax servlet http HttpServletRequest html API The injected security context depends on the actual Jersey application deployment For example if a Jersey application is deployed in a Servlet container the Jersey SecurityContext will return information of the security context retrieved from Servlet request For Jersey applications deployed on a Grizzly server the SecurityContext will return information retrieved from the Grizzly request SecurityContext can be used in conjunction with sub resource locators to return different resources if the user principle is included in a certain role For example a sub resource locator could return a different resource if a user is a preferred customer Example 14 1 Accessing SecurityContext 1 Path basket 2 public ShoppingBasketResource get Context SecurityContext sc 3 if sc isUserInRole PreferredCustomer 4 return new PreferredCustomerShoppingBasketResource 5 else 6 return new ShoppingBasketResource 7 8 SecurityContext can be injected also to singleton resources and providers as a class field In such case the proxy of the request scoped SecurityContext will be injected Example 14 2 Injecting SecurityContext into a singleton resource 1 Path resource 2 Singleton 3 public static class
123. back from the server individually without closing the connection after processing each message So SSE typically reuses one connection for more messages called events SSE also defines a dedicated media type that describes a simple format of individual evnets sent from the server to the client SSE also offers standard javascript client API implemented most modern browsers For more information about SSE see the SSE API specification http www w3 org TR 2009 WD eventsource 20091029 WebSocket technology is different from previous technologies as it provides a real full duplex connection The initiator is again a client which sends a request to a server with a special HTTP header that informs the server that the HTTP connection may be upgraded to a full duplex TCP IP WebSocket connection If server supports WebSocket it may choose to do so Once a WebSocket connection is established it can be used for bi directional communication between the client and the server Both client and server can then send data to the other party at will whenever it is needed The communication on the new WebSocket connection is no longer based on 134 Server Sent Events SSE Support HTTP protocol and can be used for example for for online gaming or any other applications that require fast exchange of small chunks of data in flowing in both directions 13 2 When to use Server Sent Events As explained above SSE is a technology that allows client
124. blic void putPrinter PathParam printerid String printerId Printer p 28 29 DELETE Path ids printerid 30 public void deletePrinter GPathParam printerid String printerId 31 If the path of the request URL is printers then the resource methods not annotated with Path http jax rs spec java net nonav 2 0 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 9 GET http jax rs spec java net nonav 2 O0 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 32 JAX RS Application Resources and Sub Resources Example 3 18 Sub resource locators 1 Path item 2 public class ItemResource 3 Context UriInfo uriInfo 4 5 Path content 6 public ItemContent
125. body reader writer as a part of their execution and they can wrap the input output stream before the entity is read written There are exceptions when interceptors are not run before message body reader writers but this is not the case of simple scenario above This happens for example when the entity is read many times from client response using internal buffering Then the data are intercepted only once and kept decoded in the buffer 108 Filters and Interceptors 9 5 Name binding Filters and interceptors can be name bound Name binding is a concept that allows to say to a JAX RS runtime that a specific filter or interceptor will be executed only for a specific resource method When a filter or an interceptor is limited only to a specific resource method we say that it is name bound Filters and interceptors that do not have such a limitation are called global Filter or interceptor can be assigned to a resource method using the NameBinding http jax rs spec java net nonav 2 0 apidocs javax ws rs NameBinding html annotation The annotation is used as meta annotation for other user implemented annotations that are applied to a providers and resource methods See the following example 109 Filters and Interceptors Example 9 7 NameBinding example ceo 10 OBWN EF 4 0 000000 00 C0 C0 C0 CO CO PO PO PO PO PO PO PO PO P2 PO ES FFF RFR RP B B EO ES QOO 000 1001 GO 2r OO 000 1001 CO Fl0r eO w000 10 01 C0 P2
126. c class BroadcasterResource 8 9 private SseBroadcaster broadcaster new SseBroadcaster 10 Ti POST 12 Produces MediaType TEXT_PLAIN 13 Consumes MediaType TEXT_PLAIN 14 public String broadcastMessage String message 15 OutboundEvent Builder eventBuilder new OutboundEvent Builder 16 OutboundEvent event eventBuilder name message 17 mediaType MediaType TEXT_PLAIN_TYPE 18 data String class message 19 build 20 21 broadcaster broadcast event 22 23 return Message was message broadcast 24 25 26 GET 27 Produces SseFeature SERVER_SENT_EVENTS 28 public EventOutput listenToBroadcast 29 final EventOutput eventOutput new EventOutput 30 this broadcaster add eventOutput 31 return eventOutput 32 33 gt Let s explore the example together The BroadcasterResource resource class is annotated with Singleton http docs oracle com javaee 6 api javax inject Singleton html annotation which tells Jersey runtime that only a single instance of the resource class should be used to serve all the incoming requests to broadcast path This is needed as we want to keep an application wide single reference to the private broadcaster field so that we can use the same instance for all requests Clients that want to listen to SSE events first send a GET request to the BroadcasterResource that is handled by the listenToBroadcast resource method The method creates a new EventOut put representing
127. c void completed Response response 5 System out println Response status code 6 response getStatus received 7 8 9 Override 10 public void failed Throwable throwable 11 System out println Invocation failed 12 throwable printStackTrace 13 14 The registered callback is expected to implement the InvocationCallback http jax rs spec java net nonav 2 0 apidocs javax ws rs client InvocationCallback html interface that defines two methods First method completed Response gets invoked when an invocation successfully finishes The result response is passed as a parameter to the callback method The second method failed Throwable is invoked in case the invocation fails and the exception describing the failure is passed to the method as a parameter In this case since the callback generic type is Response the failed Throwable method would only invoked in case the invocation fails because of an internal client side processing error It would not be invoked in case a server responds with an HTTP error code for example if the requested resource is not found on the server and HTTP 404 response code is returned In such case completed Response callback method would be invoked and the response passed to the method would contain the returned error response with HTTP 404 error code This is a special behavior in case the generic callback return type is Response In the next example an exception is thrown or failed T
128. can manipulate resource method matching process 107 Filters and Interceptors 7 Server matching resource method matching is done 8 Server post matching ContainerRequestFilters ContainerRequestFilters post matching filters are executed This include execution of all global filters without name binding and filters name bound to the matched method 9 Server ReaderInterceptor reader interceptors are executed on the server The GZIPReaderInterceptor wraps the input stream the stream from the wire into the GZipInputStream and set it to context 10 Server MessageBodyReader server message body reader is executed and it deserializes the entity from new GZipInputStream get from the context This means the reader will read unzipped data and not the compressed data from the wire 11 Server resource method is executed the deserialized entity object is passed to the matched resource method as a parameter The method returns this entity as a response entity 12 Server ContainerResponseFilters are executed response filters are executed on the server and they manipulate the response headers This include all global bound filters without name binding and all filters name bound to the resource method 13 Server WriterInterceptor is executed on the server It wraps the original output stream with a new GZIPOuptutStream The original stream is the stream that goes to the wire output stream for response from the underlying se
129. caster is not mandatory to complete the use case individual EventOutput http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventOutput html s can be just stored in a collection and iterated over in the broadcastMessage method However the SseBroadcaster internally identifies and handles also client disconnects When a client closes the connection the broadcaster detects this and removes the stale connection from the internal collection of the registered EventOutput http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventOutput html s as well as it frees all the server side resources associated with the stale connection Additionally the SseBroadcaster is implemented to be thread safe so that clients can connect and disconnect in any time and SseBroadcaster will always broadcast messages to the most recent collection of registered and active set of clients 13 5 Consuming SSE events with Jersey clients On the client side Jersey exposes APIs that support receiving and processing SSE events using two programming models Pull model pulling events from a EventInput http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventInput html or Push model listening for asynchronous notifications of Event Source Both models will be described 13 5 1 Reading SSE events with EventInput The events can be read on the client side from a EventInput
130. cit MVC view template the controller is also the model In this case the template reference index is special it is the template reference associated with the controller itself Implicit sub resource templates are also supported for example for a template reference bar that resolves to an absolute template reference com foo Foo bar that in turn resolves to a processable template reference Following GET method is also implicitly added to the Foo controller that performs the equivalent of the following explicit sub resource method GET Path implicit view path parameter public Viewable get GPathParameter implicit view path pa return new Viewable template this In other words a HTTP GET request to a foo bar would be handled by this auto generated method in the Foo resource and would delegate the request to a registered template processor supports processing of the absolute template reference com foo Foo bar while the model is still an instance of the JAX RS resource class Foo 17 3 2 2 Resource methods In case a resource method is annotated with Template http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc Template html annotation then the return value of the method defines the MVC model part The processing of such a method is then essentially the same as if the return type of the method was an instance of the Viewable http jersey java net nonav apidocs snaps
131. client API apply to WebTarget as well Each WebTarget instance inherits a configuration from it s parent either a client or another web target and can be further custom configured without affecting the configuration of the parent component In this case the FilterForExampleCom will be registered only in the webTarget and not in client So the client can still be used to create new WebTarget instances pointing at other URIs using just the common client configuration which FilterForExampleCom filter is not part of 5 3 4 Identifying resource on WebTarget Let s assume we have a webTarget pointing at http example com rest URI that represents a context root of a RESTful application and there is a resource exposed on the URI http example com rest resource As already mentioned a WebTarget instance can be used to derive other web targets Use the following code to define a path to the resource 1 WebTarget resourceWebTarget webTarget path resource The resourceWebTarget now points to the resource on URI http example com rest resource Again if we configure the resourceWebTarget with a filter specific to the resource it will not influence the original webTarget instance However the filter FilterForExampleCom registration will still be inherited by the resourceWebTarget asithas been created from webTarget This mechanism allows you to share the common configuration of related resources typically hosted under the same URI
132. com javase 6 docs api java lang Boolean html Character http docs oracle com javase 6 docs api java lang Character html and Number http docs oracle com javase 6 docs api java lang Number html text plain corresponding primitive types supported via boxing unboxing conversion For other media type supported in jersey please see the Chapter 8 Support for Common Media Type Representations which describes additional Jersey entity provider extensions for serialization to JSON XML serialization of collections Multi Part http jersey java net nonav apidocs snapshot jersey org glassfish jersey media multipart package info html and others 74 Chapter 8 Support for Common Media Type Representations 8 1 JSON 8 1 1 Jersey JSON support comes as a set of extension modules where each of these modules contains an implementation of a Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature html that needs to be registered into your Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html instance client server There are multiple frameworks that provide support for JSON processing and or JSON to Java binding The modules listed bellow provide support for JSON representations by integrating the individual JSON frameworks into Jersey At present Jersey integrates with the following modules to provide JSON support MOXy JSON binding support via MOXy i
133. core Form html instance is created with two form parameters Once ready the Form instance is POSTed to the target resource First the 46 Client API acceptable media type is specified in the request method Then in the post method a call to a static method on JAX RS Entity http jax rs spec java net nonav 2 0 apidocs javax ws rs client Entity html is made to construct the request entity instance and attach the proper content media type to the form entity that is being sent The second parameter in the post method specifies the Java type of the response entity that should be returned from the method in case of a successful response In this case an instance of JAXB bean is requested to be returned on success The Jersey client API takes care of selecting the proper MessageBodyWriter T http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html for the serialization of the Form instance invoking the POST request and producing and de serialization of the response message payload into an instance of a JAXB bean using a proper MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html If the code above had to be written using Ht tpUrlConnection the developer would have to write custom code to serialize the form data that are sent within the POST request and de serialize the response input stream into a JAXB bean Additionally more code
134. ct bean initialized with Example 8 19 JAXB beans for JSON supported notations description initialization 1 Address addresses new Address Long Street 1 Short Village 2 Contact contact new Contact 2 Bob Arrays asList addresses Le contact bean with id 2 name Bob containing a single address st reet Long Street 1 town Short Village 85 Support for Common Media Type Representations All bellow described configuration options are documented also in api docs at JettisonConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey jettison JettisonConfig html 8 1 5 2 1 Jettison mapped notation If you need to deal with various XML namespaces you will find Jettison mapped notation pretty useful Lets define a particular namespace for id item 1 2 XmlElement namespace http example com 3 public int id 4 Then you simply configure a mapping from XML namespace into JSON prefix as follows Example 8 20 XML namespace to JSON mapping configuration for Jettison based mapped notation 1 Map lt String String gt ns2json new HashMap lt String String gt 2 ns2json put http example com example 3 context new JettisonJaxbContext 4 JettisonConfig mappedJettison xml2JsonNs ns2json build 5 types Resulting JSON will look like in the example bellow Example 8 21 JSON expression with XML namespaces mapped into JSON LA 2 contact
135. ctor needed for deserialization by JAXB 14 public MyBean T5 16 13 Override 18 public String toString 19 return MyBean 20 anyString anyString N 2l anyNumber anyNumber 22 ons 23 24 7 2 1 MessageBodyWriter The MyBean is a JAXB annotated POJO In G ET resource method we return the instance of MyBean and we would like Jersey runtime to serialize it into XML and write it as an entity body to the response output stream We design a custom MessageBodyWriter lt T gt that can serialize this POJO into XML See the following code sample 63 JAX RS Entity Providers Note Please note that this is only a demonstration of how to write a custom entity provider Jersey already contains default support for entity providers that can serialize JAXB beans into XML Example 7 3 MessageBodyWriter example 1 Produces application xml 2 public class MyBeanMessageBodyWriter implements MessageBodyWriter lt MyBean gt 3 4 Override 9 public boolean isWriteable Class lt gt type Type genericType 6 Annotation annotations MediaType mediaType 7 return type MyBean class 8 9 10 Override 11 public long getSize MyBean myBean Class lt gt type Type genericType 12 Annotation annotations MediaType mediaType 13 deprecated by JAX RS 2 0 and ignored by Jersey runtime 14 return 0 15 16 17 Override 18 public void writeTo MyB
136. d 3 1 2 GET QPUT QPOST DELETE HTTP Methods GET http jax rs spec java net nonav 2 O 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 htm 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 24 JAX RS Application Resources and Sub Resources 3 1 3 The following example is an extract from the storage service sample that shows the use of the PUT method to create or update a storage container Example 3 3 PUT method 1 PUT 2 public Response putContainer 3 System out println PUT CONTAINER container 4 5 URI uri urilInfo getAbsolutePath 6 Container c new Container container uri toString 7 8 Response r 9 if MemoryStore MS hasContainer c 10 r Response created uri build 11 else 12 r Response noContent build 13 14 15 MemoryStore MS createContainer c 16 return r 17 By default the JAX RS runtime will automat
137. d by the proper MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext 122 Asynchronous Services and Clients MessageBodyReader html You can define the media type of chunks to aid the selection of a proper MessageBodyReader lt T gt in order to read chunks correctly into the requested entity types in our case into Strings 123 Chapter 11 URIs and Links 11 1 Building URIs A very important aspect of REST is hyperlinks URIs in representations that clients can use to transition the Web service to new application states this is otherwise known as hypermedia as the engine of application state HTML forms present a good example of this in practice Building URIs and building them safely is not easy with URI http docs oracle com javase 6 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 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 UriInfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html provides such information in addition to further information see next section The following example shows URI building with Urilnfo and U
138. d decides to send it to the client whenever new chunk of data is available When a new data event occurs on the server the data event is sent by the server to the client Thus the name Server Sent Events Note that at high level there are more technologies working on this principle a short overview of the technologies supporting server to client communication is in this list Polling Long polling Server Sent events WebSocket With polling a client repeatedly sends new requests to a server If the server has no new data then it send appropriate indication and closes the connection The client then waits a bit and sends another request after some time after one second for example With long polling a client sends a request to a server If the server has no new data it just holds the connection open and waits until data is available Once the server has data message for the client it uses the connection and sends it back to the client Then the connection is closed SSE is similar to the long polling mechanism except it does not send only one message per connection The client sends a request and server holds a connection until a new message is ready then it sends the message back to the client while still keeping the connection open so that it can be used for another message once it becomes available Once a new message is ready it is sent back to the client on the same initial connection Client processes the messages sent
139. dEvent The method Inboundl Event getData Class provides a way for the client to indicate what Java type should be used for the event data de serialization In our example individual events are de serialized as String Java type instances This method internally finds and executes a proper MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html which is the used to do the actual de serialization This is similar to reading an entity from the Response http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response html by readEnt ity Class The method getData can also throw an IO exception The null check on inbound Event is necessary to make sure that the chunk was properly read and connection has not been closed by the server Once the connection is closed the loop terminates and the program completes execution The client code produces the following console output message to client Hello message to client Hello message to client Hello message to client Hello message to client Hello message to client Hello message to client Hello message to client Hello message to client Hello message to client Hello world 0 world 1 world 2 world 3 world 4 world 5 world 6 world 7 world 8 world 9 13 5 2 Asynchronous SSE processing with EventSource The main Jersey SSE client is Even
140. dary key of media type Additionally JAX RS specification mandates that custom user registered providers have to be sorted ahead of default providers provided by JAX RS implementation This is used as a tertiary comparison key User providers are places prior to Jersey internal providers in to the final ordered list The sorted providers will be MyBeanMessageBodyWriter B D A 5 Iterate through the sorted MessageBodyWriter lt T gt providers and utilizing the isWriteable method of each until you find a MessageBodyWriter lt T gt that returns t rue The first provider in the list our MyBeanMessageBodyWriter returns true as it compares types and the types matches If it would return false the next provider B would by check by invoking its isWriteable method 70 JAX RS Entity Providers If step 5 locates a suitable MessageBodyWriter lt T gt then use its writeTo method to map the object to the entity body MyBeanMessageBodyWriter writeTo will be executed and it will serialize the entity e Otherwise the server runtime MUST generate a generate an InternalServerErrorException a subclass of WebApplicationException with its status set to 500 and no entity and the client runtime MUST generate a ProcessingException We have successfully found a provider thus no exception is generated Note JAX RS 2 0 is incompatible with JAX RS 1 x in one step of the entity provider selection algorithm JAX RS 1 x defines sorting key
141. ders as the response Content type header is already defined by the Produces and set to text event stream using constant from the SseFeature The event media type is used for serialization of event data Event data media type and Java type are used to select the proper MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html for event data serialization and are passed to the selected writer that serializes the event data content In our case the string Hello world i isserialized as text plain Inevent data you can send any Java entity and associate it with any media type that you would be able to serialize with an available MessageBodyWriter lt T gt Typically you may want to send e g JSON data so you would fill the data with a JAXB annotated bean instance and define media type to JSON Note If the event media type is not set explicitly the text plain media type is used by default Once an outbound event is ready it can be written to the eventOutput At that point the event is serialized by internal OutboundEventWriter which uses an appropriate MessageBodyWriter lt T gt to serialize the Hello world i string You can send as many messages as you like At the end of the thread execution the response is closed which also closes the connection to the client After that no more messages can be send to the client on this connection If the client would like
142. ds 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 evolvability or loose coupling clients and services can evolve over time perhaps in new and unexpected ways while retaining backwards compatibility Further constraints are required 1 every resource is identified by a URI 2 aclient interacts with the resource via HTTP requests and responses using a fixed set of HTTP methods 3 one or more representations can be returned 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 45 Client API Many existing Java based client APIs such as the Apache HTTP client API or 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 A resource in the JAX RS client API is an instance of the Java class WebTarget http jax rs
143. e athe same Java model to generate JSON as well 75 Support for Common Media Type Representations as XML representations Another advantage is simplicity of working with such a model and availability of the API in Java SE Platform JAXB leverages annotated POJOs and these could be handled as simple Java beans A disadvantage of JAXB based approach could be if you need to work with a very specific JSON format Then it might be difficult to find a proper way to get such a format produced and consumed This is a reason why a lot of configuration options are provided so that you can control how JAXB beans get serialized and de serialized The extra configuration options however requires you to learn more details about the framework you are using Following is a very simple example of how a JAXB bean could look like Example 8 1 Simple JAXB bean implementation 1 GXmlRootElement 2 public class MyJaxbBean 3 public String name 4 public int age 5 6 public MyJaxbBean JAXB needs this 7 8 public MyJaxbBean String name int age 9 this name name 10 this age age 11 12 5 Using the above JAXB bean for producing JSON data format from you resource method is then as simple as Example 8 2 JAXB bean used to generate JSON representation GET Produces application json public MyJaxbBean getMyBean return new MyJaxbBean Agamemnon 32 Oe WN PF Notice that JSON specific mime type
144. e new links 126 Chapter 12 Programmatic API for Building Resources 12 1 12 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 O apidocs javax ws rs POST html and implement needed functionality This approach is described in the chapter JAX RS Application Resources and Sub Resources 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 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 In some situations it would be useful to add an 9 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 whet
145. e registered will be executed and will have possibility to process the aborted response 9 2 1 1 Pre matching and post matching filters All the request filters shown above was implemented as post matching filters It means that the filters would be applied only after a suitable resource method has been selected to process the actual request i e after request matching happens Request matching is the process of finding a resource method that should be executed based on the request path and other request parameters Since post matching request filters are invoked when a particular resource method has already been selected such filters can not influence the resoure method matching process To overcome the above described limitation there is a possibility to mark a server request filter as a pre matching filter i e to annotate the filter class with the PreMatching http jax rs spec java net nonav 2 0 apidocs javax ws rs container PreMatching html annotation Pre matching filters are request filters that are executed before the request matching is started Thanks to this pre matching request filters have the possibility to influence which method will be matched Such a pre matching request filter example is shown here Example 9 3 Pre matching request filter import javax ws rs container ContainerRequestContext import javax ws rs container ContainerRequestFilter import javax ws rs container PreMatching PreMatching public class PreMa
146. eR eset yeut 168 16 7 Error Reporting 5 due IS Ie e 169 16 71 Validation Brtot eo eor eter Rete reete Deer op RON Ee petes nre po 169 cun EI 172 I7 MVC Templates eot ietete A a eS eni istis tte Neto eeot im dexeims 173 17 3 Dependencies nenion p eH pei opere e Etude eb e e Ree 173 17 2 Registration and Configuration ss ssscse teevee sitenoi dist inesi enp Sie YEER enn EE nE eee hee nennen 174 17 3 Explicit vs Implicit View Templates 0 cece cece eH 176 17 3 1 Viewable Explicit View Templates esee 176 17 3 2 femplate Implicit View Templates 2 0 0 0 eee ee cece eeeeeeeee ee 177 IU cISP e 178 17 5 Custom Templating Engines scares cece cece eee ence TEE eens eem emen mener 179 17 6 Other Examples ye e e dee t soe tase tive tes eter E exon escis ede tee den adenareode EAN 180 18 Jersey Test Framework sys sere Re ere ue E ei 181 18 1 Basis ws vesscunuc aa a e a ny amass a sean See bys A EE ETTER 181 18 2 Supported Contamers o eros E T R E e EE E EE ntact 182 18 3 Advanced feat res cuoio ere EL Re a aE o cota E E aN 183 18 3 1 JerseyTest Features ciori ou E EES va exe EEES 183 1823 2 External contamet eee oreet erre ree Ce EE E SENSEY 183 18 3 3 Test Client configuration srren T a Hem eee 184 18 3 4 Accessing the logged test records programmatically sese 184 19 Building and Testing Jersey ireen eN cece cee ce ee ceeeceeeca Ie
147. ean myBean 19 Class lt gt type 20 Type genericType 21 Annotation annotations 22 MediaType mediaType 23 MultivaluedMap lt String Object gt httpHeaders 24 OutputStream entityStream 29 throws IOException WebApplicationException 26 27 try 28 JAXBContext jaxbContext JAXBContext newInstance MyBean class 29 30 serialize the entity myBean to the entity output stream 31 jaxbContext createMarshaller marshal myBean entityStream 32 catch JAXBException jaxbException 33 throw new ProcessingException 34 Error serializing a MyBean to the output stream jaxbExcepti 39 36 up Y The MyBeanMessageBodyWriter implements the MessageBodyWriter lt T gt interface that contains three methods In the next sections we ll explore these methods more closely 7 2 1 1 MessageBodyWriter isWriteable A method isWriteable should return true if the MessageBodyWriter lt T gt is able to write the given type Method does not decide only based on the Java type of the entity but also on annotations attached to the entity and the requested representation media type 64 JAX RS Entity Providers Parameters t ype and genericType both define the entity where t ype is araw Java type for example a java util List class and genericType is a ParameterizedType http docs oracle com javase 6 docs api java lang reflect ParameterizedT ype html including generic information for example List lt String gt Parameter annotat
148. ebXml false failOnMissingWebXml 9 configuration 10 plugin 11 oes 12 lt plugins gt Another deployment option is to declare JAX RS application details in theweb xm1 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 servlet name element of the JAX RS application s web xml This is supported in a Web container implementing Servlet 3 0 as follows Example 4 5 Deployment of a JAX RS application using web xm1 with Servlet 3 0 1 lt web app gt 2 lt servlet gt 3 lt servlet name gt org foo rest MyApplication lt servlet name gt 4 lt servlet gt 5 6 7 8 lt servlet mapping gt lt servlet name gt org foo rest MyApplication lt servlet name gt lt url pattern gt resources lt url pattern gt 9 lt servlet mapping gt 10 obs 11 lt web app gt Note that the servlet class element is omitted from the servlet declaration This is a correct declaration utilizing the Servlet 3 0 extension mechanism Also note that servlet mapping 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
149. ect contains the same MyResouce JAX RS resource class It does not contain any unit tests as well as it does not contain a Main class that was used to setup Grizzly container in the previous project Instead it contains the standard Java EE web application web xm1 deployment descriptor under src main webapp WEB INF The last component in the project is an index jsp page that serves as a client for the MyResource resource class that is packaged and deployed with the application Getting Started To compile and package the application into a WAR invoke the following maven command in your console mvn clean package A successfull build output will produce an output similar to the one below Results Tests run 0 Failures 0 Errors 0 Skipped 0 INFO INFO maven war plugin 2 1 1 war default war simple service webapp INFO Packaging webapp INFO Assembling webapp simple service webapp in simple service webapp tar INFO Processing war project INFO Copying webapp resources simple service webapp src main webapp INFO Webapp assembled in 75 msecs INFO Building war simple service webapp target simple service webapp war INFO WEB INF web xml already added skipping INFO INFO BUILD SUCCESS INFO INFO Total time 9 067s INFO Finished at Sun May 26 21 07 44 CEST 2013 INFO Final Memory 17M 490M INFO Now you are ready to take the packaged WAR located under
150. ect from Maven Archetype Jersey project is build using Apache Maven http maven apache org software project build and management tool All modules produced as part of Jersey project build are pushed to the Central Maven Repository http search maven org Therefore it is very convenient to work with Jersey for any Maven based project as all the released non SNAPSHOT Jersey dependencies are readily available without a need to configure a special maven repository to consume the Jersey modules Note In case you want to depend on the latest SNAPSHOT versions of Jersey modules the following repository configuration needs to be added to your Maven project pom lt repository gt id snapshot repository java net id name Java net Snapshot Repository for Maven lt name gt url https maven java net content repositories snapshots url lt layout gt default lt layout gt lt repository gt Since starting from a Maven project is the most convenient way for working with Jersey let s now have a look at this approach We will now create a new Jersey project that runs on top of a Grizzly http grizzly java net container We will use a Jersey provided maven archetype To create the project execute the following Maven command in the directory where the new project should reside mvn archetype generat DarchetypeArtifactlId jersey quickstart grizzly2 DarchetypeGroupId org glassfish jersey archetypes DinteractiveMode fa
151. ectable lt PerRequestType gt getInjectable ComponentContext ic C Tf eus Jersey 2 0 HK2 Module public static class MyBinder extends AbstractBinder QOverride protected void configure request scope binding 187 Migrating from Jersey 1 x bind MyInjectablePerRequest class to MyInjectablePerRequest class in Req singleton binding bind MyInjectableSingleton class in Singleton class singleton instance binding bind new MyInjectableSingleton to MyInjectableSingleton class register module to ResourceConfig can be done also in constructor ResourceConfig rc new ResourceConfig rc addClasses rc addBinders new MyBinder Jersey 2 0 dynamic binding public static class MyApplication extends Application Inject public MyApplication ServiceLocator serviceLocator System out println Registering injectables DynamicConfiguration dc Injections getConfiguration serviceLocator request scope binding Injections addBinding Injections newBinder MyInjectablePerRequest class to MyInjectablePerRequ dc singleton binding Injections addBinding Injections newBinder MyInjectableSingleton class to MyInjectableSingleton class in Singleton class dc singleton instance binding Injections addBinding Injections newBinder new MyInjectableSingleton to MyInjectableSingleton class
152. ecting 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 N 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 xii Chapter 1 Getting Started This chapter provides a quick introduction on how to get started building RESTful services using Jersey The example described here uses the lightweight Grizzly HTTP server At the end of this chapter you will see how to implement equivalent functionality as a JavaEE web application you can deploy on any servlet container supporting Servlet 2 5 and higher 1 1 Creating a New Proj
153. enabled and two required named body parts data and file The optional part enabled is processed as a boolean value if the part is absent then the value will be true The part data is processed as a JAXB bean and contains some meta data about the following part The part file is a file that is uploaded this is processed as an InputStream Additional information about the file from the Content Disposition header can be accessed by the parameter fileDisposition 100 Support for Common Media Type Representations Tip FormDataParam annotation can be also used on fields 101 Chapter 9 Filters and Interceptors 9 1 Introduction This chapter describes filters interceptors and their configuration Filters and interceptors can be used on both sides on the client and the server side Filters can modify inbound and outbound requests and responses including modification of headers entity and other request response parameters Interceptors are used primarily for modification of entity input and output streams You can use interceptors for example to zip and unzip output and input entity streams 9 2 Filters Filters can be used when you want to modify any request or response parameters like headers For example you would like to add a response header X Powered By to each generated response Instead of adding this header in each resource method you would use a response filter to add this header There are filters on the
154. 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 60 Representations and Responses 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 is used to perform actions that may otherwise have to be duplicated to invoked for each resource method The life cycle of resource classes is per request which means that the resource instance is created for each request and therefore can work with request parameters and for example make changes to the request processing by throwing an exception as it is shown in this example 61 Chapter 7 JAX RS Entity Providers 7 1 Introduction Entity payload if present in an received HTTP message is passed to Jersey from an I O container as an input stream The stream may for example contain data represented as a plain text XML or JSON document However in many JAX RS components that process these inbound data such as resource methods or client responses the JAX RS API user can access the inbound entity as an arbitrary Java ob
155. eparator In order to make MoxyJsonConfig visible for MOXy you need to create and register ContextResolver lt T gt in your client server code 79 Support for Common Media Type Representations Example 8 8 ContextResolver lt MoxyJsonConfig gt Pro publ vider ic class JsonMoxyConfigurationContextResolver implements ContextResolver lt MoxyJ private final MoxyJsonConfig config public JsonMoxyConfigurationContextResolver final Map lt String String gt namespacePrefixMapper new HashMap lt String Stri namespacePrefixMapper put http www w3 org 2001 XMLSchema instance xs config MoxyJsonConfig setNamespacePrefixMapper namespacePrefixMapper setNamespaceSeparator Override public MoxyJsonConfig getContext Class lt gt objectType return config Another way to pass configuration properties to the underlying MOXyJsonProvider is to set them directly into your Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html instance see an example below These are overwritten by properties set into the MoxyJsonConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy json MoxyJsonConfig html Example 8 9 Setting properties for MOXy providers into Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html new There value ResourceConfig property Mars
156. equest processing is suspended and the container thread the one which entered the resource method is returned back to the container s thread pool and it can process other requests New thread started in the resource method may execute an expensive operation which might take a long time to finish Once a result is ready it is resumed using the resume method on the AsyncResponse instance The resumed response is then processed in the new thread by Jersey in a same way as any other synchronous response including execution of filters and interceptors use of exception mappers as necessary and sending the response back to the client It is important to note that the asynchronous response asyncResponse in the example does not need to be resumed from the thread started from the resource method The asynchronous response can be resumed even from different request processing thread as it is shown in the the example of the AsyncResponse http jax rs spec java net nonav 2 0 apidocs javax ws rs container AsyncResponse html javadoc In the javadoc example the async response suspended from the GET method is resumed later on from the POST method The suspended async response is passed between requests using a static field and is resumed from the other resource method running on a different request processing thread Imagine now a situation when there is a long delay between two requests and you would not like to let the client wait for the response forever
157. er this filter 113 Chapter 10 Asynchronous Services and 10 1 Clients This chapter describes the usage of asynchronous API on the client and server side The term async will be sometimes used interchangeably with the term asynchronous in this chapter Asynchronous Server API Request processing on the server works by default in a synchronous processing mode which means that a client connection of a request is processed in a single I O container thread Once the thread processing the request returns to the I O container the container can safely assume that the request processing is finished and that the client connection can be safely released including all the resources associated with the connection This model is typically sufficient for processing of requests for which the processing resource method execution takes a relatively short time However in cases where a resource method execution is known to take a long time to compute the result server side asynchronous processing model should be used In this model the association between a request processing thread and client connection is broken I O container that handles incoming request may no longer assume that a client connection can be safely closed when a request processing thread returns Instead a facility for explicitly suspending resuming and closing client connections needs to be exposed Note that the use of server side asynchronous processing model
158. ersey java net nonav apidocs snapshot jersey org glassfish jersey client ChunkedInput html on the client side if you are not familiar with ChunkedOutput and ChunkedInput see the Async chapter first for more details In other words our resource method that is used to open a SSE connection to a client does not return individual OutboundEvents Instead a new instance of EventOutput http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventOutput html is returned Event Output is a typed extension of ChunkedOut put OutboundEvent Similarly to receive InboundEvents on a client side Jersey SSE API provides a EventInput that represents a typed extension of ChunkedInput InboundEvent The Jersey server SSE API also contains a SseBroadcaster http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse SseBroadcaster html utility that provides a convenient way of grouping multiple EventOutput instances that represent individual client connections into a group and exposes methods for broadcasting new events to all the client connections grouped in the broadcaster The SseBroadcaster inherits from Broadcaster http jersey java net nonav apidocs snapshot jersey org glassfish jersey server Broadcaster html which is the generic broadcaster implementation of the Jersey chunked message processing facility On the he client side the Jersey SSE API contains additional E
159. ersey org glassfish jersey multipart MultiPart html class or it s subclasses can be used as an entry point to using jersey media multipart module on the client side This class represents a MIME multipart message http en wikipedia org wiki MIME ZMultipart messages and is able to hold an arbitrary number of BodyPart http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart BodyPart html s Default media type is multipart mixed http en wikipedia org wiki MIME Mixed for MultiPart entity and text plain for BodyPart Example 8 42 MultiPart entity final MultiPart multiPartEntity new MultiPart bodyPart new BodyPart entity hello bodyPart new BodyPart new JaxbBean xml MediaType APPLICATION XML TYPE bodyPart new BodyPart new JaxbBean json MediaType APPLICATION JSON TY final WebTarget target Create WebTarget final Response response target request post Entity entity multiPartEntity multiPartEntity getMediaType If you send a multiPartEntity to the server the entity with Content Type header in HTTP message would look like don t forget to register a JSON provider Example 8 43 MultiPart entity in HTTP message Content Type multipart mixed boundary Boundary 1 829077776 1369128119878 Boundary 1 829077776 1369128119878 Content Type text plain hello Boundary 1 829077776 1369128119878 Content Type application xml lt xm
160. ersey org glassfish jersey server ServerProperties html B V_SEND_ERROR_IN_RESPONSE property in your application Example 16 1 Configuring Jersey specific properties for Bean Validation When this property is enabled then our custom ExceptionMapper lt E extends Throwable gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ExceptionMapper html that is handling ValidationExceptions would transform ConstraintViolationException s into ValidationError http jersey java net nonav apidocs snapshot jersey org glassfish jersey server validation ValidationError html s and set this object collection as the new response entity which Jersey is able to sent to the client Four MediaTypes are currently supported when sending ValidationErrors to the client text plain text html application xml application json Note Note You need to register one of the JSON JAXB providers e g MOXy to marshall validation errors to JSON Let s take a look at ValidationError http jersey java net nonav apidocs snapshot jersey org glassfish jersey server validation ValidationError html class to see which properties are send to the client XmlRootElement public final class ValidationError private String message private String messageTemplate private String path private String invalidValue The message property is the interpolated error message messageTempla
161. es 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 Resource scopes Scope AnnotatiopAnnotation full class Description name Request RequestSonpeduassfish jersey proPeysiuitdrfahReqvapploeapedhen no annotation is present scope or none 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 one time in the request processing always the same instance will be used This can happen when a re
162. esponse postResponse 2 helloworldWebTarget request MediaType TEXT PLAIN TYPE 3 post Entity entity A string entity to be POSTed Example summary The following code puts together the pieces used in the earlier examples Example 5 2 Using JAX RS Client API ClientConfig clientConfig new ClientConfig clientConfig register MyClientResponseFilter class clientConfig register new AnotherClientFilter Client client ClientBuilder newClient clientConfig client register ThirdClientFilter class OANA OP C0 F5 LES WebTarget webTarget client target http example com rest webTarget register FilterForExampleCom class 10 WebTarget resourceWebTarget webTarget path resource o MediaType 11 WebTarget helloworldWebTarget resourceWebTarget path helloworld 12 WebTarget helloworldWebTargetWithQueryParam 13 helloworldWebTarget queryParam greeting Hi World 14 15 Invocation Builder invocationBuilder 16 helloworldWebTargetWithQueryParam request MediaType TEXT PLAIN TYP 17 invocationBuilder header some header true 18 19 Response response invocationBuilder get 20 System out printlin response getStatus 21 System out println response readEntity String class Now we can try to leverage the fluent API style to write this code in a more compact way 51 GI Client API Example 5 3 Using
163. esr ofasmnanmere class http jersey java net nonav names that implement application apidocs snapshot jersey org specific resources and providers If glassfish jersey server the property is set the specified ServerProperties html PROVIDER_CLASSNAMES classes will be instantiated and registered as either application JAX RS root resources or providers ServerProperties PROVIDER_CUASSRAPHconfig server pyDefinesr chtepathathat contains http jersey java net nonav application specific resources and apidocs snapshot jersey org providers If the property is set the glassfish jersey server specified packages will be scanned ServerProperties html PROVIDER_CLASSPATH for JAX RS root resources and providers ServerProperties PROVIDER_PAIGKAGHS config server pyDefinesr onactagnere packages http jersey java net nonav that contain application specific apidocs snapshot jersey org resources and providers If the glassfish jersey server property is set the specified ServerProperties html PROVIDER_ PACKAGES packages will be scanned for JAX RS root resources and providers ServerProperties PROVIDER_SCANNSNG RECURSIVErver py Sets dthe secansndm gsinategy r farve http jersey java net nonav package scanning Default value is apidocs snapshot jersey org true glassfish jersey server ServerProperties html PROVIDER_SCANNING_RECURSIVE ServerProperties RESOURCE V Aj d bag TOO DIS ABEErver raBisables Radadate om
164. essageBodyWriter lt T gt is invoked the headers still can be modified in this point and any modification will be reflected in the outbound HTTP message being sent The modification of headers must however happen before a first byte is written to the supplied output stream Another new parameter myBean contains the entity instance to be serialized the type of entity corresponds to generic type of MessageBodyWriter lt T gt Related parameter entityStream contains the entity output stream to which the method should serialize the entity In our case we use JAXB to marshall the entity into the entityStream Note that the ent ityStream is not closed at the end of method the stream will be closed by Jersey Important Do not close the entity output stream in the writeTo method of your MessageBodyWriter lt T gt implementation 7 2 1 3 MessageBodyWriter getSize The method is deprecated since JAX RS 2 0 and Jersey 2 ignores the return value In JAX RS 1 0 the method could return the size of the entity that would be then used for Content Length response header In Jersey 2 0 the Content Length parameter is computed automatically using an internal outbound entity buffering For details about configuration options of outbound entity buffering see the javadoc of MessageProperties http jersey java net nonav apidocs snapshot jersey org glassfish jersey message MessageProperties html property OUTBOUND CONTENT LENGTH BUFFER which configures the
165. estFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientRequestFilter html which would cause that no request will actually be sent to the server at all A new response is passed to the abort method This response will be used and delivered as a result of the request invocation Such a response goes through the client response filters This is similar to what happens on the server side The process is shown in the following example Example 9 4 Client request filter 1 public class CheckRequestFilter implements ClientRequestFilter 2 3 Override 4 public void filter ClientRequestContext requestContext 5 throws IOException 6 if requestContext getHeaders 7 get Client Name null 8 requestContext abortWith 9 Response status Response Status BAD_ REQUEST 10 entity Client Name header must be defined 11 build 12 13 14 The CheckRequestFilter validates the outgoing request It is checked for presence of a Client Name header If the header is not present the request will be aborted with a made up response with an appropriate code and message in the entity body This will cause that the original request will not be effectivelly sent to the server but the actual invocation will still end up with a response as if it would be generated by the server side If there would be any client response filter it would be executed on this response To summarize t
166. ey gf ejb dependencies html Jersey EJB for GlassFish integration Table 2 8 Jersey Examples Examples clipboard https jersey java net project info 2 1 jersey project clipboard dependencies html Jersey clipboard example clipboard programmatic https jersey java net project info 2 1 jersey project clipboard programmatic dependencies html exception mapping https jersey java net project info 2 1 jersey project exception mapping dependencies html Jersey programmatic resource API clipboard example Jersey example showing exception mappers in action helloworld https jersey java net project info 2 1 jersey project helloworld dependencies html Jersey annotated resource class Hello world example 15 Modules and dependencies helloworld programmatic https jersey java net project info 2 1 jersey project helloworld programmatic dependencies html Jersey programmatic resource API Hello world example helloworld pure jax rs https jersey java net project info 2 1 jersey project helloworld pure jax rs dependencies html http trace https jersey java net project info 2 1 jersey project http trace dependencies html Example using only the standard JAX RS APT s and the lightweight HTTP server bundled in JDK Jersey HTTP TRACE support example https clientserver grizzly h
167. ey java net nonav apidocs snapshot Jersey org glassfish jersey server RolesAllowedDynamicFeature html as a provider The following example shows how to register the feature if your deployment is based on a ResourceConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ResourceConfig html Example 14 4 Registering RolesAllowedDynamicFeature using ResourceConfig 1 final ResourceConfig resourceConfig new ResourceConfig MyResource class 2 resourceConfig register RolesAllowedDynamicFeature class Then you can use annotations from package javax annotation security defined by JSR 250 See the following example Example 14 5 Injecting SecurityContext into singletons 1 Path 2 PermitAll 3 public class Resource 4 RolesAllowed user 2 GET 6 public String get return GET 7 8 RolesAllowed admin 9 POST 10 public String post String content return content 11 12 Path sub 13 public SubResource getSubResource 14 return new SubResource 15 16 The resource class Resource defined in the example is annotated with a PermitAll http docs oracle com javaee 6 api javax annotation security PermitAll html annotation This means that all methods in the class which do not this annotation will be permitted for all user groups no restrictions are defined In our example the annotation will only apply to the get SubResource method as it is the
168. fig Validation register ValidationConfigurationContextResolver class Further configuration t register No ode snippet has been taken from Bean Validation example https github com jersey jersey tree master examples bean validation webapp 162 Bean Validation Support 16 4 Validating JAX RS resources and methods JAX RS specification states that constraint annotations are allowed in the same locations as the following annotations MatrixParam QueryParam PathParam CookieParam HeaderParam and Context except in class constructors and property setters Specifically they are allowed in resource method parameters fields and property getters as well as resource classes entity parameters and resource methods return values Jersey provides support for validation see following sections annotated input parameters and return value of the invoked resource method as well as validation of resource class class constraints field constraints where this resource method is placed Jersey does not support and doesn t validate constraints placed on constructors and Bean Validation groups only Default group is supported at the moment 16 4 1 Constraint Annotations The JAX RS Server API provides support for extracting request values and mapping them into Java fields properties and parameters using annotations such as HeaderParam http jax rs spec java net nonav 2 0 apidocs javax ws rs HeaderParam html
169. following chapters describes SSE support in Jersey in more details Important Note that while SSE in Jersey is supported with standard JAX RS resources Jersey SSE APIs are not part of the JAX RS specification SSE support and related APIs are a Jersey specific feature that extends JAX RS 13 3 Jersey Server Sent Events API This chapter briefly describes the Jersey support for SSE Details and examples will be covered in chapters below Jersey contains support for SSE for both server and client SSE in Jersey is implemented as an extension supporting a new media type which means that SSE really treated as just another media type that can be returned from a resource method and processed by the client There is only a minimal additional support for chunked messages added to Jersey which could not be implemented as standard JAX RS media type extension Before you start working with Jersey SSE in order to add support for SSE you need to include the dependency to the SSE media type module 1 lt dependency gt 2 lt grouplid gt org glassfish jersey media lt groupId gt 3 lt artifactId gt jersey media sse lt artifactId gt 4 lt dependency gt Then you need register SseFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse SseFeature html The SseFeature is a feature that can be registered for both the client and the server 135 Server Sent Events SSE Support SseFeatu
170. hFilter username password 20 2 3 Setting Accept header Jersey 1 x way Client client Client create WebResource webResource client resource restURL accept text plain ClientResponse response webResource get ClientResponse class JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL 192 Migrating from Jersey 1 x Response response target request text plain get 20 2 4 Attaching entity to request Jersey 1 x way Client client Client create WebResource webResource client resource restURL ClientResponse response webResource post ClientResponse class payload JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL Response response target request post Entity text payload 20 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 PROPERTIES prop Client client Client create dcc Jersey 2 0 way Client client ClientBuilder newBuilder sslContext sslContext hostnameVerifier hostnameVerifier build 193 Appendix A Configuration Properties A 1 Common client server configuration properties
171. hallerProperties JSON NAMESPACE SEPARATO further configuration are some properties for which Jersey sets the default when MessageBodyReader T _ http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html MessageBodyWriter T http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWiriter html from MOX y is used and they are Tabl e 8 1 Default property values for MOXy MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html javax xml bind MarshallerftJAXB FORM ZTEHB OUTPUT org eclipse persistence jaxb JAXBCQfi amp zxePropertiesdsJSON INCLUDE ROOT org eclipse persistence jaxb Marshd treeProperties4JSON MARSHAL EMPTY GQOLLECTIONS org eclipse persistence jaxb JAXBCQotgxeBPro psetpess dSONnNAMESBAKMLGEBARATOB SDOT 80 Support for Common Media Type Representations Example 8 10 Building client with MOXy JSON feature enabled final Client client ClientBuilder newBuilder The line bellow that registers MOXy feature can be omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled register MoxyJsonFeature class register JsonMoxyConfigurationContextResolver class build Example 8 11 Creating
172. he APIs of WadlGenerator http jersey java net nonav apidocs snapshot jersey org glassfish jersey server wadl WadlGenerator html WadlGeneratorConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server wadl WadlGeneratorConfig html as well as any related classes The API changes may impact your code if you are using a custom WadlGenerator or plan to implement one 158 Chapter 16 Bean Validation Support 16 1 16 2 Validation is a process of verifying that some data obeys one or more pre defined constraints This chapter describes support for Bean Validation http beanvalidation org in Jersey in terms of the needed dependencies configuration registration and usage For more detailed description on how JAX RS provides native support for validating resource classes based on the Bean Validation refer to the chapter in the JAX RS spec http jcp org en jsr detail id 339 Bean Validation Dependencies Bean Validation support in Jersey is provided as an extension module and needs to be mentioned explicitly in your pom xm1 file in case of using Maven dependency groupId org glassfish jersey ext groupId artifactId jersey bean validation artifactId version 2 1 version dependency Note If youre not using Maven make sure to have also all the transitive dependencies see jersey bean validation https jersey java net project info 2 1 jersey project jersey bean
173. he WebTarget http jax rs spec java net nonav 2 0 apidocs javax ws rs client WebTarget html is built In this case a request to the web target is not made directly in the code instead the web target instance is used to initialize a new EventSource instance The second parameter false of the EventSource constructor tells the EventSource to not automatically connect to the target as part of its initialization logic in the constructor The connection is established later by calling event Source open A custom EventListener http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventListener html implementation is used to listen to and process incoming SSE events The method getData Class says that the event data should be de serialized from a received InboundEvent http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse InboundEvent html instance into a String Java type This method call internally executes MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html which de serializes the event data This is similar to reading an entity from the Response http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response html by readEntity Class The method getData can throw an IO exception The custom event source listener is registered in the event source via EventSource register EventListener String method The nex
174. he filters the request will be sent to the remote resource Let s say the resource then returns an HTTP 200 message with a plain text response content that contains the value sent in the request greet ing query parameter Now we can observe the returned response 50 LH Client API 5 3 6 1 System out println response getStatus 2 System out println response readEntity String class which will produce the following output to the console 200 Hi World As we can see the request was successfully processed code 200 and returned an entity representation is Hi World Note that since ve have configureda MyClientResponseFilter in the resource target when response readEntity String class gets called the response returned from the remote endpoint is passed through the response filter chain including the MyClientResponseFilter and entity interceptor chain and at last a proper MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html is located to read the response content bytes from the response stream into a Java St ring instance Check Chapter 9 Filters and Interceptors to lear more about request and response filters and entity interceptors Imagine now that you would like to invoke a POST request but without any query parameters You would just use the he1loworldWebTarget instance created earlier and call the post instead of get 1 R
175. he named body part as input If there is no named part present and there is a default value present as declared by DefaultValue http jax rs spec java net nonav 2 0 apidocs javax ws rs DefaultV alue html then the media type will be set to text plain The value of the parameter will be the result of reading using the message body reader given the type T the media type text plain and the UTF 8 encoded bytes of the default value as input If there is no message body reader available and the type T conforms to a type specified by FormParam http jax rs spec java net nonav 2 O apidocs javax ws rs FormParam html then processing is performed as specified by FormParam where the values of the form parameter are String instances produced by reading the bytes of the named body parts utilizing a message body reader for the St ring type and the media type text plain If there is no named part present then processing is performed as specified by FormParam Example 8 48 Use of FormDataParam annotation POST Consumes MediaType MULTIPART_FORM_DATA_TYP public String postForm Et DefaultValue true FormDataParam enabled boolean enabled FormDataParam data FileData bean FormDataParam file InputStream file FormDataParam file FormDataContentDisposition fileDisposition In the example above the server consumes amultipart form data request entity body that contains one optional named body part
176. he workflow for any client request invoked from the client API the client request filters ClientRequestFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientRequestFilter html are executed that could manipulate the request If not aborted the outcoming request is then physically sent over to the server side and once a response is received back from the server the client response filters ClientResponseFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientResponseFilter html are executed that might again manipulate the returned response Finally the response is passed back to the code that invoked the request If the request was aborted in any client request filter then the client server communication is skipped and the aborted response is used in the response filters 9 3 Interceptors Interceptors share a common API for the server and the client side Whereas filters are primarily intended to manipulate request and response parameters like HTTP headers URIs and or HTTP methods interceptors are intended to manipulate entities via manipulating entity input output streams If you for example need to encode entity body of a client request then you could implement an interceptor to do the work for you There are two kinds of interceptors ReaderInterceptor http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ReaderInterceptor html and WriterInterceptor http jax rs spec java net nonav
177. her 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 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
178. hod 73 JAX RS Entity Providers 7 5 Default Jersey Entity Providers Jersey internally contains entity providers for these types with combination of media types in brackets byte String http docs oracle com javase 6 docs api java io String html InputStream http docs oracle com javase 6 docs api java io InputStream html Reader http docs oracle com javase 6 docs api java io Reader html File http docs oracle com javase 6 docs api java io File html DataSource http docs oracle com javase 6 docs api javax activation DataSource html Source http docs oracle com javase 6 docs api javax xml transform Source html text xml application xml and media types of the form application xml JAXBElement http docs oracle com javase 6 docs api javax xml bind JAXBElement html text xml application xml and media types of the form application 4xml MultivaluedMap K V http jax rs spec java net nonav 2 0 apidocs javax ws rs core MultivaluedMap html application x www form urlencoded Form http jax rs spec java net nonav 2 0 apidocs javax ws rs core Form html application x www form urlencoded StreamingOutput http jax rs spec java net nonav 2 0 apidocs javax ws rs core StreamingOutput html this class can be used as an lightweight MessageBodyWriter lt T gt that can be returned from aresource method Boolean http docs oracle
179. hot jersey org glassfish jersey server mvc Viewable html class If a method is annotated with Template and is also returning a Viewable instance then the values resolvingClass fromthe Viewable instance take precedence over those defined in the annotation Producible media types are determined from the method s GP roduces annotation Note Implicit view templates support works dynamically as is the case for explicit MVC so it is possible if the deployment system is configured correctly to add or modify templates while the application is running 17 4 JSP As stated earlier Jersey provides support for JSP templates in jersey mvc jsp https jersey java net project info 2 1 jersey project jersey mvc jsp dependencies html extension module There is a JSP template processor that resolves absolute template references to processable template references represented as JSP pages as follows Procedure 17 1 Resolving JSP processable template reference 1 if the absolute template reference does not end in jsp append this suffix to the reference and 2 ifServlet getResource returns a non nu11 value for the appended reference then return the appended reference as the processable template reference otherwise return nu11 to indicate the absolute reference has not been resolved by the JSP template processor 178 MVC Templates Thus the absolute template reference com foo Foo index would be resolved to com foo Foo index
180. hrowable method on the invocation callback is invoked even in case a non 2xx HTTP error code is returned As with the synchronous client API you can retrieve the response entity as a Java type directly without requesting a Response first In case of an InvocationCallback you need to set its generic type to the expected response entity type instead of using the Response type as demonstrated in the example bellow Example 10 8 Client async callback for specific entity 1 final Future lt String gt entityFuture target path http example com resource 2 request async get new InvocationCallback lt String gt 3 Override 4 public void completed String response 5 System out println Response entity response receiv 6 7 8 Override 9 public void failed Throwable throwable 10 System out println Invocation failed 11 throwable printStackTrace 12 13 14 System out println entityFuture get Here the generic type of the invocation callback information is used to unmarshall the HTTP response content into a desired Java type 121 Asynchronous Services and Clients Important Please note that in this case the method failed Throwable throwable would be invoked even for cases when a server responds with a non HTTP 2xx HTTP error code This is because in this case the user does not have any other means of finding out that the server returned an error response 10 2 2 Chun
181. html BV DISABLE VALIDATE ON EXECUTABLE OVERRIDE CHECK ServerProperties BV SEND ERROR HiibRis SPONSE validation errors in response entity to the client http jersey java net nonav More on this in Section 16 7 1 ValidationError apidocs snapshot jersey org glassfish jersey server ServerProperties html BV SEND ERROR IN RESPONSE Example 16 1 Configuring Jersey specific properties for Bean Validation 1 new ResourceConfig 2 Now you can expect validation errors to be sent to the client 3 property ServerProperties BV SEND ERROR IN RESPONSE true 4 ValidateOnExecution annotations on subclasses won t cause errors 5 6 7 property ServerProperties BV DISABLE VALIDATE ON EXECUTABLE OVERRIDE CHEC Further configuration of ResourceConfig register Customization of the Validator used in validation of resource classes methods can be done using ValidationConfig class and exposing it via ContextResolver lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ContextResolver html mechanism as shown in Example 16 2 Using ValidationConfig to configure Validator You can set custom instances for the following interfaces from the Bean Validation API 160 Bean Validation Support MessagelInterpolator http docs jboss org hibernate beanvalidation spec 1 1 api javax validation MessagelInterpolator html interpolates a given c
182. 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 31 JAX RS Application Resources and Sub Resources Example 3 17 Sub resource methods 1 Singleton 2 Path printers 3 public class PrintersResource 4 5 GET 6 Produces application json application xml y public WebResourceList getMyResources 8 9 GET Path list 10 GProduces application json application xml deal public WebResourceList getListOfPrinters T2 13 GET Path jMakiTable 14 Produces application json 15 public PrinterTableModel getTable 16 17 GET GPath jMakiTree 18 Produces application json 19 public TreeModel getTr O 20 21 GET Path ids printerid 22 Produces application json application xml 23 public Printer getPrinter 8PathParam printerid String printerId 24 25 PUT Path ids printerid 26 Consumes application json application xml 27 pu
183. http https Simple Http Container 10 Modules and dependencies jersey java net project info 2 1 jersey project jersey container simple http dependencies html Table 2 3 Jersey Connectors Connectors jersey grizzly connector https jersey java net project info 2 1 jersey project jersey grizzly connector dependencies html Jersey Client Transport via Grizzly jersey apache connector https jersey java net project info 2 1 jersey project jersey apache connector dependencies html Jersey Client Transport via Apache Table 2 4 Jersey Media Media jersey media json jackson https jersey java net project info 2 1 jersey project jersey media json jackson dependencies html Jersey JSON Jackson entity providers support module jersey media json jettison https jersey java net project info 2 1 jersey project jersey media json jettison dependencies html Jersey JSON Jettison entity providers support module jersey media json processing https jersey java net project info 2 1 jersey project jersey media json processing dependencies html Jersey JSON P JSR 353 entity providers support proxy module jersey media moxy https Jersey JSON entity providers support module based on EclipseLink MOXy 11 Modules and dependencies jersey java net project info 2
184. ically 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 wadl 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 jax 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 Example 3 4 Specifying output MIME type 1 Path myResource 2 Produces text plain 3 public class SomeResource 4 GET 5 public String doGetAsPlainText 6 7 8 9 GET 10 Produces text html 11 public String doGetAsHtml 12 13 14 25 JAX RS Application Resources and Sub Resources 3 1 4 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 ht
185. iders to group together multiple different extension providers and or configuration properties in order to simplify the registration and configuration of the provided feature by the end users For example MoxyJsonFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy json MoxyJsonFeature html can be register to enable and configure JSON binding support via MOXy library 5 5 Client Transport Connectors By default the transport layer in Jersey is provided by HttpUrlConnection This transport is implemented in Jersey via HttpUrlConnector http jersey java net nonav apidocs snapshot jersey org glassfish jersey client HttpUrlConnector html that implements Jersey specific Connector http jersey java net nonav apidocs snapshot jersey org glassfish jersey client spi Connector html SPI You can implement and or register your own Connector instance to the Jersey Client implementation that will replace the default Ht t pUr1Connect ion based transport layer Jersey provides several alternative client transport connector implementations that are ready to use You can use ApacheConnector http jersey java net nonav apidocs snapshot jersey org glassfish jersey apache ApacheConnector html add a maven dependency to org glassfish jersey connectors jersey apache connector or GrizzlyConnector http jersey java net nonav apidocs snapshot jersey org glassfish jersey grizzly GrizzlyConnector html add a maven dependency
186. ies LANGUAGE_MA PE GS config server labefineseMamappings of URI http jersey java net nonav extensions to languages apidocs snapshot jersey org The property is used by UriConnegFilter http 195 Configuration Properties Constant Value Description glassfish jersey server jersey java net nonav apidocs ServerProperties html LANGUAGE_MAPPINGS snapshot jersey org glassfish jersey server filter UriConnegFilter html ServerProperties MEDIA_TYPE_MAPPENGSonfig server meDefifeseMmappings of URI http jersey java net nonav extensions to media types apidocs snapshot jersey org The property is used glassfish jersey server by UriConnegFilter http ServerProperties htnl MEDIA TYPE MAPPINGS jersey java net nonav apidocs snapshot jersey org glassfish jersey server filter UriConnegFilter html ServerProperties METAINF_SERVEGES amp LOOK UPgDiSABbEeMe Dasahles e rv MEBAdNMgerweasye r http jersey java net nonav lookup on server Default value is apidocs snapshot jersey org false glassfish jersey server ServerProperties htnl METAINH SERVICES LOOKUP DISABLE ServerProperties MOXY_JSON_FEAA4 RE d2IS ABLE i sableMabysibles coafigeration of MOXy http jersey java net nonav Json feature Default value is apidocs snapshot jersey org false glassfish jersey server ServerProperties html MOXY JSON FEATURE DISABLE ServerProperties PROVIDER_CUASSNAMESnfig server pyDefin
187. ing useful client side filters that you may want to use in your applications 53 Client API CsrfProtectionFilter http jersey java net nonav apidocs snapshot jersey org glassfish jersey client filter CsrfProtectionFilter html Cross site request forgery protection filter adds X Requested By to each state changing request EncodingFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey client filter EncodingFeature html Feature that registers encoding filter which use registered ContentEncoder http jersey java net nonav apidocs snapshot jersey org glassfish jersey common spi ContentEncoder html s to encode and decode the communication The encoding decoding is performed in interceptor you don t need to register this interceptor Check the javadoc of the EncodingFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey client filter EncodingFeature html in order to use it HttpBasicAuthFilter http jersey java net nonav apidocs snapshot jersey org glassfish jersey client filter HttpBasicAuthFilter html HTTP Basic Authentication filter see below Note that these features are provided by Jersey but since they use and implement JAX RS API the features should be portable and run in any JAX RS implementation not just Jersey See Chapter 9 Filters and Interceptors chapter for more information on filters and interceptors 5 7 Securing a Client This section de
188. inherited or overridden and ignored For Bean Validation annotations Jersey follows the constraint annotation rules defined in the Bean Validation specification ValidateOnExecution According to Bean Validation specification validation is enabled by default only for the so called constrained methods Getter methods as defined by the Java Beans specification are not constrained methods so they will not be validated by default The special annotation ValidateOnExecution can be used to selectively enable and disable validation For example you can enable validation on method getEmail shown in Example 16 11 Validate getter on execution Example 16 11 Validate getter on execution Path class MyResourceClass Email ValidateOnExecution public String getEmail return email The default value for the type attribute of ValidateOnExecution is IMPLICIT which results in method get Email being validated 167 Bean Validation Support Note According to Bean Validation specification ValidateOnExecution cannot be overridden once is declared on a method i e in subclass sub interface and in this situations a ValidationException should be raised This default behaviour can be suppressed by setting ServerProperties BV DISABLE VALIDATE ON EXECUTABLE OVERRIDE CHECK http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html B V_DISABLE
189. ions contains annotations that are either attached to the resource method and or annotations that are attached to the entity by building response like in the following piece of code Example 7 4 Example of assignment of annotations to a response entity 1 Path resource 2 public static class AnnotatedResource 3 4 GET 5 public Response get 6 Annotation annotation AnnotatedResource class 7 getAnnotation Path class 8 return Response ok 9 entity Entity new Annotation annotation build 10 11 In the example above the MessageBodyWriter lt T gt would get annotations parameter containing a JAX RS GET annotation as it annotates the resource method and also a Path annotation as it is passed in the response but not because it annotates the resource only resource method annotations are included In the case of MyResource and method getMyBean the annotations would contain the GET http jax rs spec java net nonav 2 O apidocs javax ws rs GET html and the Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation The last parameter of the isWriteable method is the mediaType which is the media type attached to the response entity by annotating the resource method with a Produces annotation or the request media type specified in the JAX RS Client API In our example the media type passed to providers for the resource MyResource and method getMyBean would be
190. ipart features you need to add jersey media multipart module to your pom xml file dependency groupId org glassfish jersey media c groupId artifactId jersey media multipart artifactId version 2 1 version dependency If you re not using Maven make sure to have all needed dependencies see jersey media multipart https jersey java net project info 2 1 jersey project jersey media multipart dependencies html on the class path 8 3 1 2 Registration Before you can use capabilities of the jersey media multipart module in your client server code you need to register MultiPartFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart MultiPartFeature html Example 8 40 Building client with MultiPart feature enabled final Client client ClientBuilder newBuilder register MultiPartFeature class build 96 Support for Common Media Type Representations Example 8 41 Creating JAX RS application with MultiPart feature enabled Create JAX RS application final Application application new ResourceConfig packages org glassfish jersey examples multipart register MultiPartFeature class 8 3 1 3 Examples 8 3 2 Jersey provides an multipart webapp example https github com jersey jersey tree master examples multipart webapp on how to use multipart features Client MultiPart http jersey java net nonav apidocs snapshot j
191. is specified in P roduces annotation and the method returns an instance of My JaxbBean which JAXB is able to process Resulting JSON in this case would look like name Agamemnon age 32 A proper use of JAXB annotations itself enables you to control output JSON format to certain extent Specifically renaming and omitting items is easy to do directly just by using JAXB annotations For example the following example depicts changes in the above mentioned MyJaxbBean that will result in king Agamemnon JSON output 76 Support for Common Media Type Representations Example 8 3 Tweaking JSON format using JAXB 1 XmlRootElement 2 public class MyJaxbBean 3 4 XmlElement name king 5 public String name 6 y XmlTransient 8 public int age 9 10 several lines removed 11 Media modules that support this approach are MOXy Jackson Jettison 8 1 1 3 Low level based JSON support JSON Processing API is a new standard API for parsing and processing JSON structures in similar way to what SAX and StAX parsers provide for XML The API is part of Java EE 7 and later Another such JSON parsing processing API is provided by Jettison framework Both APIs provide a low level access to producing and consuming JSON data structures By adopting this low level approach you would be working with JsonObject or JSONOb ject respectively and or JsonArray or JSONArray respectively classes when processing your JS
192. istration of MoxyJsonFeature besides the generic CommonProperties FEATURE AUTO DISCOVERY DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE an the its client server variants CommonProperties MOXY JSON FEATURE DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey CommonProperties html MOXY_JSON_FEATURE_DISABLE e ServerProperties MOXY JSON FEATURE DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html MOXY JSON FEATURE DISABLE ClientProperties MOXY JSON FEATURE DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html MOXY_JSON_FEATURE_DISABLE 78 Support for Common Media Type Representations Note A manual registration of any other Jersey JSON provider feature except for Java API for JSON Processing JSON P disables the automated enabling and configuration of MoxyJsonFeature To configure MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html s MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html s provided by MOXy you can simply create an instance of MoxyJsonConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey moxy json MoxyJsonConfig html
193. ject that is created from the content of the input stream based on the representation type information For example an entity created from an input stream that contains data represented as a XML document can be converted to a custom JAXB bean Similar concept is supported for the outbound entities An entity returned from the resource method in the form of an arbitrary Java object can be serialized by Jersey into a container output stream as a specified representation Of course while JAX RS implementations do provide default support for most common combinations of Java type and it s respective on the wire representation formats JAX RS implementations do not support the conversion described above for any arbitrary Java type and any arbitrary representation format by default Instead a generic extension concept is exposed in JAX RS API to allow application level customizations of this JAX RS runtime to support for entity conversions The JAX RS extension API components that provide the user level extensibility are typically referred to by several terms with the same meaning such as entity providers message body providers message body workers or message body readers and writers You may find all these terms used interchangeably throughout the user guide and they all refer to the same concept In JAX RS extension API or SPI service provider interface if you like the concept is captured in 2 interfaces One for handling inbound entity representation t
194. jected by the Suspended annotation and not by Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html as Suspended does not only inject response but also says that the method is executed in the asynchronous mode By the AsyncResponse parameter into a resource method we tell the Jersey runtime that the method is supposed to be invoked using the asynchronous processing mode that is the client connection should not be automatically closed by the underlying I O container when the method returns Instead the injected AsyncResponse instance that represents the suspended client request connection will be used to explicitly send the response back to the client using some other thread In other words Jersey runtime knows that when the asyncGet method completes the response to the client may not be ready yet and the processing must be suspended and wait to be explictly resumed with a response once it becomes available Note that the method asyncGet returns voidin our example This is perfectly valid in case of an asynchronous JAX RS resource method even for a GC GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html method as the response is never returned directly from the resource method as its return value Instead the response is later returned using AsyncResponse instance as it is demonstrated in the example The asyncGet resource method starts a new thread and exits from the method In that state the r
195. jersey project webapp example parent json processing webapp dependencies html Jersey JSON P JSR 353 example managed beans webapp https jersey java net project info 2 1 jersey project webapp example parent managed beans webapp dependencies html Jersey Managed Beans Web Application example managed client simple webapp https jersey java net project info 2 1 jersey project webapp example parent managed client simple webapp dependencies html Jersey Managed Client Simple Webapp example managed client webapp https jersey java net project info 2 1 jersey project webapp example parent managed client webapp dependencies html Jersey managed client web application example multipart webapp https jersey java net project info 2 1 Jersey Multipart example 21 Modules and dependencies jersey project webapp example parent multipart webapp dependencies html sse item store webapp https jersey java net project info 2 1 jersey project webapp example parent sse item store webapp dependencies html Jersey SSE based item store example 22 Chapter 3 JAX RS Application Resources and Sub Resources This chapter presents an overview of the core JAX RS concepts resources and sub resources The JAX RS 2 0 JavaDoc can be found online here http jax rs spec java net nonav 2 0 apidocs i
196. ked input In an earlier section the ChunkedOut put was described It was shown how to use a chunked output on the server In order to read chunks on the client the ChunkedInput http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ChunkedInput html can be used to complete the story You can of course process input on the client as a standard input stream but if you would like to leverage Jersey infrastructure to provide support of translating message chunk data into Java types using a ChunkedInput is much more straightforward See the usage of the ChunkedInput in the following example Example 10 9 ChunkedInput example 1 final Response response target path http example com resource 2 request get 3 final ChunkedInput lt String gt chunkedInput 4 response readEntity new GenericType lt ChunkedInput lt String gt gt 5 String chunk 6 7 8 9 while chunk chunkedInput read null System out println Next chunk received chunk The response is retrieved in a standard way from the server The entity is read as a ChunkedInput entity In order to do that the GenericEntity lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs core GenericEntity html is used to preserve a generic information at run time If you would not use GenericEntity lt T gt Java language generic type erasure would cause that the generic information would get lost at compile time and
197. l now namely Viewable http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc Viewable html and Template http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc Template html These classes determines which approach explicit implicit you would be taking when working with Jersey MVC templating support 17 3 1 Viewable Explicit View Templates In this approach a resource method explicitly returns a reference to a view template and the data model to be used For this purpose the Viewable http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc Viewable html class has been introduced in Jersey 1 and is also present under a different package in Jersey 2 A simple example of usage can be seen in Example 17 5 Using Viewable in a resource class Example 17 5 Using Viewable in a resource class package com foo Path foo public class Foo GGET public Viewable get return new Viewable index FOO In this example the Foo JAX RS resource class is the controller and the V iewable instance encapsulates the provided data model FOO string and a named reference to the associated view template index The template name reference index is a relative value that Jersey will resolve to its absolute template reference using the fully qualified class name of Foo more on resolving relative template name to the absolute
198. l version 1 0 encoding UTF 8 standalone yes gt lt jaxbBean gt lt value gt xml lt value Boundary 1 829077776 1369128119878 Content Type application json value json Boundary 1 829077776 1369128119878 97 Support for Common Media Type Representations When working with forms e g media type mult ipart form data and various fields in them there is a more convenient class to be used FormDataMultiPart http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart FormDataMultiPart html It automatically sets the media type for the FormDataMultiPart entity to mnultipart form data and Content Disposition header to FormDataBodyPart body parts Example 8 44 FormDataMultiPart entity final FormDataMultiPart multipart new FormDataMultiPart field hello hello field xml new JaxbBean xml field json new JaxbBean json MediaType APPLICATION JSON TYPE final WebTarget target Create WebTarget final Response response target request post Entity entity multipart multipart To illustrate the difference when using FormDataMultiPart instead of FormDataBodyPart you can take a look at the FormDataMultiPart entity from HTML message Example 8 45 FormDataMultiPart entity in HTTP message Content Type multipart form data boundary Boundary 1 511262261 1369143433608 Boundary 1 511262261 1369143433608 Content Type text plain Content Disposition
199. ld 0 t Hello world 1 t Hello world 2 t Hello world 3 t Hello world 4 t Hello world 5 t Hello world 6 t Hello world 7 t Hello world 8 t Hello world 9 4452883555338 ko Eje Ej ee ee ejna 2E When browsing through the Jersey SSE API documentation you may have noticed that the EventSource http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventSource html implements EventListener http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventListener html and provides an empty implementation for the onEvent InboundEvent inboundEvent listener method This adds more flexibility to the Jersey client side SSE API Instead of defining and registering a separate event listener in simple scenarios you can also choose to derive directly from the Event Source and override the empty listener method to handle the incoming events This programming model is shown in the following example Example 13 4 Overriding EventSource onEvent InboundEvent method 1 Client client ClientBuilder newBuilder 2 register SseFeature class build 3 WebTarget target client target http example com events 4 EventSource eventSource new EventSource target 5 Override 6 public void onEvent InboundEvent inboundEvent 7 if message to client equals inboundEvent getName
200. le overloaded versions of the method that support registration of feature and provider classes or instances Once a Client Config instance is configured it can be passed to the C1ientBuilder to create a pre configured Client instance Note that the Jersey ClientConfig supports the fluent API model of Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html With that the code that configures a new client instance can be also written using a more compact style as shown below Client client ClientBuilder newClient new ClientConfig register MyClientResponseFilter class register new AnotherClientFilter A WN HP The ability to leverage this compact pattern is inherent to all JAX RS and Jersey Client API components Since Client implements Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html interface too it can be configured further even after it has been created Important is to mention that any configuration change done on a Client instance will not influence the ClientConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientConfig html instance that was used to provide the initial Client instance configuration at the instance creation time The next piece of code shows a configuration of an existing Client instance 1 client register ThirdClientFilter class Similarly to earlier examples since Clie
201. le providing support for proxy based high level client API jersey servlet portability https jersey java net project info 2 1 jersey project jersey servlet portability dependencies html jersey wadl doclet https jersey java net project info 2 1 jersey project jersey wadl doclet dependencies html Library that enables writing web applications that run with both Jersey 1 x and Jersey 2 x servlet containers A doclet that generates a resourcedoc xml file this file contains the javadoc documentation of resource classes so that this can be used for extending generated wadl with useful documentation Table 2 6 Jersey Test Framework Test Framework jersey test framework core https jersey java net project info 2 1 jersey project jersey test framework core dependencies html Jersey Test Framework Core jersey test framework provider bundle https jersey java net project info 2 1 jersey project project jersey test framework provider bundle dependencies html Jersey Test Framework Providers Bundle jersey test framework provider default client https jersey java net project info 2 1 jersey project project jersey test framework provider Jersey Test Framework Default Client Provider 13 Modules and dependencies default client dependencies html jersey test framework provider external https je
202. lse DgroupId com exampl DartifactId simple servic Dpackage com example DarchetypeVersion 2 1 Feel free to adjust the groupId package and or art ifactId of your new project Alternatively you can change it by updating the new project pom xml once it gets generated 1 2 Exploring the Newly Created Project Once the project generation from a Jersey maven archetype is successfully finished you should see the new simple service project directory created in your current location The directory contains a standard Maven project structure Project build and management configuration is described in the pom xml located in the project root directory Project sources are located under src main java Getting Started Project test sources are located under src test java There are 2 classes in the project source directory in the com example package The Main class is responsible for bootstrapping the Grizzly container as well as configuring and deploying the project s JAX RS application to the container Another class in the same package is MyResource class that contains implementation of a simple JAX RS resource It looks like this OANA OBWN L2 Ne 10 11 12 13 14 T5 16 17 18 19 20 21 22 23 24 25 packag import import import import com javax javax javax javax xample WS WS WS WS Root resourc 2 rS GET rs Path rs Produces rs core MediaType
203. lves given relative URI to an absolute URI using application context URI as the base URI Urilnfo relativize java net URI http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html relativize java net URI then transforms an absolute URI to a relative one using again the applications context URI as the base URI UriBuilder also introduces a set of methods that provide ways of resolving URI templates by replacing individual templates with a provided value s A short example 1 final URI uri UriBuilder fromUri http host path q param 2 resolveTemplate host localhost 3 resolveTemplate path myApp 4 5 6 resolveTemplate param value build uri toString returns http localhost myApp q value See the UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html javadoc for more details 11 3 Link JAX RS 2 0 introduces Link http jax rs spec java net nonav 2 0 apidocs javax ws rs core Link html class which serves as a representation of Web Link defined in RFC 5988 http tools ietf org html 125 URIs and Links rfc5988 The JAX RS Link class adds API support for providing additional metadata in HTTP messages for example if you are consuming a REST interface of a public library you might have a resource returning description of a single book Then you can include links to related resources such as a book category author
204. ly a view of the client configuration and not a configuration state copy These principles are important in the client API and will be used in 48 Client API the following sections too For example you can construct a common base configuration for all clients in our case it would be client Config and then reuse this common configuration instance to configure multiple client instances that can be further specialized Similarly you can use an existing client instance configuration to configure another client instance without having to worry about any side effects in the original client instance 5 3 3 Targeting a web resource Once you have a Client instance you can create a WebTarget from it 1 WebTarget webTarget client target http example com rest A Client contains several target methods that allow for creation of WebTarget instance In this case we re using target String uri version The uri passed to the method asa String is the URI of the targeted web resource In more complex scenarios it could be the context root URI of the whole RESTful application from which WebTarget instances representing individual resource targets can be derived and individually configured This is possible because JAX RS WebTarget also implements Configurable 1 WebTarget webTarget client target http example com rest 2 webTarget register FilterForExampleCom class The configuration principles used in JAX RS
205. mParam html annotation is special and may only be utilized on resource and sub resource methods This is because it extracts information from a request entity 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 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 39 JAX RS Application Resources and Sub Resources 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 40 Chap
206. master examples json jackson on how to use Jackson to consume produce JSON 8 1 5 Jettison JAXB approach for de serializing JSON in Jettison module provides in addition to using pure JAXB configuration options that could be set on an JettisonConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey jettison JettisonConfig html instance The instance could be then further used to create a JettisonJaxbContext http jersey java net nonav apidocs snapshot jersey org glassfish jersey jettison JettisonJaxbContext html which serves as a main configuration point in this area To pass your specialized JettisonJaxbContext to Jersey you will finally need to implement a JAXBContext ContextResolver lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ContextResolver html see below 8 1 5 1 Dependency To use Jettison as your JSON provider you need to add jersey media json jettison module to your pom xml file dependency groupId org glassfish jersey media c groupId artifactId jersey media json jettison artifactId version 2 1 version dependency If you re not using Maven make sure to have all needed dependencies see jersey media json jettison https jersey java net project info 2 1 jersey project jersey media json jettison dependencies html on the classpath 8 1 5 2 JSON Notations JettisonConfig allows you to use two JSON notations Each of these not
207. mem emm henm hen eee rene 185 19 T Checking Qut the SouUrCE 1 e eir recorte octo ever e ete o teo Pepe teen 185 19 2 Buildmg the Source 2 3 eI RE ne es v NOSE I ete caede ea e og eed 185 Jersey 2 1 User Guide 5p 185 19 4 Using NetBeans 52 e eR ox don bee tuc Mak T Ud tse 186 20 Migrating from Jersey T xc iic oa ceded ettet een aa an dest iet dest tee ces ERR Rr coe es een 187 20 1 Server ABI ouest e ENERO MU Wee te M UR Te 187 20 3 1 Injecting custom ObJects roer rr eoe Re rp re ten o Eee er pe estonneeds 187 20 1 2 ResourceConbig Reload de e eter er t t e N 189 20 1 3 MessageBodyReaders and MessageBodyWriters ordering ee 190 20 2 Migrating Jersey Client APD eo ane e a E A HH HH Ime ree 191 20 2 1 Making a simple client request sssssee HH 192 20 22 Registerimp filters ns ren T ee ep rU OEC UD I I dert 192 20 2 3 Setting Accept header 55 isset atit Debe Or EIE e Saee 192 20 2 4 Attaching entity to request 2 0 0 ee eee ee cece HH emere 193 20 2 5 Setting SSLContext and or HostnameVerifier eseeee 193 A Configuration Propertie S es rrena E LEHRER es et eq tris de ssb es uae epe eU Ee 194 A 1 Common client server configuration properties ssssse seen eenes 194 A 2 Server configuration properties sssssessesseeeee e ene m emen hee nhe rre 194 A 3 Client configuration properties enepar He Hm
208. method returning text plain media type that will return a response with a string entity containing the list of methods deployed on this resource this means that instead of WADL you can use this OPTIONS method to get similar information in a textual representation Another OPTIONS method returning will return a response with no entity and A110w header that will contain list of methods as a String The last OPTIONS method producing application vnd sun wadl xml returns a WADL description of the resource count ry id As you can see all OPTIONS methods return information about the resource to which the HTTP OPTIONS request is made Second resource with a path application wadl has again similar OPTIONS methods and one GET method which return this WADL There is also a sub resource with a path defined by path param path This means that you can request a resource on the URI http localhost 9998 application wadl something This is used only to return an external grammar if there is any attached Such a external grammar can be for example an XSD schema of the response entity which if the response entity is a JAXB bean An external grammar support via Jersey extended WADL support is described in sections below Let s now send an HTTP OPTIONS request to country id resource using the the curl command curl X OPTIONS H Allow application vnd sun wadl 4xml v http localhost 9998 country 15 We should see a WADL
209. mework provider inmemory artifactlId lt version gt 2 1 lt version gt lt dependency gt HttpServer from Oracle JDK is another supported test container lt dependency gt groupId org glassfish jersey test framework providers groupId artifactlId jersey test framework provider jdk http artifactlId version 2 1 version dependency 182 Jersey Test Framework e Simple container org simpleframework http is another light weight HTTP container that integrates with Jersey and is supported by Jersey Test Framework lt dependency gt groupId org glassfish jersey test framework providers groupId lt artifactId gt jersey test framework provider simple lt artifactId gt lt version gt 2 1 lt version gt lt dependency gt 18 3 Advanced features 18 3 1 JerseyTest Features JerseyTest provide enable http jersey java net nonav apidocs snapshot jersey org glassfish jersey test JerseyTest html enable java lang String forceEnable http jersey java net nonav apidocs snapshot jersey org glassfish jersey test JerseyTest html forceEnable java lang String and disable http jersey java net nonav apidocs snapshot jersey org glassfish jersey test JerseyTest html disable java lang String methods that give you control over configuring values of the properties defined and described in the Test Properties class A typical code that overrides the default
210. ml 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 doGetAsHtm1 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 GProduces application xml application json public String doGetAsXmlOrJson Oe WN PF The doGetAsXmlOrJson method will get invoked if either of the media types application xml and application json are acceptable If both are equally acceptable then the former will be chose
211. mm here 197 vi List of Tables 2 1 Jersey COre z iode P pe Rte ter el e at se DER ribus iete ea but sete E E aE 9 2 2 Ti M Girl M M ESS 10 2 3 Jersey Connectors iiec eterne rd err E Ri eate RANEES EES EE PRV sess 11 ZA Jersey Media irei oon RE aet Hest bet EET ERES Haka cone NR ET NOD ESES 11 2 5 Jersey Extensions 5 veinte t resto eet kr tere orbe manag re bata teet loreet greci bed 12 2 6 Jersey Test Framework eodcm ere EES E pee ide edge tege eee Deor ete ge esp gne 13 2 7 Jersey Glassfish Bundles eret e err Rr oT EESE PRI NEO ERES ES TERO eR 15 2 8 Jersey Examples oi ene tete eee E tee etre tipo beets 15 2 9 Jersey Examples WebADpps oct tete nor te be CHE aO ge EE ERE DEE 19 3 1 Resource SCOPES oi RR L ee LAT i es ALPS cease 35 3 2 Overview of injection types ingen Heer EESE ESE SE e ERN RR PERPE EEST Phe REIR IS 37 8 1 Default property values for MOXy MessageBodyReader lt T gt MessageBodyWriter T 80 20 1 Mapping of Jersey 1 x to JAX RS 2 0 client classes ssss HMM 191 A 1 List of common configuration properties sesssssesee HH emere 194 A 2 List of server configuration properties ssssssessessee em em mee He men nennen 195 A 3 List of client configuration properties 2 0 0 0 ccc ee cece ence HH eene 197 vil List of Examples 3 1 Simple hello world root resource class
212. mmon Media Type Representations lt dependency gt lt grouplid gt org glassfish jersey media lt groupId gt lt artifactId gt jersey media json jackson lt artifactId gt lt version gt 2 1 lt version gt lt dependency gt If you re not using Maven make sure to have all needed dependencies see jersey media json jackson https jersey java net project info 2 1 jersey project jersey media json jackson dependencies html on the classpath 8 1 4 2 Configure and register Jackson JSON processor could be controlled via providing a custom Jackson ObjectMapper http jackson codehaus org 1 9 11 javadoc org codehaus jackson map ObjectMapper html instance This could be handy if you need to redefine the default Jackson behaviour and to fine tune how your JSON data structures look like Detailed description of all Jackson features is out of scope of this guide The example bellow gives you a hint on how to wire your Ob jectMapper instance into your Jersey application In order to use Jackson as your JSON JAXB POJO provider you need to register JacksonFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey jackson JacksonFeature html and a ContextResolver lt T gt for ObjectMapper if needed in your Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html client server Example 8 14 ContextResolver lt ObjectMapper gt 1 Provider 2 public class My
213. much different from the parts described in the client section above To obtain a multipart entity sent by a client in the application you can use two approaches e Injecting the whole MultiPart http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart MultiPart html entity Injecting particular parts of a form data multipart request via FormDataParam http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart FormDataParam html annotation 8 3 3 1 Injecting and returning the MultiPart entity Working with MultiPart types is no different from injecting returning other entity types Jersey provides MessageBodyReader lt T gt for reading the request entity and injecting this entity into a method parameter of a resource method and MessageBodyWriter lt T gt for writing output entities You can expect that either MultiPart or FormDataMultiPart multipart form data media type object to be injected into a resource method Example 8 47 Resource method using MultiPart as input parameter return value QPOST Produces multipart mixed public MultiPart post final FormDataMultiPart multiPart return multiPart 8 3 3 2 Injecting with FormDataParam If you just need to bin the named body part s of a multipart form data request entity body to a resource method parameter you can use 9 FormDataParam http jersey java net nonav apidocs snapshot jersey org glassfi
214. n 1 Path id d 2 public class InjectedResource 3 Injection onto field 4 DefaultValue q QueryParam p 5 private String p 6 7 Injection onto constructor parameter 8 public InjectedResource G8PathParam id int id 9 10 Injection onto resource method parameter FI GET 12 public String get Context UriInfo ui 13 14 Injection onto sub resource resource method parameter 15 Path sub id 16 GET 1 7 public String get PathParam sub id String id 18 19 Injection onto sub resource locator method parameter 20 Path sub id 21 public SubResource getSubResource GPathParam sub id String id 22 23 Injection using bean setter method 24 QHeaderParam X header 25 public void setHeader String header 26 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 36 JAX RS Application Resources and Sub Resources Example 3 24 Wrong injection into a singleton scope 1 Path resource 2 Singleton 3 public static class MySingletonResource 4 5 QueryParam query 6 String param WRONG initialization of application will fail as you can 7 inject request specific parameters into a singleton resou 8
215. n 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 Example 3 6 Server side content negotiation GET Produces application xml qs 0 9 application json public String doGetAsXmlOrJson Oe WN FP 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 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 26 JAX RS Application Resources and Sub Resources Example 3 7 Specifying input MIME type 1 POST 2 Consumes text plain 3 public void postClichedMessage String message 4 Store the messag 5 In this example the Java method will consume representations identified by the MIME media type text plain Notice that
216. n feature For each of these properties there is a client server counter part that only disables the feature on the client or server respectively see ClientProperties http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html ServerProperties http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties html Each of these client server specific auto discovery related properties overrides the value of the related common property if set Note In case an auto discoverable feature is disabled then all the featured components and or properties registered with the feature by default using the auto discovery mechanism have to be registered manually 44 Chapter 5 Client API This section introduces the JAX RS Client API which is a fluent Java based API for communication with RESTful Web services This standard API that is also part of Java EE 7 is designed to make it very easy to consume a Web service exposed via HTTP protocol and enables developers to concisely and efficiently implement portable client side solutions that leverage existing and well established client side HTTP connector implementations The JAX RS client API can be utilized to consume any Web service exposed on top of a HTTP protocol or it s extension e g WebDAV and is not restricted to services implemented using JAX RS Yet developers familiar with JAX RS should find the client
217. n maven developers how to depend on Jersey modules in their application Ant developers are likely to find the Ant Tasks for Maven http maven apache org ant tasks index html very useful 2 3 Common Jersey Use Cases 2 3 1 Servlet based application on Glassfish If you are using Glassfish application server you don t need to package anything with your application everything is already included You just need to declare provided dependency on JAX RS API to be able to compile your application dependency groupId javax ws rs groupId lt artifactId gt javax ws rs api lt artifactId gt lt version gt 2 0 lt version gt lt scope gt provided lt scope gt lt dependency gt If you are using any Jersey specific feature you will need to depend on Jersey directly lt dependency gt groupId org glassfish jersey containers groupId artifactId jersey container servlet artifactlId version 2 1 version lt scope gt provided lt scope gt Modules and dependencies 2 3 2 2 3 3 lt dependency gt lt if you are using Jersey client specific features lt dependency gt groupId org glassfish jersey core groupId lt artifactId gt jersey client lt artifactId gt lt version gt 2 1 lt version gt lt scope gt provided lt scope gt lt dependency gt Servlet based server side application Following dependencies apply to application server servlet containers without any i
218. n of your custom authentication request filter set the filter priority to AUTHENTICATION using constants from Priorities http jax rs spec java net nonav 2 0 apidocs javax ws rs Priorities html An early execution of you authentication filter will ensure that all other filters resources resource methods and sub resource locators will execute with your custom SecurityContext instance 14 1 2 Authorization securing resources 14 1 2 1 Security resources with web xm1 In cases where a Jersey application is deployed in a Servlet container you can rely only on the standard Java EE Web application security mechanisms offered by the Servlet container and configurable via application s web xm1 descriptor You need to define the security constraint elements in the web xml and assign roles which are able to access these resources You can also define HTTP methods that are allowed to be executed See the following example Example 14 3 Injecting SecurityContext into singletons 1 security constraint 2 lt web resource collection gt 3 url pattern rest admin url pattern 4 lt web resource collection gt 5 lt auth constraint gt 6 lt role name gt admin lt role name gt 7 lt auth constraint gt 8 security constraint 9 lt security constraint gt 10 web resource collection T url pattern rest orders url pattern 12 lt web resource collection gt 13 lt auth constraint gt 14 l
219. nav 2 0 apidocs javax ws 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 57 Representations and Responses Example 6 2 Returning 201 status code and adding Location header in response to POST request POST Consumes application xml public Response post String content create content return Response created createdUri build 1 2 3 4 URI createdUri 5 6 7 In the above no representation produced is returned this can be achieved by building an entity as part of the response as follows Example 6 3 Adding an entity body to a custom response POST Consumes application xml public Response post String content String createdContent create content return Response created createdUri entity Entity text createdContent buil 1 2 3 4 URI createdUri 5 6 7 Response building provides other functionality such as setting the entity tag and last modified date of the representation 6 3 WebApplicationException Exceptions to Responses and Mapping Previous section shows how to return HTTP responses that
220. nav 2 O apidocs javax ws rs core Configurable html as this feature is automatically discovered and registered when you add jersey media json processing module to your classpath As for the other modules jersey media json processing has also few properties that can affect the registration of JsonProcessingFeature besides CommonProperties FEATURE AUTO DISCOVERY DISABLE http jersey java net nonav apidocs 81 Support for Common Media Type Representations snapshot jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE and the like e CommonProperties JSON_PROCESSING_FEATURE_DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey CommonProperties html JSON_PROCESSING_FEATURE_DISABLE e ServerProperties SON PROCESSING FEATURE DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ServerProperties htmltJSON PROCESSING FEATURE DISABLE e ClientProperties SON PROCESSING FEATURE DISABLE http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html JSON PROCESSING FEATURE DISABLE To configure MessageBodyReader T http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html s MessageBodyWriter T http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html s provided by JSON P you can simply add values for supported propertie
221. ncies see jersey mvc https jersey java net project info 2 1 jersey project jersey mvc dependencies html jersey mvc freemarker https jersey java net project info 2 1 jersey project jersey mvc freemarker dependencies html jersey mvc jsp https jersey java net project info 2 1 jersey project jersey mvc jsp dependencies html on the classpath 17 2 Registration and Configuration To use capabilities of Jersey MVC templating support in your JAX RS Jersey application you need to register Feature http jax rs spec java net nonav 2 O0 apidocs javax ws rs core Feature html s provided by the modules mentioned above For jersey mvc it is MvcFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc MvcFeature html for jersey mvc jsp its JspMvcFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc JspMvcFeature html and for jersey mvc freemarker it is FreemarkerMvcFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc FreemarkerM vcFeature html Note Both JspMvcFeature and FreemarkerMvcFeature also register MvcFeature so you don t need to register it explicitly when using these JSP Freemarker modules Example 17 1 Registering MvcFeature new ResourceConfig register org glassfish jersey server mvc MvcFeature class Further configuration of ResourceConfig register Example 17 2 Registering
222. nd annotation XmlRootElement html This is an JAXB annotation which maps java classes to XML elements We don t need to specify anything else because Planet is very simple class and all fields are public In this case XML element name will be derived from the class name or you can set the name property QXmlRootElement name yourName Our resource class will respond to GET planet with lt xml version 1 0 encoding UTF 8 standalone yes gt lt planet gt lt id gt 1 lt id gt lt name gt Earth lt name gt lt radius gt 1 0 lt radius gt lt planet gt which might be exactly what we want or not Or we might not really care because we can use JAX RS client for making requests to this resource and this is easy as Planet planet webTarget path planet request MediaType APP There is pre created WebTarget object which points to our applications context root and we simply add path in our case its planet accept header not mandatory but service could provide different content based on this header for example text htm1 can be served for web browsers and at the end we specify that we are expecting Planet class via GET request 92 Support for Common Media Type Representations 8 2 3 There may be need for not just producing XML we might want to consume it as well Example 8 32 Method for consuming Planet 1 POST 2 Consumes MediaType APPLICATION_XML 3 public void setPlane
223. nd cross property constraints 16 4 2 Annotation constraints and Validators Annotation constraints and validators are defined in accordance with the Bean Validation specification The Email annotation used in Example 16 4 Constraint annotations on fields is defined using the Bean Validation Constraint http docs jboss org hibernate beanvalidation spec 1 1 api javax validation Constraint html meta annotation see Example 16 6 Definition of a constraint annotation Example 16 6 Definition of a constraint annotation Target METHOD Retention RUNTIME Constraint valida public interface FIELD tedBy Email String message defa Class lt gt gro PARAMETER EmailValidator class ult com example validation constraints email ups default Class extends Payload gt payload default The Constraint annotation must include a reference to the validator class that will be used to validate decorated values The EmailValidator class must implement ConstraintValidator lt Email T gt where T is the type of values being validated as described in Example 16 7 Validator implementation Example 16 7 Validator implementation public class EmailValidator implements ConstraintValidator lt Email String gt public void initialize Email email public boolean isValid String value ConstraintValida
224. nd send a HTTP GET request to the MyResource JAX RS resource class listening on myresource URI As part of the same fluent JAX RS API method invocation chain a response is read as a Java St ring type On the second line in the test method the response content string returned from the server is compared with the expected phrase in the test assertion To learn more about using JAX RS Client API please see the Chapter 5 Client API chapter 1 3 Running the Project Now that we have seen the content of the project let s try to test run it To do this we need to invoke following command on the command line mvn clean test This will compile the project and run the project unit tests We should see a similar output that informs about a successful build once the build is finished Results Tests run 1 Failures 0 Errors 0 Skipped 0 Getting Started INFO INFO BUILD SUCCESS INFO INFO Total time 34 527s INFO Finished at Sun May 26 19 26 24 CEST 2013 INFO Final Memory 17M 490M INFO Now that we have verified that the project compiles and that the unit test passes we can execute the application in a standalone mode To do this run the following maven command mvn clean exec java The application starts and you should soon see the following notification in your console May 26 2013 8 08 45 PM org glassfish grizzly http server NetworkListener start INFO Started listener bound to
225. ndex html The JAX RS 2 0 specification draft can be found online here http jcp org en jsr summary id 339 3 1 Root Resource Classes Root resource classes are POJOs Plain Old Java Objects that are annotated with Path http jax rs spec java net nonav 2 0 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 O 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 1 Example 3 1 Simple hello world root resource class package org glassfish jersey examples helloworld import javax ws rs GET import javax
226. nt events https jersey java net project info 2 1 jersey project server sent events dependencies html Jersey Server Sent Events example simple console https jersey java net project info 2 1 jersey project Jersey Simple Console example 18 Modules and dependencies simple console dependencies html sse twitter aggregator https jersey java net project info 2 1 jersey project sse twitter aggregator dependencies html Jersey SSE Twitter Message Aggregator Example system properties example https jersey java net project info 2 1 jersey project system properties example dependencies html Jersey system properties example xml moxy https jersey java net project info 2 1 jersey project xml moxy dependencies html Jersey XML MOXy example Table 2 9 Jersey Examples WebApps Examples WAR bean validation webapp https jersey java net project info 2 1 jersey project webapp example parent bean validation webapp dependencies html bookmark https jersey java net project info 2 1 jersey project webapp example parent bookmark dependencies html Jersey Bean Validation JSR 349 example Jersey Bookmark example bookmark em https jersey java net project info 2 1 jersey project webapp example parent bookmark em dependencies html Jersey Bookmark example using
227. nt register method supports the fluent API style multiple client instance configuration calls can be chained 1 client register FilterA class 2 register new FilterB 3 property my property true To get the current configuration of the Client instance a get Configuration method can be used ClientConfig clientConfig new ClientConfig clientConfig register MyClientResponseFilter class clientConfig register new AnotherClientFilter Client client ClientBuilder newClient clientConfig client register ThirdClientFilter class Configuration newConfiguration client getConfiguration DOP CO Por In the code an additional MyClientResponseFilter class and AnotherClientFilter instance are registered in the clientConfig The clientConfig is then used to construct a new Client instance The ThirdClientFilter is added separately to the constructed Client instance This does not influence the configuration represented by the original clientConfig In the last step a newConfiguration is retrieved from the client This configuration contains all three registered filters while the original c1ientConfig instance still contains only two filters Unlike clientConfig created separately the newConfiguration retrieved from the client instance represents a live client configuration view Any additional configuration changes made to the c1ient instance are also reflected in the newConfiguration So newConfiguration is real
228. ntegrated JAX RS implementation Then application needs to include JAX RS API and Jersey implementation in deployed application lt dependency gt groupId org glassfish jersey containers groupId if your container implements Servlet API older than 3 0 use jersey cont artifactId jersey container servlet artifactlId version 2 1 version dependency Required only when you are using JAX RS Client gt dependency groupId org glassfish jersey core groupId lt artifactId gt jersey client lt artifactId gt lt version gt 2 1 lt version gt lt dependency gt Client application on JDK Applications running on plain JDK using only client part of JAX RS specification need to depend only on client There are various additional modules which can be added like for example grizzly or apache connector see dependencies snipped below Jersey client runs by default with plain JDK using HttpUrlConnection See Chapter 5 Client API for more details lt dependency gt groupId org glassfish jersey core groupId lt artifactId gt jersey client lt artifactId gt lt version gt 2 1 lt version gt lt dependency gt Currently available connectors lt dependency gt groupId org glassfish jersey connectors groupId lt artifactId gt jersey grizzly connector lt artifactId gt lt version gt 2 1 lt version gt lt dependency gt lt dependency gt groupId org glassfish je
229. ntext http jax rs spec java net nonav 2 0 apidocs javax ws rs ext WriterInterceptorContext html and sets a new one which is a GZIP wrapper of the original output stream After all interceptors are executed the output stream lastly set to the WriterInterceptorContext will be used for serialization of the entity In the example above the entity bytes will be written to the GZIPOutputStream which will compress the stream data and write them to the original output stream The original stream is always the stream which writes the data to the wire When the interceptor is used on the server the original output stream is the stream into which writes data to the underlying server container stream that sends the response to the client The interceptors wrap the streams and they itself work as wrappers This means that each interceptor is a wrapper of another interceptor and it is responsibility of each interceptor implementation to call the wrapped interceptor This is achieved by calling the proceed method on the WriterInterceptorContext This method will call the next registered interceptor in the chain so effectivelly this will call all remaining registered interceptors Calling proceed from the last interceptor in the chain will call the appropriate message body reader Therefore every interceptor must call the proceed method otherwise the entity would not be written The wrapping principle is reflected also in the method name aroundWriteTo which
230. nto a ConstraintValidator Example 16 12 Injecting UriInfo into a ConstraintValidator public class EmailValidator implements ConstraintValidator Email String Context private Urilnfo uriInfo public void initialize Email email public boolean isValid String value ConstraintValidatorContext context Use UriInfo Using a custom ConstraintValidatorFactory http docs jboss org hibernate beanvalidation spec 1 1 api javax validation ConstraintValidatorFactory html of your own disables registration of the one 168 Bean Validation Support provided by Jersey and injection support for resources providers if needed has to be provided by this new implementation Example 16 13 Support for injecting Jersey s resources providers via ConstraintV alidatorFactory shows how this can be achieved Example 16 13 Support for injecting Jersey s resources providers via ConstraintValidatorFactory public class InjectingConstraintValidatorFactory implements ConstraintValidatorFac Context private ResourceContext resourceContext QOverride public T extends ConstraintValidator lt gt gt T getInstance final Class lt T gt key return resourceContext getResource key GOverride public void releaseInstance final ConstraintValidator lt instance NOOP Note This behaviour may likely change in one of the next version of Jersey to remove the need of manually
231. o Java de serialization MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html and the other one for handling the outbound entity Java to representation serialization MessageBodyWriter lt T gt http jax rs spec java net nonav 2 O apidocs javax ws rs ext MessageBodyWiriter html A MessageBodyReader lt T gt as the name suggests is an extension that supports reading the message body representation from an input stream and converting the data into an instance of a specific Java type A MessageBodyWriter lt T gt is then responsible for converting a message payload from an instance of a specific Java type into a specific representation format that is sent over the wire to the other party as part of an HTTP message exchange Both of these providers can be used to provide message payload serialization and de serialization support on the server as well as the client side A message body reader or writer is always used whenever a HTTP request or response contains an entity and the entity is either requested by the application code e g injected as a parameter of JAX RS resource method or a response entity read on the client from a Response http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response html or has to be serialized and sent to the other party e g an instance returned from a JAX RS resource method or a request entity sent by a JAX RS client 7 2 How to Write C
232. on that contains only the HelloResource resource class ResourceConfig is a sub class of JAX RS Application http jax rs spec java net nonav 2 O apidocs javax ws rs 181 Jersey Test Framework 18 2 core Application html It is a Jersey convenience class for configuring JAX RS applications ResourceConfig also implements JAX RS Configurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html interface to make the application configuration more flexible Supported Containers JerseyTest http jersey java net nonav apidocs snapshot jersey org glassfish jersey org glassfish jersey test JerseyTest html supports deploying applications on various containers all except the external container wrapper need to have some glue code to be supported Currently Jersey Test Framework provides support for Grizzly In Memory JDK com sun net httpserver HttpServer and Simple HTTP container org simpleframework http A test container is selected based on various inputs JerseyTest getTestContainerFactory http jersey java net nonav apidocs snapshot jersey org glassfish jersey test JerseyTest html getTestContainerFactory is always executed so if you override it and provide your own version of TestContainerFactory http jersey java net nonav apidocs snapshot jersey org glassfish jersey org glassfish jersey test spi TestContainerFactory html nothing else will be considered Setting a system variable
233. onse but content stays Feel free to iterate through all resources Getting started with JAXB Good start for people which already have some experience with JAXB annotations is JAXB example https github com jersey jersey tree master examples jaxb You can see various use cases there This text is mainly meant for those who don t have prior experience with JAXB Don t expect that all possible annotations and their combinations will be covered in this chapter JAXB JSR 222 implementation http jaxb java net is pretty complex and comprehensive But if you just want to know how you can interchange XML messages with your REST service you are looking at the right chapter Lets start with simple example Lets say we have class Planet and service which produces Planets 91 Support for Common Media Type Representations Example 8 30 Planet class 1 XmlRootElement 2 public class Planet 3 public int id 4 public String name 5 public double radius 6 Example 8 31 Resource class 1 Path planet 2 public class Resource 3 4 GET 5 Produces MediaType APPLICATION_XML 6 public Planet getPlanet 7 final Planet planet new Planet 8 9 planet id 1 10 planet name Earth 11 planet radius 1 0 12 13 return planet 14 15 You can see there is some extra annotation declared on Planet class particularly 9 XmlRootElement http jaxb java net nonav 2 2 7 docs api javax xml bi
234. onstraint violation message TraversableResolver http docs jboss org hibernate beanvalidation spec 1 1 api javax validation TraversableResolver html determines if a property can be accessed by the Bean Validation provider Constraint ValidatorFactory http docs jboss org hibernate beanvalidation spec 1 1 api javax validation ConstraintV alidatorFactory html instantiatesa Const raint Validator instance based off its class Note that by setting a custom ConstraintValidatorFactory you may loose injection of available resources providers at the moment See Section 16 6 Injecting how to handle this ParameterNameProvider http docs jboss org hibernate beanvalidation spec 1 1 api javax validation ParameterNameProvider html provides names for method and constructor parameters Tip In the latest versions of Jersey the old style setter methods set on ValidationConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server validation ValidationConfig html are deprecated and replaced with methods that allow the fluent use of the API e g ValidationConfig messageInterpolator MessageInterpolator Use of the new fluent methods is encouraged as the old setters will be removed from the API soon 161 Bean Validation Support Example 16 2 Using ValidationConfig to configure Validator Custom configuration of validation This configuration defines custom
235. or at least for an unacceptable long time In asynchronous processing model occurrences of such situations should be carefully considered with client connections not being automatically closed when the processing method returns and the response needs to be resumed explicitly based on an event that may actually even never happen To tackle these situations asynchronous timeouts can be used The following example shows the usage of timeouts 115 Asynchronous Services and Clients Example 10 2 Simple async method with timeout 1 GET 2 public void asyncGetWithTimeout Suspended final AsyncResponse asyncResponse 3 asyncResponse setTimeoutHandler new TimeoutHandler 4 5 Override 6 public void handleTimeout AsyncResponse asyncResponse 7 asyncResponse resume Response status Response Status SERVICE_UNAVA 8 entity Operation time out build 9 10 deal asyncResponse setTimeout 20 TimeUnit SECONDS T2 13 new Thread new Runnable 14 15 Override 16 public void run 17 String result veryExpensiveOperation 18 asyncResponse resume result 19 20 21 private String veryExpensiveOperation 22 very expensive operation that typically finishes within 20 23 24 start 29 By default there is no timeout defined on the suspended AsyncResponse instance A custom timeout and timeout event handler may be defined using set TimeoutHandler TimeoutH
236. ory was cloned typically the directory named jersey 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 tests e2e directory You can run tests related to a particular area using the following command 185 Building and Testing Jersey mvn Dtest lt pattern gt test where pattern may be a comma separated set of names matching tests classes or individual methods like LinkTest testDelimiters 19 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 186 Chapter 20 Migrating from Jersey 1 x This chapter is a migration guide for people switching from Jersey 1 x Since many of the Jersey 1 x features became part of JAX RS 2 0 standard which caused changes in the package names we decided it is a good time to do a more significant incompatible refactoring which will allow us to introduce some more interesting new features in the future As the result there are many incompatiblities between Jersey 1
237. ost suitable provider for entity processing This algorithm works with information such as entity Java type and on the wire media type representation of entity and searches for the most suitable entity provider from the list of available providers based on the supported media type declared on each provider defined by Produces or 69 JAX RS Entity Providers Consumes on the provider class as well as based on the generic type declaration of the available providers When a list of suitable candidate entity providers is selected and sorted based on the rules defined in JAX RS specification a JAX RS runtime then it invokes isReadable or isWriteable method respectively on each provider in the list until a first provider is found that returns t rue This provider is then used to process the entity The following steps describe the algorithm for selecting a MessageBodyWriter lt T gt extracted from JAX RS with little modifications The steps refer to the previously discussed example application The MessageBodyWriter lt T gt is searched for purpose of deserialization of MyBean entity returned from the method getMyBean So type is MyBean and media type application xm1 Let s assume the runtime contains also registered providers namely A Produces application with generic type lt Object gt B Produces with generic type lt MyBean gt C Produces text plain with generic type lt MyBean gt D Produces applica
238. ource 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 a new 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 during the deployment in the resource model validation phase In order to retain the consistency of the final model a model processor implementation would have to be more robust than what is shown in the example 133 Chapter 13 Server Sent Events SSE Support 13 1 What are Server Sent Events In a standard HTTP request response scenario a client opens a connection sends a HTTP request to the server for example a HTTP GET request then receives a HTTP response back and the server closes the connection once the response is fully sent received The initiative always comes from a client when the client requests all the data In contrast Server Sent Events SSE is a mechanism that allows server to asynchronously push the data from the server to the client once the client server connection is established by the client Once the connection is established by the client it is the server who provides the data an
239. ource method s invoked from another request thread s can write data into the chunked output and or close the chunked response 119 Asynchronous Services and Clients 10 2 Client API The client API supports asynchronous processing too Simple usage of asynchronous client API is shown in the following example Example 10 5 Simple client async invocation 1 final AsyncInvoker asyncInvoker target path http example com resource 2 request async 3 final Future lt Response gt responseFuture asyncInvoker get 4 System out println Request is being processed asynchronously 5 final Response response responseFuture get 6 get waits for the response to be ready 7 System out println Response received The difference against synchronous invocation is that the http method call get is not called on SyncInvoker http jax rs spec java net nonav 2 0 apidocs javax ws rs client SyncInvoker html but on AsyncInvoker http jax rs spec java net nonav 2 O apidocs javax ws rs client AsyncInvoker html The AsyncInvoker is returned from the call of method Invocation Builder async as shown above AsyncInvoker offers methods similar to SyncInvoker only these methods do not return a response synchronously Instead a Future representing response data is returned These method calls also return immediately without waiting for the actual request to complete In order to get the response of
240. plateReference Viewable viewable MediaType mediaType OutputStream out throws IOException final PrintStream ps new PrintStream out ps print path ps print templateReference ps printin ps print model ps print viewable getModel toString ps printin 179 MVC Templates Example 17 9 Registering custom TemplateProcessor http jersey java net nonav apidocs snapshot jersey org glassfish jersey server mvc TemplateProcessor html new ResourceConfig register MyTemplateProcessor class Further configuration of ResourceConfig register 17 6 Other Examples To see an example of MVC JSP templating support in Jersey refer to the MVC Bookstore example https github com jersey jersey tree master examples bookstore webapp 180 Chapter 18 Jersey Test Framework Jersey Test Framework originated as an internal tool used for verifying the correct implementation of server side components Testing RESTful applications became a more pressing issue with modern approaches like test driven development and users started to look for a tool that could help with designing and running the tests as fast as possible but with many options related to test execution environment Current implementation of Jersey Test Framework supports the following set of features pre configured client to access deployed application support for multiple containers gri
241. property values is listed bellow 1 public class SimpleTest extends JerseyTest 2 3 4 Override 5 protected Application configure 6 enable TestProperties LOG TRAFFIC 7 enable TestProperties DUMP ENTITY 8 9 10 11 12 The code in the example above enables test traffic logging inbound and outbound headers as well as dumping the HTTP message entity as part of the traffic logging 18 3 2 External container Complicated test scenarios may require fully started containers with complex setup configuration that is not easily doable with current Jersey container support To address these use cases Jersey Test Framework providers general fallback mechanism an External Test Container Factory Support of this external container wrapper is provided as the following module lt dependency gt groupId org glassfish jersey test framework providers groupId artifactId jersey test framework provider external artifactlId version 2 1 version dependency As indicated the container exposed by this module is just a wrapper or stub that redirects all request to a configured host and port Writing tests for this container is same as for any other but you have to provide the information about host and port during the test execution 183 Jersey Test Framework mvn test Djersey test host myhost org Djersey config test container port 8080 18 3 3 Test Client configura
242. providing support for injecting resources providers from Jersey in your own ConstraintValidatorFactory implementation code 16 7 Error Reporting Bean Validation specification defines a small hierarchy of exceptions they all inherit from ValidationException http docs jboss org hibernate beanvalidation spec 1 1 api javax validation ValidationException html that could be thrown during initialization of validation engine or for our case more importantly during validation of input output values ConstraintViolationException http docs jboss org hibernate beanvalidation spec 1 1 api javax validation ConstraintViolationException html If a thrown exception is a subclass of ValidationException except ConstraintViolationException then this exception is mapped to a HTTP response with status code 500 Internal Server Error On the other hand when a ConstraintViolationException is throw two different status code would be returned e 500 Internal Server Error If the exception was thrown while validating a method return type 400 Bad Request Otherwise 16 7 1 ValidationError By default during mapping Const raintViolationExceptions Jersey doesn t return any entities that would include validation errors to the client This default behaviour could be changed by enabling 169 Bean Validation Support ServerProperties BV_SEND_ERROR_IN_RESPONSE http jersey java net nonav apidocs snapshot j
243. ps github com jersey jersey tree master examples json jettison on how to use Jettison to consume produce JSON JSONP JSON with Padding Support Jersey provides out of the box support for JSONP http en wikipedia org wiki JSONP JSON with padding The following conditions has to be met to take advantage of this capability Resource method which should return wrapped JSON needs to be annotated with JSONP http jersey java net nonav apidocs snapshot Jersey org glassfish jersey server JS ONP html annotation e MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html for application json media type which also accepts the return type of the resource method needs to be registered see JSON section of this chapter User s request has to contain Accept header with one of the JavaScript media types defined see below Acceptable media types compatible with JSONP are application javascript application x javascript application ecmascript text javascript text x javascript text ecmascript text jscript Example 8 26 Simplest case of using QJSONP GET JSONP Produces application json application javascript public JaxbBean getSimpleJSONP return new JaxbBean jsonp Assume that we have registered a JSON providers and that the JaxbBean looks like 88 Support for Common Media Type Representations Example 8 27 JaxbBean for JSONP
244. r container 16 17 18 Override 19 public void onReload Container container 20 ignore or do whatever you want after reload has been done 21 22 23 Override 24 public void onShutdown Container container 2 5 ignore or do something after the container has been shutdown 26 27 Example 20 4 Jersey 2 reloader registration 1 Reloader reloader new Reloader 2 resourceConfig addSingletons reloader 3 20 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 having higher priority than default ones provided by Jersey 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 190 Migrating from Jersey 1 x 20 2 Migrating Jersey 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 Table 20 1 Mapping of Jersey 1 x to JAX RS 2 0 client classes Dy RS t Ihss Class Erat krsibtierfaapryl iretKddsnind constructors http jexsey java net monav apedgas d rici jeonay 2 0 apid cs fandx yessey ngl client ClientBimilpr html Eietite instance methods ht
245. rId this customerId customerId this customerService null init customer service her GET public String getAddress return customerService getAddressForCustomer customerId PUT public void updateAddress String address customerService updateAddressForCustomer customerId address GET Path sub public String getDeliveryAddress return customerService getDeliveryAddressForCustomer customerId 154 WADL Support The GET request to http localhost 9998 application wadl will return the following WADL document 155 49 lt method gt 50 lt method name PUT id updateAddress gt 51 lt resource path sub gt 52 nW bldSupport GET id getDeliveryAddress gt 53 lt response gt 54 lt method gt Example 15 5 More complex WADL example WADL content 56 resource 57 resource 58 resource path application wadl 59 method name GET id getWadl gt 60 response 61 representation mediaType application vnd sun wadl txml 62 representation mediaType application xml 63 response 64 method 65 method name OPTIONS id apply gt 66 request 67 representation mediaType gt 68 request 69 response 70 representation mediaType text plain 71 lt response gt 72 lt method gt 73 lt method name OPTIONS id apply gt 74 lt request gt 75 representation mediaType
246. re 68 viii Jersey 2 1 User Guide 7 9 Result of testing MyBeanMessageBodyReader sssesseeee eee eene 69 7 10 MessageBodyReader registered on a JAX RS client sssss ee eeca ceca sean eeneees 69 TAY Result of chent code executio 11 shawn ttes ente ied oret dane obese eed oA dee ses 69 7 12 Usage of MessageBodyWorkers interface ssessesseseee Her 73 8 1 Simple JAXB bean implementation 0 cece ee cece cence HH Hee herren 76 8 2 JAXB bean used to generate JSON representation csssessse e 76 8 3 Tweaking JSON format using JAXB sssssesssssesse I Ime emere TI 8 4 JAXB bean creatioB ne Eee yere tem ute 77 8 5 Constructing a JsonOb ject JSON Processing 2 0 0 0 cece cece eee cece ce eece Hen TI 8 6 Constructing a JSONOb ject Jettison esses he emen eene 78 8 7 MoxyJsonConfig Setting properties sor eie eener cece cee III men ment entren 79 8 8 ContextResolver MoxyJsonConfig i cusseeatradereetesstinei ere xe rte decree dee re eren 80 8 9 Setting properties for MOXy providers into Configurable eee ees 80 8 10 Building client with MOXy JSON feature enabled ssseeee 81 8 11 Creating JAX RS application with MOXy JSON feature enabled eeeeeeessl 81 8 12 Building client with JSON Processing JSON feature enabled esses 82 8 13 Creating JA
247. re adds new supported entity representation Java types namely OutboundEvent http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse OutboundEvent html for the outbound server events and InboundEvent http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse InboundEvent html for inbound client events These types are serialized by OutboundEvent http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse OutboundEventWriter html and de serialized by InboundEventReader http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse InboundEventReader html There is no restriction for a media type used in individual event messages however the media type used for a SSE stream as whole is text event stream and this media type should be set on messages that are used to serve SSE events for example on the server side using Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html on the method that returns an EventOutput see bellow The InboundEvent and OutboundEvent contain all the fields needed for composing and processing individual SSE events These entities represent the chunks sent or received over an open server to client connection that is represented by an ChunkedOutput http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ChunkedOuptut html on the servers side and ChunkedInput http j
248. red 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 Path users username 2 public class UserResource 3 4 GET 5 Produces text xml 6 public String getUser GPathParam username String userName 7 8 9 If it is required that a user name must only consist of lower and upper case numeric characters then it is possible to declare a particular regular expression which overrides the default regular expression 4 for example Path users username a zA Z a zA Z 0 9 In this type of example the username variable will only match user names that begin with one upper or lower case letter and zero or more alpha numeric characters and the underscore character If a user name does not match that a 404 Not Found response will occur A Path http jax rs spec java net nonav 2 0 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 ws rs Path html value may or may not end in a it makes no difference and thus request URLs that end or do not end in a will both be matche
249. response GET Path images image Produces image public Response getImage PathParam image String image File f new File image if f exists throw new WebApplicationException 404 OANA OBWN FE Ne 10 11 String mt new MimetypesFileTypeMap getContentType f 12 return Response ok f mt build 13 The File type can also be used when consuming a representation request entity In that case a temporary file will be created from the incoming request entity and passed as a parameter to the resource method The Content Type response header if not set programmatically as described in the next section will be automatically set based on the media types declared by Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation Given the following method the most acceptable media type is used when multiple output media types are allowed GET Produces application xml application json public String doGetAsXmlOrJson Oe WN PF If application xml is the most acceptable media type defined by the request e g by header Accept application xml then the Content Type response header will be set to application xml 6 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 no
250. rg glassfish jersey client ClientProperties html CONNECT_ TIMEOUT interval in milliseconds Default value is 0 infinity ClientProperties FEATURE_AUT http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html FEATURE _ AUTO_DISCOVERY_DISABLI GeDESGO VERN DISABLE cAu Disables feature autbidiscovery on client Default value is false i ClientProperties FOLLOW_REDIREC 8y config client fdDbolw amp sdithatctthe client http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html FOLLOW REDIRECTS will automatically redirect to the URI declared in 3xx responses Default value is true ClientProperties HTTP URL CO http jersey java net nonav apidocs snapshot jersey org glassfish jersey client NNEGdIONoSETgMETHODB W up Xd ATfeS nb thei chent ewME tiy to set erased HTTP method to HttpURLConnection via reflection Default value is ClientProperties html HTTP URL CONNECTION SET METHO X WORKAROUND ClientProperties JSSON PROCESSIENGsSEEATURE dDISASAIE e J3 Disablese eonfrgnrationerof Json http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html JSON_PR CESSING_FEATURE_DISABLI Processing JSR 353 feature Default value is false i ClientProperties METAINF_SERMVJ ESe LOOKUP gDISABICH eMe Disables e rv ME
251. rgeting a web resource eic ede edet ete goce sepe eget eve ceri eee tn 49 5 3 4 Identifying resource on WebTarget sese HH 49 5 3 5 Invoking HTTP request neritina ureei ue iesite e EE eiue IRI vH Eee ern aD e 50 3 3 6 Example sumrmaty tete terree terme ete meade re POR RESET 51 5 4 Java instances and types for representations ssssssssseee me 52 5 4 1 Adding support for new representations sessesee eee eeneeeneeeneees 52 5 5 Client Transport Connectors sessessesee IH HI He emen eere rennen 53 5 6 Using client request and response filters 1 2 0 0 cece cece ee cece ce m 53 5 7 Securing a Chente een gt eer estes e sisi eee get ege desi gto sedeo ede Re TEES 54 5 7 1 HTTP Basic Authentication Support ssssesse HH 55 6 Representations and Responses ssessessesee I He eee hee hen thiet entren 56 6 1 Representations and Java Types sssssss HI ehem N EEES 56 6 2 Building Responses ete re eere Eee DOR Speer e ee HERD De PE epe quei 57 6 3 WebApplicationException and Mapping Exceptions to Responses eeseeseess 58 lil Jersey 2 1 User Guide 6 4 Conditional GETs and Returning 304 Not Modified Responses sess 60 ic JAX RS Entity Providers 2 5 ao eee ed eue Ud ree E TIR 62 Wels Introduction s sie coiere Etre reete beep teta fe sess Ent ete aeo ptg inea te dte de sedute 62 7
252. riBuilder from the bookmark example Example 11 1 URI building 1 Path users 2 public class UsersResource 3 4 Context 5 Urilnfo uriInfo 6 7 8 9 GET 10 Produces application json 11 public JSONArray getUsersAsJsonArray 12 JSONArray uriArray new JSONArray 13 for UserEntity userEntity getUsers 14 UriBuilder ub urilInfo getAbsolutePathBuilder 15 URI userUri ub 16 path userEntity getUserid L7 build 18 uriArray put userUri toASCIIString 19 20 return uriArray 21 22 UriInfo 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 9 Context on resource method parameters UriInfo can be used to obtain URIs and associated UriBuilder 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 124 URIs and Links calling UriInfo getAbsolutePathBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriInfo htmltgetAbsolutePathBuilder A new path segment is added which is the user ID and then the URI is built
253. rm data Example 3 10 Processing POSTed HTML form 1 POST 2 Consumes application x www form urlencoded 3 public void post FormParam name String name 4 5 Store the messag If it is necessary to obtain a general map of parameter name to values then for query and path parameters it is possible to do the following Example 3 11 Obtaining general map of URI path and or query parameters GET public String get Context UriInfo ui MultivaluedMap lt String String gt queryParams ui getQueryParameters MultivaluedMap lt String String gt pathParams ui getPathParameters O15 WBN FR 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 headerParams hh getRequestHeaders Map lt String Cookie pathParams hh getCookies Owe WBN FR 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 1 POST 2 Consumes application x www form urlencoded 3 public void post MultivaluedMap lt String String gt formParams 4 5 Store
254. rsey connectors groupId Modules and dependencies artifactId jersey apache connector artifactId version 2 1 version dependency 2 3 4 Served side application on supported container Jersey provides support for programmatic deployment on some containers Grizzly 2 http servlet JDK Http server and Simple Http server This chapter presents only required maven dependencies more information can be found in Chapter 4 Deploying a RESTful Web Service dependency groupId org glassfish jersey containers groupId artifactId jersey container grizzly2 http artifactId version 2 1 version dependency dependency groupId org glassfish jersey containers groupId artifactId jersey container grizzly2 servlet artifactId version 2 1 version dependency dependency groupId org glassfish jersey containers groupId artifactId jersey container jdk http artifactId version 2 1 version dependency dependency groupId org glassfish jersey containers groupId artifactId jersey container simple http artifactlId version 2 1 version dependency 2 4 List of modules The following chapters provide an overview of all Jersey modules and their dependencies with links to the respective binaries follow a link on a module name to get complete set of downloadable dependencies Table 2 1 Jersey Core Core jerse
255. rsey java net project info 2 1 jersey project project jersey test framework provider external dependencies html Jersey Test Framework External container jersey test framework provider grizzly2 https jersey java net project info 2 1 jersey project project jersey test framework provider grizzly2 dependencies html Jersey Test Framework Grizzly2 container jersey test framework provider inmemory https jersey java net project info 2 1 jersey project project jersey test framework provider inmemory dependencies html Jersey Test Framework InMemory container jersey test framework provider jdk http https jersey java net project info 2 1 jersey project project jersey test framework provider jdk http dependencies html Jersey Test Framework JDK HTTP container jersey test framework provider simple https jersey java net project info 2 1 jersey project project jersey test framework Jersey Test Framework Simple HTTP container 14 Modules and dependencies provider simple dependencies html Table 2 7 Jersey Glassfish Bundles Glassfish Bundles jersey gf cdi https jersey java net project info 2 1 jersey project project jersey gf cdi dependencies html Jersey CDI for GlassFish integration jersey gf ejb https jersey java net project info 2 1 jersey project project jers
256. rver container 14 Server MessageBodyWiriter message body writer is executed on the server which serializes the entity into the GZIPOutputStream This stream compresses the data and writes it to the original stream which sends this compressed data back to the client 15 Client receives the response the response contains compressed entity data 16 Client ClientResponseFilters client response filters are executed and they manipulate the response headers 17 Client response is returned the javax ws rs core Response is returned from the request invocation 18 Client code calls response readEntity read entity is executed on the client to extract the entity from the response 19 Client ReaderInterceptor the client reader interceptor is executed when readEntity Class is called The interceptor wraps the entity input stream with GZIPInputStream This will decompress the data from the original input stream 20 Client MessageBodyReaders client message body reader is invoked which reads decompressed data from GZIPInputStream and deserializes the entity 21 Client The entity is returned from the readEntity Itis worth to mention that in the scenario above the reader and writer interceptors are invoked only if the entity is present it does not make sense to wrap entity stream when no entity will be written The same behaviour is there for message body readers and writers As mentioned above interceptors are executed before the message
257. s a default and preferred way of supporting JSON binding in your Jersey applications since Jersey 2 0 When JSON MOXy module is on the class path Jersey will automatically discover the module and seamlessly enable JSON binding support via MOXy in your applications See Section 4 1 Auto Discoverable Features Java API for JSON Processing JSON P Jackson Jettison Approaches to JSON Support Each of the aforementioned extension modules uses one or more of the three basic approaches available when working with JSON representations e POJO based JSON binding support JAXB based JSON binding support Low level JSON parsing amp processing support The first method is pretty generic and allows you to map any Java Object to JSON and vice versa The other two approaches limit you in Java types your resource methods could produce and or consume JAXB based approach is useful if you plan to utilize certain JAXB features and support both XML and JSON representations The last low level approach gives you the best fine grained control over the out coming JSON data format 8 1 1 1 POJO support POJO support represents the easiest way to convert your Java Objects to JSON and back Media modules that support this approach are MOXy and Jackson 8 1 1 2 JAXB based JSON support Taking this approach will save you a lot of time if you want to easily produce consume both JSON and XML data format With JAXB beans you will be able to us
258. s into the Configuration http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configuration html instance client server Currently supported are these properties e JsonGenerator PRETTY PRINTING javax json stream JsonGenerator prettyPrinting Example 8 12 Building client with JSON Processing JSON feature enabled ClientBuilder newClient new ClientConfig The line bellow that registers JSON Processing feature can be omitted if FEATURE AUTO DISCOVERY DISABLE is not disabled register JsonProcessingFeature class property JsonGenerator PRETTY PRINTING true Example 8 13 Creating JAX RS application with JSON Processing JSON feature enabled Create JAX RS application final Application application new ResourceConfig The line bellow that registers JSON Processing feature can be omitted if FEATURE AUTO DISCOVERY DISABLE is not disabled register JsonProcessingFeature class packages org glassfish jersey examples jsonp property JsonGenerator PRETTY PRINTING true 8 1 3 3 Examples Jersey provides an JSON Processing example https github com jersey jersey tree master examples json processing webapp on how to use JSON Processing to consume produce JSON 8 1 4 Jackson 8 1 4 1 Dependency To use Jackson as your JSON provider you need to add jersey media json jackson module to your pom xml file 82 Support for Co
259. s priorities in the Step 4 in exactly opposite order So in JAX RS 1 x the keys are defined in the order primary media type secondary type declaration distance where custom providers have always precedence to internal providers If you want to force Jersey to use the algorithm compatible with JAX RS 1 x setup the property to ResourceConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ResourceConfig html or return from Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html from its get Properties method jersey config workers legacyOrdering true Documentation of this property can be found in the javadoc of MessageProperties http jersey java net nonav apidocs snapshot jersey org glassfish Jersey message MessageProperties html The algorithm for selection of MessageBodyReader T is similar including the incompatibility between JAX RS 2 0 and JAX RS 1 x and the property to workaround it The algorithm is defined as follows Procedure 7 2 MessageBodyReader T Selection Algorithm 1 Obtain the media type of the request If the request does not contain a Content Type header then use application octet stream media type Identify the Java type of the parameter whose value will be mapped from the entity body The Java type on the server is the type of the entity parameter of the resource method On the client it is the Class passed to readF rom method
260. s to subscribe to event notifications that originate On a server Server generates new events and sends these events back to the clients subscribed to receive the notifications In other words SSE offers a solution for a one way publish subscribe model A good example of the use case where SSE can be used is a simple message exchange RESTful service Clients POST new messages to the service and subscribe to receive messages from other clients Let s call the resource messages While POSTing a new message to this resource involves a typical HTTP request response communication between a client and the messages resource subscribing to receive all new message notifications would be hard and impractical to model with a sequence of standard request response message exchanges Using Server sent events provides a much more practical approach here You can use SSE to let clients subscribe to the messages resource via standard GET request use a SSE client API for example javascript API or Jersey Client SSE API and let the server broadcast new messages to all connected clients in the form of individual events in our case using Jersey Server SSE API Note that with Jersey a SSE support is implemented as an usual JAX RS resource method There s no need to do anything special to provide a SSE support in your Jersey JAX RS applications your SSE enabled resources are a standard part of your RESTful Web application that defines the REST API of your application The
261. s tte oe ederet et ee etie eee nor tite ee ve toe AE EU gery 125 11 3 Eink c ste eile este a whee eee E a E E A E E O ETN S 125 12 Programmatic API for Building Resources ce ceeeeeceeeeceeeceeceeeeeceeaeeeeeereeasereeaneneees 127 12 T Introduction sieren e Soie e ese RAE NERO E A N E 127 12 2 Programmatic Hello World example esses 127 12 2 1 Deployment of programmatic resources 2 0 0 0 ee cece e cence HH 129 12 3 Additional examples secs caved geese er Pero tee toten edere Paso bt vex EERE 130 12 4 Model processors 5 o or Re ode dae eset eU e ene quid e eee 131 iv Jersey 2 1 User Guide 13 Server Sent Events SSE Support eirese sp ieo oren ae aR Ep ERE eina E 134 13 1 What are Server Sent Events Corarnetori noot nee E a eme me meh Ne 134 13 2 When to use Server Sent Events postens o terano Ea HH eene 135 13 3 Jersey Server Sent Events API ice aen ee a aa EE EEE A EEE E TRER 135 13 4 Implementing SSE support in a JAX RS resource sessem 136 13 4 1 Simple SSE resource method 0 cece cence E E HH 136 13 4 2 Broadcasting with Jersey SSE 0 0 sss 139 13 5 Consuming SSE events with Jersey clients 1 0 0 0 cece cee ceeeceeece teen seca eene een eeee 141 13 5 1 Reading SSE events with Event Input esee seca eeneeneees 141 13 5 2 Asynchronous SSE processing with Event SOULCE oe ee eeeeeeeceeece eter eee 142 I NUNC T 146 TA Ve Securing
262. say we want to test this feature and we have helloworld example https github com jersey jersey tree master examples helloworld as a starting point All we need to do is add methods resources which consumes and produces XML and types mentioned above will be used 90 Support for Common Media Type Representations 8 2 2 Example 8 29 Low level XML test methods added to HelloWorldResource java POST Path StreamSource public StreamSource getStreamSource StreamSource streamSource return streamSource POST Path SAXSource public SAXSource getSAXSource SAXSource saxSource 10 return saxSource 11 12 13 POST 14 Path DOMSource 15 public DOMSource getDOMSource DOMSource domSource 16 return domSource 13 18 19 POST 20 Path Document 21 public Document getDocument Document document 22 return document 23 cO 10 01 CO Fo EF o Both MessageBodyWriter lt T gt and MessageBodyReader lt T gt are used in this case all we need is a POST request with some XML document as a request entity To keep this as simple as possible only root element with no content will be sent test You can create JAX RS client to do that or use some other tool for example cur1 curl v http localhost 8080 base helloworld StreamSource d test You should get exactly the same XML from our service as is present in the request in this case XML headers are added to resp
263. scribes how to setup SSL configuration on Jersey client using JAX RS API The SSL configuration is setup in ClientBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientBuilder html The client builder contains methods for definition of KeyStore http docs oracle com javase 6 docs api java security KeyStore html TrustStore http docs oracle com javase 6 docs api java security TrustStore html or entire SslContext http docs oracle com javase 6 docs api javax net ssl SslContext html See the following example 1 SSLContext ssl your configured SSL context 2 Client client ClientBuilder newBuilder sslContext ssl build 3 Response response client target https example com resource request ge The example above shows how to setup a custom SslContext to the ClientBuilder Creating a SslContext can be more difficult as you might need to init instance properly with the protocol KeyStore TrustStore etc Jersey offers a utility ClientConfig http jersey java net nonav apidocs snapshot Jersey org glassfish jersey SsIConfigurator html class that can be used to setup the SslContext The SslConfigurator can be configured based on standardized system properties for SSL configuration so for example you can configure the KeyStore file name using a environment variable javax net ssl keyStoreand SslConfigurator will use such a variable to setup the Ss1Context See javadoc of ClientConfig ht
264. se will be chunked and that the processing works asynchronously as such You do not need to inject AsyncResponse to start the asynchronous processing mode in this case Returning a ChunkedOut put instance from the method is enough to indicate the asynchronous processing Response headers will be sent to a client when the resource method returns and the client will wait for the stream of chunked data which you will be able to write from different thread using the same ChunkedOut put instance returned from the resource method earlier The following example demonstrates this use case 118 Asynchronous Services and Clients Example 10 4 ChunkedOutput example 1 Path resource 2 public class AsyncResource 3 QGET 4 public ChunkedOutput String getChunkedResponse 5 final ChunkedOutput lt String gt output new ChunkedOutput lt String gt String 6 7 new Thread 8 public void run 9 try 10 String chunk 11 12 while chunk getNextString null 13 output write chunk 14 1 5 catch IOException e 16 IOException thrown when writing the 17 chunks of response should be handled 18 finally 4 19 output close 20 simplified IOException thrown from 21 this close should be handled here 22 23 24 start 25 26 the output will be probably returned even befor 27 a first chunk is written by the new thread 28 return output 29 30 31 private String getNextS
265. ser will be used to validate the request entity These two ways in which validation of entities can be triggered can also be combined by including Valid in the list of constraints The presence of Valid will trigger validation of all the constraint annotations decorating a Java bean class Response entity bodies returned from resource methods can be validated in a similar manner by annotating the resource method itself To exemplify assuming both StandardUser and PremiumUser are required to be checked before returning a user the getUser method can be annotated as shown in Example 16 10 Response entity validation 166 Bean Validation Support Example 16 10 Response entity validation Path class MyResourceClass GET Path id Produces application xml Valid PremiumUser public User getUser PathParam id String id User u findUser id return u Note that PremiumUser is explicitly listed and StandardUser is triggered by the presence of the Valid annotation see definition of User class earlier in this section 16 4 4 Annotation Inheritance 16 5 The rules for inheritance of constraint annotation are defined in Bean Validation specification It is worth noting that these rules are incompatible with those defined by JAX RS Generally speaking constraint annotations in Bean Validation are cumulative can be strengthen across a given type hierarchy while JAX RS annotations are
266. servlet and pass the Application http jax rs spec java net nonav 2 O apidocs Javax ws rs core Application html implementation class name as one of the servlet s init param entries 42 Deploying a RESTful Web Service Example 4 6 Deployment of your application using Jersey specific servlet 1 lt web app gt 2 lt servlet gt 3 servlet name Jersey Web Application lt servlet name gt 4 servlet class org glassfish jersey servlet ServletContainer servlet 5 lt init param gt 6 lt param name gt javax ws rs Application lt param name gt 7 param value org foo rest MyApplication param value 8 init param 9 us 10 servlet 11 12 web app If there is no configuration to be set and deployed application consists only from resources and providers stored in particular packages Jersey can scan them and register automatically Example 4 7 Using Jersey specific servlet without an application model instance 1 web app 2 servlet 3 servlet name Jersey Web Application c servlet name 4 servlet class org glassfish jersey servlet ServletContainer servlet 5 lt init param gt 6 lt param name gt jersey config server provider packages lt param name gt 7 lt param value gt org foo rest org bar rest lt param value gt 8 init param 9 EM 10 servlet 11 12 web app JAX RS also provides the ability to obtain a container specific artifact from an Applic
267. sh jersey multipart FormDataParam html annotation This annotation in conjunction with the media type multipart form data should be used for submitting and consuming forms that contain files non ASCII data and binary data The type of the annotated parameter can be one of the following for more detailed description see javadoc to FormDataParam http jersey java net nonav apidocs snapshot jersey org glassfish jersey multipart FormDataParam html 99 Support for Common Media Type Representations FormDataBodyPart The value of the parameter will be the first named body part or nu11 if such a named body part is not present A List or Collection of FormDataBodyPart The value of the parameter will one or more named body parts with the same name or nu11 if such a named body part is not present FormDataContentDisposition The value of the parameter will be the content disposition of the first named body part part or nu11 if such a named body part is not present A List or Collection of FormDataContentDisposition The value of the parameter will one or more content dispositions of the named body parts with the same name or nu11 if such a named body part is not present A type for which a message body reader is available given the media type of the first named body part The value of the parameter will be the result of reading using the message body reader given the type T the media type of the named part and the bytes of t
268. simpleWABloexample WADL content 33 method 38 resource 39 resource path application wadl 40 method name GET id getWadl 41 response 42 representation mediaType application vnd sun wadl txml 43 representation mediaType application xml 44 response 45 method 46 method name OPTIONS id apply gt 47 request 48 representation mediaType gt 49 request 50 response 51 representation mediaType text plain 52 lt response gt 53 lt method gt 54 lt method name OPTIONS id apply gt 55 lt request gt 56 lt representation mediaType gt 57 lt request gt 58 lt response gt 59 lt representation mediaType gt 60 lt response gt 61 lt method gt 62 lt resource path path gt 63 lt param xmlns xs http www w3 org 2001 XMLSchema 64 type xs string style template name path gt 65 method name GET id geExternalGrammar gt 66 response 67 representation mediaType application xml 68 response 69 method 70 method name OPTIONS id apply 71 request 72 representation mediaType gt 73 request 74 response T5 lt representation mediaType text plain gt 76 lt response gt 771 method 78 method name OPTIONS id apply gt 79 request 80 representation mediaType gt 81 request 82 response 83 representation mediaType gt 84 lt response g
269. sisa osien o e ea ue ses eee lS eerte ce er ue esc Do E ipu ee PEE e aee oen 33 3 19 Sub resource locators with empty path sssssssssessesse HH HH 33 3 20 Sub resource locators returning sub type sess HH eere 34 3 21 Sub resource locators created from classes sssse e 34 3 22 Sub resource locators returning resource model sss 35 3 23 Infection ios in tee De rte ineo toto FE eret 36 3 24 Wrong injection into a singleton scope 2 0 cece ec ee ee cece HH mH eere 37 3 25 Injection of proxies into singleton esses Hem eher 37 3 26 Example of possible injections esses ememmem hen ent entren 39 4 1 Deployment agnostic application model sess eene meme hene 41 4 2 Reusing Jersey implementation in your custom application model sese 41 4 3 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 41 4 4 Configuration of maven war plugin in pom xm1 with Servlet 3 0 0 0 eee eeee eee 42 4 5 Deployment of a JAX RS application using web xm1 with Servlet 3 0 esses 42 4 6 Deployment of your application using Jersey specific servlet eee 43 4 7 Using Jersey specific servlet without an application model instance eseeesessse 43 5 1 POST request with form parameters cece cece cece ence II ehem mhi rentre 46
270. size of the buffer Note You can disable the Jersey outbound entity buffering by setting the buffer size to 0 7 2 1 4 Testing a MessageBodyWriter T Before testing the MyBeanMessageBodyWriter the writer must be registered as a custom JAX RS extension provider It should either be added to your application ResourceConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ResourceConfig html or returned from your custom Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html sub class or annotated with Provider http jax rs spec java net nonav 2 0 apidocs javax ws rs ext Provider html annotation to leverage JAX RS provider auto discovery feature After registering the MyBeanMessageBodyWriter and MyResource class in our application the request can be initiated in this example from Client API Example 7 5 Client code testing MyBeanMessageBodyWriter 1 WebTarget webTarget initialize web target to the context root 2 of example application 3 Response response webTarget path resource 4 request MediaType APPLICATION_XML get 5 System out println response getStatus 6 String myBeanXml response readEntity String class 7 System out println myBeanXml The client code initiates the GET which will be matched to the resource method MyResource getMyBean The response entity is de serialized as a String
271. sonp And make two requests 89 Support for Common Media Type Representations curl X GET http localhost 8080 jsonp will return eval value jsonp and the curl X GET http localhost 8080 jsonp jsonpCallback alert will return alert value jsonp Example You can take a look at a provided example available at JSON with Padding example https github com jersey jersey tree master examples json with padding 8 2 XML 8 2 1 As you probably already know Jersey uses MessageBodyWriter lt T gt s and MessageBodyReader lt T gt s to parse incoming requests and create outgoing responses Every user can create its own representation but this is not recommended way how to do things XML is proven standard for interchanging information especially in web services Jerseys supports low level data types used for direct manipulation and JAXB XML entities Low level XML support Jersey currently support several low level data types StreamSource http docs oracle com javase 7 docs api javax xml transform stream StreamSource html SAXSource http docs oracle com javase 7 docs api javax xml transform sax S AXSource html DOMSource http docs oracle com javase 7 docs api javax xml transform dom DOMSource html and Document http docs oracle com javase 7 docs api org w3c dom Document html You can use these types as the return type or as a method resource parameter Lets
272. source is a sub resource is returned more times during the matching In this situation only on instance will server the requests Per PerLookupg glassfish jersey prpheshintsropk Requestiuupemstance is created every time lookup it is needed for the processing even it handles the same scope request Singleton Singletofjavax inject Singleton In this scope there is only one instance per jax rs application Singleton resource can be either annotated with Singleton and its 35 JAX RS Application Resources and Sub Resources Scope AnnotatiopAnnotation full class Description name class can be registered using the instance of Application http Jax rs spec java net nonav 2 0 apidocs javax ws rs core A pplication 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 A pplication 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 bean setter methods The following presents an example of all such injection cases Example 3 23 Injectio
273. spec java net nonav 2 0 apidocs javax ws rs client WebTarget html and encapsulates an URI The fixed set of HTTP methods can be invoked based on the WebTarget The representations are Java types instances of which may contain links that new instances of WebTarget may be created from 5 2 Ease of use and reusing JAX RS artifacts Since a JAX RS component is represented as an annotated Java type it makes it easy to configure pass around and inject in ways that are 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 O apidocs javax ws rs core UriBuilder html and UriTemplate http jax rs spec java net nonav 2 O apidocs javax ws rs core UriTemplate html to safely build URIs 2 Built in support for Java types of representations such as byte String Number Boolean Character InputStream java io Reader File DataSource JAXB beans as well as additional Jersey specific JSON and Multi Part http jersey java net nonav apidocs snapshot jersey org glassfish jersey media multipart package info html support 3 Using the fluent builder style API pattern to make it easier to construct requests Some APIs like the Apache HTTP Client or HttpURLConnection http docs oracle com javase 6 docs api java net HttpURLConnection html can be rather hard to use and or require
274. ssage sss 98 8 46 Multipart sending Tiles ote sce oed erre e es tere P ep ve E P eh d 99 8 47 Resource method using MultiPart as input parameter return value esssssss 99 8 48 Use of QFormDataParam annotation 2 0 0 0 cece eece ence eece III HH eme herren 100 9 1 Container response filter rrt o sy Soames py soe ees hor eases dee Bea ee eR er Ee Ode e swans 102 9 2 Contamer request filter i3 a eec Rr e e Reto e ULM E o or E eeu E NE 103 1X Jersey 2 1 User Guide 9 3 Pre matching request liter seduce ewes ere ettet erre EEEE EPEA IRE ER REESS sees 104 9 4 Chent request filter ze apr ec So tees aed noah sen eee 105 9 5 GZIP Writer Interceptor r on idee itt ette ett inm iie Pee Deo ERR ssa eee tans IxS E Fe du ed nein bee ees 106 9 6 GZIP reader mterceptot oorr ere er ese Mc e or A ro rire 107 9 7 dNameBinding example uoce edet Ges teet retro pee repete pvp etd pet 110 9 8 Dynamic binding example ie ee e eee e teres ds oak mas Dentes eie e e E eee 112 9 9 Priorities example seo teniente ia ett ee o idee stout at E et Et b toit diete 113 10 T Smple dsync resource 3 noi p RUDI ui A ee BE ee ee 114 10 2 Simple async method with timeout ssssesssseI HH eene 116 10 3 CompletionCallback example serisini a eee cee cece ee He meme e mee hen nene 117 10 4 ChunkedOutput example s 2 i534 2 m tube a E te utes Ce eae n eR IR ee he RE
275. t 85 lt method gt 86 lt resource gt 87 lt resource gt 88 lt resources gt 89 lt application gt 151 WADL Support In the example above the returned application WADL is shown in full WADL schema is defined by the WADL specification The root WADL document element is the application It contains global information about the deployed JAX RS application Under this element there is a nested element resources which contains zero or more resource elements Each resource element describes a single deployed resource In our example there are only two root resources country id and application wadl The application wadl resource is the resource that was just requested in order to receive the application WADL document Even though WADL support is an additional feature in Jersey it is still a resource deployed in the resource model and therefore it is itself present in the returned WADL document The first resource element with the path country id is the element that describes our custom deployed resource This resource contains a GET method and three OPTIONS methods The GET method is our getCountry method defined in the sample There is a method name in the id attribute and Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html is described in the response representation WADL element OPTIONS methods are the methods that are automatically added by Jersey to each resource There is an OPTIONS
276. t Planet planet 4 System out println setPlanet planet SI After valid request is made service will print out string representation of Planet which can look like Planet id 2 name Mars radius 1 51 With JAX RS client you can do webTarget path planet post planet If there is a need for some other non default XML representation other JAXB annotations would need to be used This process is usually simplified by generating java source from XML Schema which is done by x jc which is XML to java compiler and it is part of JAXB POJOs Sometimes you can t don t want to add JAXB annotations to source code and you still want to have resources consuming and producing XML representation of your classes In this case JAXBElement http jaxb java net nonav 2 2 7 docs api javax xml bind JAXBElement html class should help you Let s redo planet resource but this time we won t have an XmlRootElement http jaxb java net nonav 2 2 7 docs api javax xml bind annotation XmlRootElement html annotation on Planet class Example 8 33 Resource class JAXBElement 1 Path planet 2 public class Resource 3 4 GET 5 Produces MediaType APPLICATION XML 6 public JAXBElement Planet getPlanet 7 Planet planet new Planet 8 9 planet id 1 10 planet name Earth 11 planet radius 1 0 12 13 return new JAXBElement lt Planet gt new QName planet Planet class 14 15 16 POST T3 Cons
277. t xml version 1 0 encoding UTF 8 gt lt validationErrors gt lt validationError gt lt message gt Contact with given ID does not exist lt message gt lt messageTemplate gt contact does not exist lt messageTemplate gt lt path gt ContactCardResource getContact lt return value amp gt path lt validationError gt lt validationErrors gt 171 Bean Validation Support Example 16 17 ValidationError to application json HTTP 1 1 500 Internal Server Error Content Length 174 Content Type application json Vary Accept Server Jetty 6 1 24 HE message Contact with given ID does not exist messageTemplate contact does not exist path ContactCardResource getContact lt return value gt 16 8 Example To see a complete wroking example of using Bean Validation JSR 349 with Jersey refer to the Bean Validation example https github com jersey jersey tree master examples bean validation webapp 172 Chapter 17 MVC Templates Jersey provides an extension to support the Model View Controller MVC design pattern In the context of Jersey components the Controller from the MVC pattern corresponds to a resource class or method the View to a template bound to the resource class or method and the Model to a Java object or a Java bean returned from a resource method 17 1 Dependencies Jersey MVC templating support is provided by Jersey as
278. t method arguments define the names of the events to receive and can be omitted If names are defined the listener will be associated with the named events and will only invoked for events with a name from the set of defined event names It will not be invoked for events with any other name or for events without a name Important It is a common mistake to think that unnamed events will be processed by listeners that are registered to process events from a particular name set That is NOT the case Unnamed events are only processed by listeners that are not name bound The same limitation applied to HTML5 Javascript SSE Client API supported by modern browsers 143 Server Sent Events SSE Support After a connection to the server is opened by calling the open method on the event source the event Source starts listening to events When an event named message to client comes the listener will be executed by the event source If any other event comes with a name different from message to client the registered listener is not invoked Once the client is done with processing and does not want to receive events anymore it closes the connection by calling the close method on the event source The listener from the example above will print the following output ssage to cli ssage to cli ssage to cli ssage to cli ssage to cli ssage to cli ssage to cli ssage to cli ssage to cli ssage to cli t Hello wor
279. t role name gt customer lt role name gt 15 lt auth constraint gt 16 lt security constraint gt 17 lt login config gt 18 auth method BASIC auth method 19 realm name my defaul realm realm name 20 lt login config gt The example secures two kinds of URI namespaces using the HTTP Basic Authentication rest admin will be accessible only for user group admin and rest orders will be accessible for customer 147 Security user group This security configuration does not use JAX RS or Jersey features at all as it is enforced by the Servlet container even before a request reaches the Jersey application Keeping this security constrains up to date with your JAX RS application might not be easy as whenever you change the Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html annotations on your resource classes you may need to update also the web xm1 security configurations to reflect the changed JAX RS resource paths Therefore Jersey offers a more flexible solution based on placing standard Java EE security annotations directly on JAX RS resource classes and methods 14 1 2 2 Securing JAX RS resources with annotations With Jersey you can define the access to resources based on the user group using annotations You can for example define that only a user group admin can execute specific resource method To do that you firstly need to register RolesAllowedDynamicFeature http jers
280. tSource API component used to read SSE events asynchronously http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventSource html The usage of the Event Source is shown on the following example 142 Server Sent Events SSE Support Example 13 3 Registering EventListener with EventSource 1 Client client ClientBuilder newBuilder 2 register SseFeature class build 3 WebTarget target client target http example com events 4 EventSource eventSource new EventSource target false 9 6 7 8 EventListener listener new EventListener QOverride public void onEvent InboundEvent inboundEvent try 9 System out printin inboundEvent getName 10 inboundEvent getData String class 11 catch IOException e 12 throw new RuntimeException 13 Error when deserializing of data 14 15 16 H 17 eventSource register listener message to client 18 eventSource open 9m X4 20 eventSource close In this example the client code again connects to the server where the SseResource from the Example 13 1 Simple SSE resource method is deployed The Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html instance is again created and initialized with SseFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse SseFeature html Then t
281. tchingFilter implements ContainerRequestFilter o 10 OB WN EF Ne 10 Override 11 public void filter ContainerRequestContext requestContext 12 throws IOException 13 change all PUT methods to POST 14 if requestContext getMethod equals PUT l5 requestContext setMethod POST 16 17 18 The PreMatchingFilter is a simple pre matching filter which changes all PUT HTTP methods to POST This might be useful when you want to always handle these PUT and POST HTTP methods with the same Java code After the PreMatchingFilter has been invoked the rest of the request processing will behave as if the POST HTTP method was originally used You cannot do this in post matching filters standard filters without GP reMat ching annotation as the resource method is already matched selected An attempt to tweak the original HTTP method in a post matching filter would cause an IllegalArgumentException As written above pre matching filters can fully influence the request matching process which means you can even modify request URI in a pre matching filter by invoking the setRequestUri URI method of ContainerRequestFilter so that a different resource would be matched Like in post matching filters you can abort a response in pre matching filters too 104 Filters and Interceptors 9 2 2 Client fillers Client filters are similar to container filters The response can also be aborted in the ClientRequ
282. te represents a non interpolated error message or key from your constraint definition e g javax validation constraints NotNull message path contains information about the path in the validated object graph to the property holding invalid value and invalidValue is the string representation of the invalid value itself Here are few examples of Validat ionError messages sent to client 170 Bean Validation Support Example 16 14 ValidationError to text plain HTTP 1 1 500 Internal Server Error Content Length 114 Content Type text plain Vary Accept Server Jetty 6 1 24 Contact with given ID does not exist path ContactCardResource getContact lt retu Example 16 15 ValidationError to text html HTTP 1 1 500 Internal Server Error Content Length Content Type text plain Vary Accept Server Jetty 6 1 24 div class validation errors gt lt div class validation error span class message gt Contact with given ID does not exist lt span gt lt span class path gt lt strong gt path lt strong gt ContactCardResource getContact lt return value gt lt span gt lt span class invalid value gt lt strong gt invalidValue lt strong gt null lt span gt lt div gt lt div gt Example 16 16 ValidationError to application xml HTTP 1 1 500 Internal Server Error Content Length Content Type text plain Vary Accept Server Jetty 6 1 24 l
283. ter ContainerRequestContext requestContext tT throws IOException T2 13 final SecurityContext securityContext 14 requestContext getSecurityContext 15 if securityContext null 16 securityContext isUserInRole privileged 17 18 requestContext abortWith Response 19 status Response Status UNAUTHORIZED 20 entity User cannot access the resource 21 build 22 23 24 The request filter is similar to the response filter but does not have access to the ContainerResponseContext as no response is accessible yet Response filter inherits from ClientResponseFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientResponseFilter html Request filter is executed before the resource method is run and before the response is created The filter has possibility to manipulate the request parameters including request headers or entity The AuthorizationRequestFilter in the example checks whether the authenticated user is in the privileged role If it is not then the request is aborted by calling ContainerRequestContext abortWith Respons response method The method is intended to be called from the request filter in situation when the request should not be processed further in the standard processing chain When the ilter method is finished the response passed as a parameter 103 Filters and Interceptors to the abortWith method is used to respond to the request Response filters if any ar
284. ter 4 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 4 1 Deployment agnostic application model 1 public class MyApplication extends Application 2 Override 3 public Set lt Class lt gt gt getClasses 4 Set lt Class lt gt gt s new HashSet lt Class lt gt gt 5 s add HelloWorldResource class 6 return S 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 on provider classes in packages org foo rest org bar rest and in any sub packages of those two Example 4 2 Reusing Jersey implementation in your custom application model 1 public class MyApplication extends ResourceConfig 2 public MyApplication 3 packages org foo rest org bar rest 4 5 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
285. the messag 29 JAX RS Application Resources and Sub Resources 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 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 html is used this way to aggregate more request parameters into a single bean 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 rs BeanParam html 1 public class MyBeanParam 2 PathParam p 3 private String pathParam 4 5 MatrixParam
286. 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 Example 3 8 Query parameters 1 Path smooth 2 GET 3 public Response smooth 4 DefaultValue 2 QueryParam step int step 5 DefaultValue true QueryParam min m boolean hasMin 6 DefaultValue true QueryParam max m boolean hasMax 7 DefaultValue
287. tion Tests might require some advanced client configuration This is possible by overriding configureClient ClientConfig clientConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey test JerseyTest html configureClient org glassfish jersey client ClientConfig method Typical use case for this is registering more providers such as MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html s or MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html s or enabling additional features 18 3 4 Accessing the logged test records programmatically Sometimes you might need to check a logged message as part of your test assertions For this purpose Jersey Test Framework provides convenient access to the logged records via JerseyTest getLastLoggedRecord http jersey java net nonav apidocs snapshot jersey org glassfish jersey test JerseyTest html getLastLoggedRecord and JerseyTest getLoggedRecords http jersey java net nonav apidocs snapshot jersey org glassfish jersey test JerseyTest html getLoggedRecords methods Note that this feature is not enabled by default see TestProperties RECORD_LOG_LEVEL http jersey java net nonav apidocs snapshot jersey org glassfish jersey test TestProperties html RECORD_LOG_LEVEL for more information 184 Chapter 19 Building and Testing Jersey 19 1
288. tion xml with generic type Object MyBeanMessageBodyWriter Produces application xml with generic type lt MyBean gt The algorithm executed by a JAX RS runtime to select a proper MessageBodyWriter lt T gt implementation is illustrated in Procedure 7 1 MessageBodyWriter lt T gt Selection Algorithm Procedure 7 1 MessageBodyWriter lt T gt Selection Algorithm 1 Obtain the object that will be mapped to the message entity body For a return type of Response or subclasses the object is the value of the entity property for other return types it is the returned object So in our case for the resource method get MyBean the type will be MyBean 2 Determine the media type of the response In our case for resource method getMyBean annotated with Produces application xml the media type will be application xml 3 Select the set of MessageBody Writer providers that support the object and media type of the message entity body In our case for entity media type application xml and type MyBean the appropriate MessageBodyWriter lt T gt will be the A B D and MyBeanMessageBodyWriter The provider C does not define the appropriate media type A and B are fine as their type is more generic and compatible with application xml 4 Sort the selected MessageBodyWriter providers with a primary key of generic type where providers whose generic type is the nearest superclass of the object class are sorted first and a secon
289. tity or representation as a stream of bytes use InputStream as follows InputStream in response readEntity 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 a File instance as follows File f webTarget request post Entity entity f MediaType TEXT PLAIN TYP LH Adding support for new representations The support for new application defined representations as Java types requires the implementation of the same JAX RS entity provider extension interfaces as for the server side JAX RS 52 Client API API namely MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html and MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html respectively for request and response entities or inbound and outbound representations Classes or implementations of the provider based interfaces need to be registered as providers within the JAX RS or Jersey Client API components that implement Configurable contract ClientBuilder Client WebTarget or ClientConfig as was shown in the earlier sections Some media types are provided in the form of JAX RS Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature html a concept that allows the extension prov
290. to org glassfish jersey connectors jersey grizzly connector alternatively Please note again that the Connector http jersey java net nonav apidocs snapshot jersey org glassfish jersey client spi Connector html SPI is not a feature of JAX RS but is a Jersey specific extension API that will only work with Jersey Following example shows how to setup the custom Connector to the Jersey client ClientConfig clientConfig new ClientConfig Connector connector new GrizzlyConnector clientConfig clientConfig connector connector Client client ClientBuilder newClient clientConfig A C0 PKN PF Client accepts as as a constructor argument a Configurable instance Jersey implementation of the Configurable provider for the client is C1ientConfig By using the Jersey ClientConfig you can configure the custom Connector into the ClientConfig The GrizzlyConnector is used as a custom connector in the example above Please note that the connector cannot be registered as a provider using Configurable register at the moment 5 6 Using client request and response filters Filtering requests and responses can provide useful lower level concept focused on a certain independent aspect or domain that is decoupled 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 Jersey contains the follow
291. too much code to do something relatively simple especially when the client needs to understand different payload representations This is why the Jersey implementation of JAX RS Client API provides support for wrapping HttpUrlConnection and the Apache HTTP client Thus it is possible to get the benefits of the established JAX RS implementations and features while getting the ease of use benefit of the simple design of the JAX RS client API For example with a low level HTTP client library sending a POST request with a bunch of typed HTML form parameters and receiving a response de serialized into a JAXB bean is not straightforward at all With the new JAX RS Client API supported by Jersey this task is very easy Example 5 1 POST request with form parameters Client client ClientBuilder newClient WebTarget target client target http localhost 9998 path resource Form form new Form form param x foo form param y bar MyJAXBBean bean target request MediaType APPLICATION JSON TYPE post Entity entity form MediaType APPLICATION FORM URLENCODED TYPE MyJAXBBean class Ee A ONT O G 0 Pho np ere In the Example 5 1 POST request with form parameters a new WebTarget instance is created using a new Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html instance first next a Form http jax rs spec java net nonav 2 0 apidocs javax ws rs
292. torContext context Thus EmailValidator applies to values annotated with Emai 1 that are of type St ring Validators for other Java types can be defined for the same constraint annotation 16 4 3 Entity Validation Request entity bodies can be mapped to resource method parameters There are two ways in which these entities can be validated If the request entity is mapped to a Java bean whose class is decorated with Bean Validation annotations then validation can be enabled using Valid http docs jboss org hibernate beanvalidation spec 1 1 api javax validation Valid html as in Example 16 8 Entity validation 165 Bean Validation Support Example 16 8 Entity validation StandardUser class User NotNull private String firstName Path class MyResourceClass POST Consumes application xml public void registerUser Valid User user In this case the validator associated with StandardUser as well as those for non class level constraints like Not Nu11 will be called to verify the request entity mapped to user Alternatively a new annotation can be defined and used directly on the resource method parameter Example 16 9 Entity validation 2 Example 16 9 Entity validation 2 Path class MyResourceClass POST Consumes application xml public void registerUser PremiumUser User user In the example above GP remiumUser rather than St andardU
293. tp jax TS spec java net nonav 2 0 apidocs javax ws rs client Client html Wab Tangetrsey api client WebResource http jexsey java net reonav spedqas d rie jeonay 2 0 apid cs fandx yessey ngi client WebRasgetrh rhtin Vb Fangetsess apyalientreys MW lsResaurenethods by calling fhttpVArget request async jexsey java net menav spedqos d ray 191 Migrating from Jersey 1 x Dy RS lhss Class jeonay 2 0 apid cs fandx yessey ngi client MishiEMiattEatgol rce html The following sub sections show code examples 20 2 1 Making a simple client request Jersey 1 x way Client client Client create WebResource webResource client resource restURL path myresource param String result webResource pathParam param value get String class JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL path myresource param String result target pathParam param value get String class 20 2 2 Registering filters Jersey 1 x way Client client Client create WebResource webResource client resource restURL webResource addFilter new HTTPBasicAuthFilter username password JAX RS 2 0 way Client client ClientFactory newClient WebTarget target client target restURL target register new HttpBasicAut
294. tp jersey java net nonav apidocs snapshot jersey org glassfish jersey SslConfigurator html for more details The following code shows how a SslConfigurator can be used to create a custom SSL context 1 SslConfigurator sslConfig SslConfigurator newInstance 2 trustStoreFile truststore_client 3 trustStorePassword secret password for truststore 4 keyStoreFile keystore client 5 keyPassword secret password for keystore 6 7 SSLContext sslContext sslConfig createSSLContext 8 Client client ClientBuilder newBuilder sslContext sslContext build Note that you can also setup KeyStore and TrustStore directly on a ClientBuilder instance without wrapping them into the Ss1Context However if you setup a Ss1Context it will override any previously defined KeyStore and TrustStore settings ClientBuilder also offers a method for defining a custom HostnameVerifier http docs oracle com javase 6 docs api javax net ssl 54 Client API HostnameVerifier html implementation HostnameVerifier implementations are invoked when default host URL verification fails Important Note that to utilize HTTP with SSL it is necessary to utilize the https scheme Currently the default connector HttpUrlConnector based on HttpUrlConnection implements support for SSL defined by JAX RS configuration discussed in this sample 5 7 1 HTTP Basic Authentication Support Jersey contains a filter that allows client
295. tps jersey java net project info 2 1 jersey project osgi helloworld webapp lib bundle dependencies html OSGi Helloworld bundle osgi helloworld webapp https jersey java net project info 2 1 jersey project osgi helloworld webapp war bundle dependencies html OSGi Helloworld war osgi http service https jersey java net OSGi Helloworld 17 Modules and dependencies project info 2 1 jersey project osgi http service bundle dependencies html osgi http service https jersey java net project info 2 1 jersey project osgi http service dependencies html OSGi Helloworld reload https jersey java net project info 2 1 jersey project reload dependencies html Jersey resource configuration reload example server async https jersey java net project info 2 1 jersey project server async dependencies html Jersey JAX RS asynchronous server side example server async managed https jersey java net project info 2 1 jersey project server async managed dependencies html Jersey JAX RS asynchronous server side example with custom Jersey executor providers server async standalone https jersey java net project info 2 1 jersey project server async standalone server async standalone client dependencies html Standalone Jersey JAX RS asynchronous server side processing example server se
296. tring 32 long running operation that returns 33 next string or null if no other string is accessible 34 35 The example above defines a GET method that returns a ChunkedOut put instance The generic type of ChunkedOutput defines the chunk types in this case chunks are Strings Before the instance is returned a new thread is started that writes individual chunks into the chunked output instance named output Once the original thread returns from the resource method Jersey runtime writes headers to the container response but does not close the client connection yet and waits for the response data to be written to the chunked out put New thread in a loop calls the method getNextString whichreturns a next String or nu11 if no other String exists the method could for example load latest data from the database Returned Strings are written to the chunked output Such a written chunks are internally written to the container response and client can read them At the end the chunked output is closed which determines the end of the chunked response Please note that you must close the output explicitly in order to close the client connection as Jersey does not implicitly know when you are finished with writing the chunks A chunked output can be processed also from threads created from another request as it is explained in the sections above This means that one resource method may e g only return a ChunkedOut put instance and other res
297. tructure that we saw in the WADL document returned for the whole Jersey application earlier The main difference here is that the only resource is the resource to which the OPTIONS HTTP request was sent The resource has now path country 15 and not country id as the path parameter id was already specified in the request to this concrete resource Another a more complex WADL example is shown in the next example 153 WADL Support Example 15 4 More complex WADL example JAX RS resource definition 1 Path customer id 2 public static class CustomerResource 3 ora oO ws 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 private CustomerService customerService GET public Customer get PathParam id int id return customerService getCustomerById id QPUT public Customer put Customer customer return customerService updateCustomer customer Path address public CustomerAddressSubResource getCustomerAddress PathParam id int return new CustomerAddressSubResource id GPath additional info public Object getAdditionallnfoSubResource 8PathParam id int id return new CustomerAddressSubResource id public static class CustomerAddressSubResource private final int customerIg private CustomerService customerService public CustomerAddressSubResource int custome
298. true QueryParam last m boolean hasLast 8 DefaultValue blue QueryParam min color ColorParam minColor 9 DefaultValue green QueryParam max color ColorParam maxColor 10 DefaultValue red QueryParam last color ColorParam lastColor 11 12 53 If a query parameter step exists in the query component of the request URI then the step value will be will extracted and parsed as a 32 bit signed integer and assigned to the step method parameter If step does not exist then a default value of 2 as declared in the DefaultValue http jax rs spec java net nonav 2 0 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 27 JAX RS Application Resources and Sub Resources Example 3 9 Custom Java type for consuming request parameters 1 public class ColorParam extends Color 2 3 public ColorParam String s 4 super getRGB s 5 6 7 private static int getRGB String s 8 if s charAt 0 9 try 10 Color c Color decode 0x s substring 1 11 return c getRGB 12 catch NumberFormatException e 13 throw new WebApplicationException 400 14 15 else 16 try 1 7 Field f Color class getField s
299. ttp 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 configured When an application throws an EntityNotFoundException http docs oracle com javaee 6 api javax persistence EntityNotFoundException html the toResponse method of the EntityNotFoundMapper instance will be invoked Jersey supports extension of the exception mappers These extended mappers must implement the org glassfish jersey spi ExtendedExceptionMapper interface This interface additionally defines method isMappable Throwable which will be invoked by the Jersey runtime 59 Representations and Responses when exception is thrown and this provider is considered as mappable based on the exception type Using this method the provider can reject mapping of the exception before the method t oResponse is invoked The provider can for example check the exception parameters and based on them return false and let other provider to be chosen for the exception mapping 6 4 Conditional GETs and Returning 304 Not Modified Responses Conditional GETs are a great way to reduce bandwidth and potentially improve on the server side performance depending on how the information used to determine conditions is calculated A well
300. ttps jersey java net project info 2 1 jersey project https clientserver grizzly dependencies html Jersey HTTPS Client Server example on Grizzly jaxb https jersey java net project info 2 1 jersey project jaxb dependencies html Jersey JAXB example jaxrs types injection https jersey java net project info 2 1 jersey project jaxrs types injection dependencies html json jackson https jersey java net project info 2 1 jersey project json jackson dependencies html Jersey JAX RS types injection example Jersey JSON with Jackson example json jettison https Jersey JSON with Jettison JAXB example 16 Modules and dependencies jersey java net project info 2 1 jersey project json jettison dependencies html json moxy https jersey java net project info 2 1 jersey project json moxy dependencies html Jersey JSON with MOXy example json with padding https jersey java net project info 2 1 jersey project json with padding dependencies html Jersey JSON with Padding example managed client https jersey java net project info 2 1 jersey project managed client dependencies html Jersey managed client example osgi helloworld webapp https jersey java net project info 2 1 jersey project osgi helloworld webapp dependencies html OSGi Helloworld osgi helloworld webapp ht
301. turns a type CustomerAddressSubResource in the method declaration and also in the WADL there is a resource element for such a sub resource with full internal description The second method getAdditionalInfoSubResource returns only an Object in the method declaration While this is correct from the JAX RS perspective as the real returned type can be computed from a request information it creates a problem for WADL generator because WADL is generated based on the static configuration of the JAX RS application resources The WADL generator does not know what type would be actually returned to a request at run time That is the reason why the nested resource element with path additional info does not contain any information about the supported resource representations The CustomerAddressSubResource sub resource described in the nested element resource path address gt does not contain an OPTIONS method While these methods are in fact generated by Jersey for the sub resource Jersey WADL generator does not currently support adding these methods to the sub resource description This should be addressed in the near future Still there are two user defined resource methods handling HTTP GET and PUT requests The sub resource method getDeliveryAddress is represented as a separate nested resource with path sub Should there be more sub resource methods defined with path sub then all these method descriptions would be placed into the same resource
302. u will also need at least Java SE 6 to be able to compile and run your application 2 2 Introduction to Jersey dependencies Jersey is built assembled and installed using Apache Maven http maven apache org Non snapshot Jersey releases are deployed to the Central Maven Repository http search maven org Jersey is also being deployed to Java Net Maven repositories http maven java net which contain also Jersey SNAPSHOT versions In case you would want to test the latest development builds check out the Java Net Snapshots Maven repository https maven java net content repositories snapshots org glassfish jersey An application that uses Jersey and depends on Jersey modules is in turn required to also include in the application dependencies the set of 3rd party modules that Jersey modules depend on Jersey is designed as a pluggable component architecture and different applications can therefore require different sets of Jersey modules This also means that the set of external Jersey dependencies required to be included in the application dependencies may vary in each application based on the Jersey modules that are being used by the application Developers using Maven or a Maven aware build system in their projects are likely to find it easier to include and manage dependencies of their applications compared to developers using ant or other build systems that are not compatible with Maven This document will explain to both maven and no
303. umes MediaType APPLICATION XML 18 public void setPlanet JAXBElement lt Planet gt planet 19 System out println setPlanet planet getValue 20 21 As you can see everything is little more complicated with JAXBE1ement This is because now you need to explicitly set element name for P Lanet class XML representation Client side is even more complicated 93 Support for Common Media Type Representations than server side because you can t do JAXBElement Planet so JAX RS client API provides way how to workaround it by declaring subclass of GenericType lt T gt Example 8 34 Client side JAXBElement 1 GET 2 GenericType lt JAXBElement lt Planet gt gt planetType new GenericType lt JAXBElement lt Plan 3 4 Planet planet Planet webTarget path planet request MediaType APPLICATIO 5 System out printin planet 6 7 POST 8 planet new Planet 9 10 11 12 webTarget path planet post new JAXBElement Planet new QName planet Pla 8 2 4 Using custom JAXBContext In some scenarios you can take advantage of using custom JAXBContext http jaxb java net nonav 2 2 7 docs api javax xml bind JAXB Context html Creating JAXBContext is an expensive operation and if you already have one created same instance can be used by Jersey Other possible use case for this is when you need to set some specific things to JAXBContext for example to set a different class
304. urce methods are aggregated from resource method and from resource class But this is probably just an edge case which will not be used so often Note that global filters are executed always so even for resource methods which have any name binding annotations 9 6 Dynamic binding Dynamic binding is a way how to assign filters and interceptors to the resource methods in a dynamic manner Name binding from the previous chapter uses a static approach and changes to binding require source code change and recompilation With dynamic binding you can implement code which defines bindings during the application initialization time The following example shows how to implement dynamic binding 111 Filters and Interceptors Example 9 8 Dynamic binding example 1 2 import javax ws rs core FeatureContext 3 import javax ws rs container DynamicFeature 4 5 6 GPath helloworld 7 public class HelloWorldResource 8 9 GET 10 Produces text plain 11 public String getHello 12 return Hello World 13 14 T5 GET 16 Path too much data L7 public String getVeryLongString 18 String str very long string 19 return str 20 21 22 23 This dynamic binding provider registers GZIPWriterInterceptor 24 only for HelloWorldResource and methods that contain 25 VeryLongString in their name It will be executed during 26 application initialization phase 27 public cl
305. urce resource resourceBuilder build 30 registerResources resource WW w WN EF wa 128 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 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 the 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 directl
306. ured parameters ssseee ence eeeeeeeeeeeaees 89 8 29 Low level XML test methods added to He11oWorldResource Jjava eese 91 8 30 Planet class s ee e ee Re d e e ah a A eed 92 8 3 Resource Class serere eee e ERROR e oca ete oae sene les ge o N e I odese t eed teo tree SERERE 92 8 32 Method for consuming Planet esessesseseeeee e e me He e mee mene rennen 93 8 33 Resource class JAXBbElement 5 oerte eed ete e eere ene deor po ome re Doe ere p 93 8 34 Chent side TAXBElemeht rere es e UL e d eae 94 8 35 PlanetJAXB Conte xtProvider s iiseetiect pese tenet dese teer suet esee tide tte dese zoe doeet eet dee dese 94 8 36 Using Provider with JAX RS client 2 00 cece e cece ce eece e em eme eere 95 8 37 Add jersey media moxy dependency sss eee eene 95 8 38 Register the MoxyXmlFeature class sess eem em en ee mene E SE 95 8 39 Configure and register an MoxyXmlFeature instance sesseeseeee e 95 8 40 Building client with MultiPart feature enabled sssss eecaeeea cece sean eene ones 96 8 41 Creating JAX RS application with MultiPart feature enabled eese 97 8 42 Mut S3Part entty i eov Ue Ie RATER ot en caido ete vate deh end ete SES 97 8 43 M ltiPart entity am DTTP message outset er e eT Serene AINE EE N EE dee eit 97 8 44 FortmDabaM ltiPart en ty 5 IINE IDA 98 8 45 FormDataMultiPart entity in HTTP me
307. ustom ClientRequestFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client RequestFilter html you can call get Property method on the supplied ClientRequestContext http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientRequestContext html to read a request property Note that these request properties are different from the configuration properties set on Configurable As mentioned earlier an Invocation instance provides generic invocation API to invoke the HTTP request it represents either synchronously or asynchronously See the Chapter 10 Asynchronous Services and Clients for more information on asynchronous invocations In case you do not want to do any batch processing on your HTTP request invocations prior to invoking them there is another more convenient approach that you can use to invoke your requests directly from an Invocation Builder instance This approach is demonstrated in the next Java code listing 1 Response response invocationBuilder get While short the code in the example performs multiple actions First it will build the the request from the invocationBuilder The URI of request will be http example com rest resource helloworld greeting Hi 20World and the request will contain some header true and Accept text plain headers The request will then pass trough all configured request filters AnotherClientFilter ThirdClientFilter and FilterForExampleCom Once processed by t
308. ustom Entity Providers A best way how to learn about entity providers is to walk through an example of writing one Therefore we will describe here the process of implementing a custom MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html and MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyReader html using a practical example Let s first setup the stage by defining a JAX RS resource class for the server side story of our application 62 JAX RS Enti ty Providers Example 7 1 Example resource class 1 Path resource 2 public class MyResource 42 3 GET 4 Produces application xml 5 public MyBean getMyBean 6 return new MyBean Hello World 7 8 9 POST 10 Consumes application xml de public String postMyBean MyBean myBean 12 return myBean anyString 13 14 ET and POST res The resource class defines GI an instance of MyBean ource methods Both methods work with an entity that is The MyBean class is defined in the next example Example 7 2 MyBean entity class 1 QXmlRootElement 2 public class MyBean 3 XmlElement 4 public String anyString 5 XmlElement 6 public int anyNumber 7 8 public MyBean String anyString int anyNumber 9 this anyString anyString 10 this anyNumber anyNumber 11 12 13 empty constru
309. validation dependencies html on the classpath This module depends directly on Hibernate Validator http www hibernate org subprojects validator html which provides a most commonly used implementation of the Bean Validation API spec If you want to use a different implementation of the Bean Validation API use standard Maven mechanisms to exclude Hibernate Validator from the modules dependencies and add a dependency of your own dependency groupId org glassfish jersey ext groupId artifactId jersey bean validation artifactId version 2 1 version lt exclusions gt lt exclusion gt groupId org hibernate groupId lt artifactId gt hibernate validator lt artifactId gt lt exclusion gt lt exclusions gt lt dependency gt Enabling Bean Validation in Jersey As stated in Section 4 1 Auto Discoverable Features Jersey Bean Validation is one of the modules where you don t need to explicitly register it s Feat ures ValidationFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey server validation ValidationFeature html on the server as its features are automatically discovered and registered when you add the jersey bean validation module to your classpath There are three Jersey specific properties that could disable automatic discovery and registration of Jersey Bean Validation integration module 159 Bean Validation Support e CommonProperties FEATURE_AUTO
310. ventOutput eventOutput new EventOutput 14 new Thread new Runnable 15 Override 16 public void run 17 try 18 for int i 0 i lt 10 i 19 code that waits 1 second 20 final OutboundEvent Builder eventBuilder 21 new OutboundEvent Builder 22 eventBuilder name message to client 23 eventBuilder data String class 24 Hello world i 29 final OutboundEvent event eventBuilder build 26 eventOutput write event 27 28 catch IOException e 29 throw new RuntimeException 30 Error when writing the event e 31 finally 32 try 33 eventOutput close 34 catch IOException ioClose 35 throw new RuntimeException 36 Error when closing the event output ioClose 37 38 39 40 start 41 return eventOutput 42 43 The code above defines the resource deployed on URI events This resource has a single GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html resource method which returns as an entity EventOutput http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventOutput html an extension of generic Jersey ChunkedOutput http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ChunkedOuptut html API for output chunked message processing 137 Server Sent Events SSE Support Note If you are not familiar with ChunkedOutput and ChunkedInput see the As
311. ventSource http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventSource html and EventListener http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse EventListener html classes that further improve convenience of processing new inbound SSE events 13 4 Implementing SSE support in a JAX RS resource 13 4 1 Simple SSE resource method Firstly you need to add a Jersey SSE module dependency to your project as shown in the earlier section and register the SseFeature http jersey java net nonav apidocs snapshot jersey org glassfish jersey media sse SseFeature html from this module in your Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html or ResourceConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ResourceConfig html Once done you are ready to add SSE support to your resource 136 Server Sent Events SSE Support Example 13 1 Simple SSE resource method l i 2 import org glassfish jersey media sse EventOutput 3 import org glassfish jersey media sse OutboundEvent 4 import org glassfish jersey media sse SseFeature 5 6 7 Path events 8 public static class SseResource 9 10 GET tI Produces SseFeature SERVER_SENT_EVENTS 12 public EventOutput getServerSentEvents 13 final E
312. vided by Jersey JSP Freemarker you will need to add the base jersey mvc https jersey java net project info 2 1 jersey project jersey mvc dependencies html module into the list of your dependencies dependency groupId org glassfish jersey ext groupId lt artifactId gt jersey mvc lt artifactId gt lt version gt 2 1 lt version gt lt dependency gt To use one of the templating engines for which Jersey provides the integration implementation JSP Freemarker in your project you need to add the jersey mvc jsp https jersey java net project info 2 1 jersey project jersey mvc jsp dependencies html or jersey mvc freemarker https jersey java net project info 2 1 jersey project jersey mvc freemarker dependencies html module to your pom xml respectively dependency 173 MVC Templates groupId org glassfish jersey ext groupId lt artifactId gt jersey mvc jsp lt artifactId gt lt version gt 2 1 lt version gt lt dependency gt lt dependency gt groupId org glassfish jersey ext groupId artifactId jersey mvc freemarker artifactId version 2 1 version dependency Both of these modules transitively depend on the base jersey mvc so it is not necessary to add the base jersey mvc module explicitly into your dependency list however it is a recommended Maven practice to do so If you are not using Maven you need to make sure to have all required transitive depende
313. will not improve the request processing time perceived by the client It will however increase the throughput of the server by releasing the initial request processing thread back to the I O container while the request may still be waiting in a queue for processing or the processing may still be running on another dedicated thread The released I O container thread can be used to accept and process new incoming request connections The following example shows a simple asynchronous resource method defined using the new JAX RS async API Example 10 1 Simple async resource 1 Path resource 2 public class AsyncResource 3 GET 4 public void asyncGet Suspended final AsyncResponse asyncResponse 5 6 new Thread new Runnable 7 Override 8 public void run 9 String result veryExpensiveOperation 10 asyncResponse resume result 11 T2 13 private String veryExpensiveOperation 14 very expensive operation 15 16 start ls 18 In the example above a resource AsyncResource with one GET method asyncGet is defined The asyncGet method injects a JAX RS AsyncResponse http jax rs spec java net nonav 2 0 114 Asynchronous Services and Clients apidocs javax ws rs container AsyncResponse html instance using a JAX RS Suspended http jax rs spec java net nonav 2 0 apidocs javax ws rs container Suspended html annotation Please note that AsyncResponse must be in
314. ws rs Path import javax ws rs Produces Path helloworld public class HelloWorldResource public static final String CLICHED_MESSAGE Hello World OANA O PWN FE Ko 10 11 GET 12 Produces text plain 13 public String getHello 14 return CLICHED MESSAGE 15 1 6 7 Let s look at some of the JAX RS annotations used in this example 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 hellowor1ld 23 JAX RS Application Resources and Sub Resources 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 name and then a Jersey web service configured to respond to requests to this URI path template will respond For example if the user ente
315. y java io File javax activation DataSource e javax ws rs core StreamingOutput outbound only e XML media types text xml application xml and application xml javax xml transform Source javax xml bind JAXBElement e Application supplied JAXB classes types 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 e Form content application x www form urlencoded MultivaluedMap lt String String gt e Plain text text plain java lang Boolean java lang Character java lang Number 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 In other words 56 Representations and Responses the representation entity parameter does not require a specific entity annotation A method parameter without a annotation is an entity 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 6 1 Using File with a specific media type to produce a
316. y 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 config at the last line of the MyResourceConfig constructor in the example 12 2 1 Deployment of programmatic resources Let s now look at how a programmatic resources 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
317. y client Jersey core client implementation https jersey java net project info 2 1 jersey jersey client dependencies html jersey common Jersey core common packages https jersey java net project info 2 1 jersey jersey common dependencies html Modules and dependencies jersey server https jersey java net project info 2 1 jersey jersey server dependencies html Jersey core server implementation Table 2 2 Jersey Containers Containers jersey container grizzly2 http https jersey java net project info 2 1 jersey project jersey container grizzly2 http dependencies html Grizzly 2 Http Container jersey container grizzly2 servlet https jersey java net project info 2 1 jersey project jersey container grizzly2 servlet dependencies html Grizzly 2 Servlet Container jersey container jdk http https jersey java net project info 2 1 jersey project jersey container jdk http dependencies html JDK Http Container jersey container servlet https jersey java net project info 2 1 jersey project jersey container servlet dependencies html Jersey core Servlet 3 x implementation jersey container servlet core https jersey java net project info 2 1 jersey project jersey container servlet core dependencies html Jersey core Servlet 2 x implementation jersey container simple
318. y org glassfish jersey client ClientProperties html class Table A 3 List of client configuration properties Constant Value Description jersey config contentL amp fA gtintegert falne that defines the buffer size used to buffer the outbound message entity in order to determine its size and set the value of HTTP Content Length header Default value is 8192 ClientProperties ASYNC THREADPOQGE SIZHfig client agysynchhonous Pthrekd i peol size http jersey java net nonav apidocs snapshot jersey org glassfish jersey client ClientProperties html AS YNC_T HREADPOOL SIZE Default value is not set NOT SUPPORTED ClientProperties BUFFER_RESPONS E d85NTHAYE ON diIXGBPTKON fitonRaticprespera chuffebmg xing http jersey java net nonav apidocs snapshot jersey org glassfish jersey client case of an exception Default value is true NOT SUPPORTED ClientProperties html BUFFER_RESPONSE_ENTITY_ON_EXCEPTION pption ClientProperties CHUNKED ENCQDEN y SIZRfig client cH hiekedn emadidlimgs size Default http jersey java net nonav apidocs snapshot jersey org value is not set NOT SUPPORTED 197 Configuration Properties Constant Value Description glassfish jersey client ClientProperties html CHUNKEID_ENCODING_SIZE ClientProperties CONNECT TIMBGEHey config client cgoRnaattTtimeoutc http jersey java net nonav apidocs snapshot jersey o
319. yWorkers http jersey java net nonav apidocs snapshot jersey org glassfish jersey message MessageBodyWorkers html interface and Jersey provides an implementation that can be injected using the 2 Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html injection annotation The interface declares methods for selection of most appropriate MessageBodyReader T and MessageBodyWriter lt T gt based on the rules defined in JAX RS spec methods for writing and reading entity that ensure proper and timely invocation of interceptors and other useful methods See the following example of usage of MessageBodyWorkers 72 JAX RS Entity Providers Example 7 12 Usage of MessageBody Workers interface 1 Path workers 2 public static class WorkersResource 3 4 Context 5 private MessageBodyWorkers workers 6 f GET 8 Produces application xml 9 public String getMyBeanAsString 10 11 final MyBean myBean new MyBean Hello World 42 T2 13 buffer into which myBean will be serialized 14 ByteArrayOutputStream baos new ByteArrayOutputStream T5 16 get most appropriate MBW 17 final MessageBodyWriter lt MyBean gt messageBodyWriter 18 workers getMessageBodyWriter MyBean class MyBean class 19 new Annotation MediaType APPLICATION XML TYPE 20 21 try 22 use the MBW to serialize myBean into baos 23 messageBodyWriter writeTo myBean
320. ync chapter first for more details After the eventOutput is returned from the method the Jersey runtime recognizes that this is a ChunkedOut put extension and does not close the client connection immediately Instead it writes the HTTP headers to the response stream and waits for more chunks SSE events to be sent At this point the client can read headers and starts listening for individual events Note Since Jersey runtime does not implicitly close the connection to the client similarly to asynchronous processing closing the connection is a responsibility of the resource method or the client listening on the open connection for new events see following example In the Example 13 1 Simple SSE resource method the resource method creates a new thread that sends a sequence of 10 events There is a 1 second delay between two subsequent events as indicated in a comment Each event is represented by OutboundEvent type and is built with a helpf of an outbound event Builder The OutboundEvent reflects the standardized format of SSE messages and contains properties that represent name for named events comment data or id The code also sets the event data media type using the nediaType MediaType method on the eventBuilder The media type together with the data type set by the data Class Object method in our case String class is used for serialization of the event data Note that the event data media type will not be written to any hea
321. 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 129 Programmatic API for Building Resources Example 12 3 A programmatic resource 1 2 pis 3 servlet 4 servlet name org glassfish jersey examples hellow 5 servlet class org glassfish jersey 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 init param 10 lt load on startup gt 1 lt load on startup gt TT servlet 12 servlet mapping 13 servlet name org glassfish jersey examples hellow 14 url pattern url pattern 15 servlet mapping 16 177 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
322. zzly in memory jdk simple able to run against any external container automated configurable traffic logging Jersey Test Framework is based on JUnit and works almost out of the box It is easy to integrate it within your Maven based project While it is usable on all environments where you can run JUnit we support primarily the Maven based setups 18 1 Basics 1 public class SimpleTest extends JerseyTest 2 3 Path hello 4 public static class HelloResource 2 GET 6 public String getHello 7 return Hello World 8 9 10 Tat Override 12 protected Application configure 13 return new ResourceConfig HelloResource class 14 1 5 16 Test 17 public void test 18 final String hello target hello request get String class 19 assertEquals Hello World hello 20 2l If you want to develop a test using Jersey Test Framework you need to subclass JerseyTest http jersey java net nonav apidocs snapshot jersey org glassfish jersey org glassfish jersey test Jersey Test html and configure the set of resources and or providers that will be deployed as part of the test application This short code snippet shows basic resource class Hel loResource used in tests defined as part of the SimpleTest class The overridden configure method returns a ResourceConfig http jersey java net nonav apidocs snapshot jersey org glassfish jersey server ResourceConfig html of the test applicati

Download Pdf Manuals

Related Search

Related Contents

NEC EA222WME  Als PDF herunterladen  Hama Turn  Nedis SEC-CAM735 surveillance camera  lsa 37.32 - 4 polos - acc  組立説明書  Manual de uso de teléfonos IP  azur 640T V2.0  manual  Keating Of Chicago 37399 User's Manual  

Copyright © All rights reserved. Failed to retrieve file