Home

Jersey 2.10 User Guide

Contents

1. 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 filter ContainerRequestContext requestContext T I 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 m
2. 156 Chapter 13 Programmatic API for Building Resources 13 1 13 2 Introduction A standard approach of developing JAX RS application is to implement resource classes annotated with Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html with resource methods annotated with HTTP method annotations like GET http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html or POST http jax rs spec java net nonav 2 0 apidocs javax ws rs POST html and implement needed functionality This approach is described in the chapter JAX RS Application Resources and Sub Resources 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 OPTIONS http jax rs spec java net nonav 2 0 apidocs javax ws rs OPTIONS html method which would return some kind of meta data about the deployed resource Ideally you would want to expose the functionality as an additional feature and you want to decide at the deploy time whether
3. ceee eee eee 126 8 50 Use of FormDataParam annotation sson Ea E E A EIE S nA 127 91 Container response fter aeea e eis eed dts eae eee eee O ARES 129 0 2 Contamer request filter seerne p eoe na R E tush a e EA E I SE EE 130 9 3 Pre matchine request filter nonin oein re T a ee EEE a A E aN eae 131 94A Chent reguest Miltersen asane a a e A Mew e a a N 132 9 5 GZIP Writer interceptor aera a E N e Wied ace A E E R eata bel 133 9 6 GZIP reader mterceptoi erii o e p AE EE EE E wom E Ea EEEE EIER 134 97 CNameBinding examples E n E E E E E TTO E RTS 137 9 8 Dynamic binding example sanieren eaea en E E ENE wend EE EEEE 139 9 9 sa B KOIGI IERA E10 O leE E E E AN 140 10 1 Simple async Tes OUECE etree oaro e EE NE E EN E E E EEEE EE 141 10 2 Simple async method with timeout sseessseessseresrerrsresrrrresrrererrerrsrrerrrreerrrrerreerereet 143 10 3 CompletionCallback example rense ernen E E cena eens E ae AERE eE 144 10 4 ChunkedO tp t example siei oieee E a EE ERE pE E OAST 146 10 5 Simple client async Invocation p sasse an n re aE E E A a EE EEPE 147 10 6 Simple client fluent async invocation seesseseessesrseeerrsresrrrrerrrersrrerrerrerrrresrrersrreerere 147 10 7 Che nt asyne Callback sser etniei E R RE EA E E N EASA 148 10 8 Client async callback for specific entity e sseesssseessesrsrrerrsresrerrsrrerrsrrerreresrereesreeesre 148 10 9 ChunkedInput example soen een eee ar EERE E EE
4. 0 00 cece ce cece ee cece cece ee ceneeeeeeeeneeeees 49 Ally Tntroductyomi mesier aud cade chbectyictebesig teenies EAEE E EEO PEENE ESEE EEES E 49 4 2 JAX RS Application Model ssie eiie e n ae e E E T GE EESE AR 49 4 3 Auto Discoverable Features se sseseeseeereerrsrreersrrerreresrrrrerrerrsrrerrsrrerrreesrreeerreees 50 4 3 1 Configuring Feature Auto discovery Mechanism cece ceeeeeeeeneeee teen eenes 50 4 4 Configuring the Classpath Scanning 0 cocci ce cece cece cece ence ne eeneeeeeceeeeeeeeeeeaees 51 4 5 Java SE Deployment Environment cece cece ce eece ence eeceeeceeeeaesea esau eeea ea 53 ADL HT EP SCDVeLs noe cbabed teiteegcres ERE E EEN desis eyes ves E S 53 4 6 Creating programmatic JAX RS endpoint eee eens cc eece ence eceeeeeeeeaeeeaeeenes 55 4 7 Servlet based Deployment 00 ce cece cece iun eeri ae EE EE EENE EE SEESE ESEE 55 4 1 1 Serviet 2X Contae iir a anpe i ea E pe Ta e E E aE potted 56 4 7 2 Servlet 3 x Contamer ieou e re E EE EE EESO EEE RIE 58 4 7 3 Jersey Servlet container modules cece neiti osre cece eece cena een eeneeeneeeenees 62 4 3 Java EE Platform 23 0 otsisiesscssin eed ts veg EE coed NEE ceeds tu cles KEE EEEIEE EE E 62 4 3 1 Managed Beans oime ei ei a span eetes Seaver rae E E R 62 4 8 2 Context and Dependency Injection CDI sssessseessesessrerrssrerrsrrrrrererreererreees 63 4 8 3 Enterprise Java B
5. 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 WN FE WebTarget webTarget client target http example com rest webTarget register FilterForExampleCom class 10 WebTarget resourceWebTarget webTarget path resource Ne 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 printin response getStatus 21 System out printin response readEntity String class Now we can try to leverage the fluent API style to write this code in a more compact way 75 GI Client API Example 5 3 Using JAX RS Client API fluently Client client ClientBuilder newClient new ClientConfig register MyClientResponseFilter class r
6. eseesseseeseeeeseueersrrsrrrrerrrrrsrrerrsrrerrereereee 207 17 13 Support for injecting Jersey s resources providers via ConstraintValidatorFactory 208 1714 Vals datron Error totext plai Ny yp nE vedawcsetie tweens EE AEE ESS rA 210 1715s Validaticnkrrortorbext htm shania uaan e TA 210 17 16 Val dati nibrror to application xml Js fess secretes eh osteo ude Sac cba e a as 210 17 7 Validat LonError toapplitation JSON vresa cet ieiee ieee lial estes EE RA 211 18 1 Registering and configuring entity filtering feature On Server ceeeeeeeeeeeeeeeeeceeeeeeeee eee 213 18 2 Registering and configuring entity filtering feature with security annotations on server 214 18 3 Registering and configuring entity filtering feature based on dynamic and configurable query PATAMELETS o oe rea a TE E E E sedans sh vee Dae ye cc daa paved E A EENE AN TEO EE EEE AR 214 18 4 Registering and configuring entity filtering feature on client eeeeeceerceereeerrrerreerreerreee 214 18 5 Project nsiro ai E SSA Te Pg Ge N TE E E A Ue Es E R S 215 18 6 USE nnen a e a e Smead dd sade e e a a e coe a a a e a E N 215 T8 7 Task omeen aetna os ea e e ae Ean h EENE E E a T AA Ee eo doers Palle eave TETO N 215 18 8 ProjeCtSRESOULCe ise 3s oe TH oe sen ceed den spose eaesesy ns tet op Suseea EEE sae ss devsddess Sandee SE techs evtns 216 18 9 ProjectDetaled View 82 53 55 22 tive nde a E E E soe ued anes ee vole Abs eee 21
7. 254 Custom Injection and Lifecycle Management Again the semantics remains the same as in the example described in the previous section You want to have the actual HTTP Servlet session instance injected into your MyDiResource instance This time however you expect that the htt pSession field to be injected must be annotated with a custom SessionInject annotation Obviously in this simplistic case the use of a custom injection annotation is an overkill however the simplicity of the use case will help us to avoid use case specific distractions and allow us better focus on the important aspects of the job of defining a custom injection annotation If you remember from the previous section to make the injection in the code snippet above work you first need to implement the injection provider HK2 Factory https hk2 java net apidocs org glassfish hk2 api Factory html as well as define the injection binding for the HttpSession type That part we have already done in the previous section We will now focus on what needs to be done to inform the HK2 runtime about our SessionInject annotation type that we want to support as a new injection point marker annotation To do that we need to implement our own HK2 InjectionResolver https hk2 java net apidocs org glassfish hk2 api InjectionResolver html for the annotation as demonstrated in the following listing import javax inject Inject import javax inject Named import java
8. Error he Configuration Properties Constant Value Description code e g servlet page configuration if you want process response servlet filter the way to do it is calling setStatus on container Response object If property value is true the method Response setStatus is used over default Response sendError Type of the property value is boolean The default value is false error However post by only to e g ServerProperties TRACING https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html TRACING jersey config server tuy Endbles diyabtes tracing support Possible values are OFF default ON_DEMAND and ALL See Section 20 2 1 Configuration options for more detail https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties TRACING_THRESH 4p config server ty ServerProperties html TRACING_THRESHOLD Setingthehramhduntd of detail provided by tracing Possible values are SUMMARY TRACE and VERBOSE See Section 20 2 1 Configuration options to learn more about the levels https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html PROCESS ServerProperties PROCESSING_RESPGNSE diRR OQRScENABLEIXe ptoperty prahe ass Reape tiea icrors the errors raised during response processing are tried
9. The jersey container servlet module depends on jersey container servlet cor module therefore when it is used it is not necessary to explicitly declare the jersey container servlet core dependency Note that in simple cases you don t need to provide the deployment descriptor web xm1 and can use the ApplicationPath annotation as described in Section 4 7 2 3 1 JAX RS application without an Application subclass section 4 8 Java EE Platform 4 8 1 This section describes how you can publish Jersey JAX RS resources as various Java EE platform elements JAX RS and Jersey give you wide choice of possibilities and it is up to your taste and design of your application what Java EE technology you decide to use for the management of your resources Managed Beans Jersey supports the use of Java EE Managed beans as root resource classes providers as well as Application subclasses In the code below you can find an example of a bean that uses a managed bean interceptor defined as a JAX RS bean The bean is used to intercept calls to the resource method get It 1 ManagedBean 2 Path managedbean 3 public class ManagedBeanResource 4 62 Application Deployment and Runtime Environments 5 public static class MyInterceptor 6 AroundInvoke 7 public String around InvocationContext ctx throws Exception 8 System out println around called 9 return String ctx proceed 10
10. Zz ry O mav Z ry O n clean plugin 2 4 1 clean default clean simple hero Z mj O mav Using skip no Z2 2 Z 2 Z Aog AY Ay CRS RRON Compili Z ry O n resources plugin 2 4 3 resources default resources UTF 8 encoding to copy filtered resources n existing resourceDirectory tmp build_992cc747 26d6 480 maven compiler plugin 2 5 1 compile default compile simp ng 2 source files to tmp build_992cc747 26d6 4800 bdb1 a Z nj O mav Using skip no Z Z a CS HHHHHHHHHHHHHHHHHH Z nj O n resources plugin 2 4 3 testResources default testReso UTF 8 encoding to copy filtered resources n existing resourceDirectory tmp build_992cc747 26d6 480 Getting Started Z2 2 Z Z2 Z Z 2 Z2 ZZ 2 Z2 Z222 Z2 ZZ 2 Z 2 Z OOOO OO0 000 0 0 0 0 O 010 0 O 0 0 O 0 000 0 0 0 HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH 2222222222222 222222 2252 2224224 RyRy Ry ep Rp RB RO OO OO OOO OO OQO OO OO OTO O O OOTI O O OOOO O OOO Oo Z ry O INFO E aM ave n compiler plugin 2 5 1 testCompile default testCompile Compiling 1 source file to tmp build_992cc747 26d6 4800 bdb1 ad m Tests av ar n surefire plugin 2 7 2 test default test simple her e skipped m av n war plugin 2 1 1l war default war simple heroku web Packaging webapp Assem Proce Copyi bli ssi ng
11. e Section 18 4 Role based Entity Filtering using javax annotation security annotations e Section 18 5 Entity Filtering based on dynamic and configurable query parameters as well as some more complex ones e Section 18 6 Defining custom handling for entity filtering annotations Note Jersey entity filtering feature is supported via Jersey extension modules listed in Section 18 8 Modules with support for Entity Data Filtering 18 1 Enabling and configuring Entity Filtering in your application Entity Filtering 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 lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey entity filtering lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt Note If you re not using Maven make sure to have also all the transitive dependencies see jersey entity filtering https jersey java net project info 2 10 jersey project jersey entity filtering dependencies html on the classpath 212 Entity Data Filtering The entity filtering extension module provides three Features which you can register into server client runtime in prior to use Entity Filtering in an application EntityFilteringFeature https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering EntityFilteringFeature
12. jersey java net project Jersey JAX RS asynchronous server side example 27 Modules and dependencies Jersey Examples info 2 10 jersey project server async dependencies html server async managed https jersey java net project info 2 10 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 10 jersey project server async standalone dependencies html Standalone Jersey JAX RS asynchronous server side processing example server async standalone client https jersey java net project info 2 10 jersey project server async standalone server async standalone client dependencies html Standalone Jersey JAX RS asynchronous server side processing example client server async standalone webapp https jersey java net project info 2 10 jersey project server async standalone server async standalone webapp dependencies html Standalone Jersey JAX RS asynchronous server side processing example web application server sent events https jersey java net project info 2 10 jersey project server sent events dependencies html Jersey Server Sent Events example servlet3 webapp https jersey java net project info 2 10 jersey project webapp example parent servlet3 webapp dependencies
13. org eclipse persistence jaxb JAXBCaofla x Properties JSON_INCLUDE_ROOT org eclipse persistence jaxb MarshafiteeProperties JSON_MARSHAL EMPTY_ OLLECTIONS org eclipse persistence jaxb JAXBContrgx Ptropset pes iJSONnNAMBSRAKMLSBAARANOBHDOT Example 8 10 Building client with MOXy JSON feature enabled final Client client ClientBuilder newBuilder The line below that registers MOXy feature can be omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled register MoxyJsonFeature class register jsonConfigResolver build Example 8 11 Creating 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 below that registers MOXy feature can be omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled register MoxyJsonFeature class register jsonConfigResolver 8 1 2 3 Examples Jersey provides an JSON MOXy example https github com jersey jersey tree 2 10 examples json moxy on how to use MOXy to consume produce JSON 107 Support for Common Media Type Representations 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 p
14. org glassfish jersey server wadL internal wadlResource MaxTime ms _1m gt org glassfish jersey server wadl processor OptionsMethodProcessor GenericOptionsinflector MaxTime ms 1s gt org glassfish jersey server wadl processor OptionsMethodProcessor PlainTextOptionsinflector MaxTime ms total gt org glassfish jersey server wadl processor WadlModelProcessor OptionsHandler MinTime ms _ 15m gt org glassfish jersey tests server monitoring MBeansTest SubResource MinTime ms 15s gt org glassfish jersey tests e2e server monitoring MBeansTest TestResource MinTime ms _1h Uris MinTime ms 1m gt application wadl MinTime ms 1s gt application wadl path MinTime ms total gt exception resource RequestCount_15m gt in subresource locator locator locator resource RequestCount_15s_ gt gt v Name N N N 0 0 6 6 6 6 N O 4 N 4 N B lOO OA in subresource locator locator resource RequestCount_1h 45 in subresource locator resource RequestCount_1m 38 resource RequestCount_1s 1 gt Attributes RequestCount_total 51 gt MethodTimes RequestRate requestsPerSeconds 15m __ 0 6172839506172839 gt RequestTimes RequestRate requestsPerSeconds 15s v methods RequestRate requestsPerSeconds 1h GET gt TestResource testGet 1F1 45bd4 RequestRate requestsPerSeconds 1m 3 gt Attributes
15. 3 public String street 4 public String town 5 6 public Address 7 8 public Address String street String town 9 this street street 10 this town town 11 12 4 Example 8 18 JA XB beans for JSON supported notations description contact bean 1 XmlRootElement 2 public class Contact 3 4 public int id 5 public String name 6 public List lt Address gt addresses 7 8 public Contact 9 10 public Contact int id String name List lt Address gt addresses 11 this name name 12 this id id 13 this addresses 14 addresses null new LinkedList lt Address gt addresses null 15 16 Following text will be mainly working with a contact bean initialized with Example 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 Ie contact bean with id 2 name Bob containing a single address st reet Long Street 1 town Short Village All below described configuration options are documented also in api docs at JettisonConfig https jersey java net apidocs 2 10 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
16. ClientProperties html JSON_PROCESSING_FEATURE_DISABI Sparse cecsomiimoy iert di LE https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html JSON_PRI ServerProperties JSON_PROCES SENG chKEA SURE DISABBEe J OCESSING_FEATURE_DISABLE spaibsencescat inion ssamear dil https jersey java net apidocs 2 10 jersey org glassfish jersey client https jersey java net apidocs 2 10 jersey org glassfish jersey server ClientProperties html METAINF ServerProperties METAINF_SER WEES yLOOKUR DISAB Meteriseh coor ClientProperties MET AINF_SER VICES y LQOQOKER DISABBFeMeterisehis ccorlt SERVICES_LOOKUP_DISAB ServerProperties html METAINF_SERVICES_LOOKUP_DISABLE LE https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties MOXY_JSON_FRAYRERE cbISABLE i sableM ClientProperties html MOXY_J ON_FEATURE_DISABLE bemes cdnn client di ServerProperties MOXY_JSON https jersey java net apidocs 2 10 jersey org glassfish jersey server Flak EERECDISABLHi sableM ServerProperties html 4MOXY_JSON_FEATURE_DISABLE Dpeycksayn coariviey server di https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html OUTBOUND_CONTENT_LENGTH_BUF FER 274 sableAutoDis sableAutoDis sableJsonPro sableJsonPro fries Imlokent cl
17. ProjectDetailedView 12 PZE 18 4 Role based Entity Filtering using javax annotation security annotations Filtering the content sent to the client or server based on the authorized security roles is a commonly required use case By registering SecurityEntityFilteringFeature https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering SecurityEntityFilteringFeature html you can leverage the Jersey Entity Filtering facility in connection with standard javax annotation security annotations exactly the same way as you would with custom entity filtering annotations described in previous chapters Supported security annotations are 221 Entity Data Filtering e PermitAll http docs oracle com javaee 6 api javax annotation security PermitAl1 html e RolesAllowed and e DenyAll http docs oracle com javaee 6 api javax annotation security Deny All html Although the mechanics of the Entity Data Filtering feature used for the security annotation based filtering is the same as with the entity filtering annotations the processing of security annotations differs in a few important aspects e Custom SecurityContext http jax rs spec java net nonav 2 0 apidocs javax ws rs core SecurityContext html should be set by a container request filter in order to use RolesAl lowed for role based filtering of domain model data server side e There is no need to provide entity filtering or security a
18. RE_AUTO_DISCOVERY_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html JSON_FRROCESSING_FEATURE_DISAI CommonProperties JSON_PROCESSiNGy FEATURE DISABILE s Disablese senfiguration of Json Processing JSR 353 feature Default value is false BLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties METAINF_SERMI amp S LOOK GP di BB ENa Disables e rv MEEAdMNFigervices lookup globally on client server Default value is false CommonProperties html METAINF_SERVICES_LOOKUP_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html MOXY CommonProperties OUTBOUND JSON_FEATURE_DISABLE EON FENG oLENG Td BIERFER Agtintdgerf falne that defines the CommonProperties html OUTBQUND_CONTENT_LENGTH_BU CommonProperties MOXY_JSONJEEAPWRinWASABLEs abl eMabysables configuration of MOXy Json feature Default value is false buffer size used to buffer the outbound message entity in order to determine its size and set HWERhlue 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 https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html class
19. cceseceeeceneeceeececeesceaeeeeeuscecseceeueeeeaeeeeueeeeeees 288 A 3 Client configuration properties 1 2 0 0 cece cece eee e cena cena cen ERa TETEA Ea ESR 293 Vil List of Tables 2 1 Jersey Core oies tsa ratoetetcetts satboroasaeinte via E a T dita see pat EE E E 15 2 2 JErsey COMLAMELS nirea Tee o EEE EE EEEE E O EE EE E See a 15 2 3 Jersey CONNECIOLS sorsia rees E PAS SE ENSE EEPO EE NEUE ESE EAA PES Ep REO PEES 16 ZA Jersey M dia iiei ea e n EEEE EE a sth ety Bales cobs EES E Haka cone E EE IERS 17 2 5 Jersey EXteNSIONS vepsa aiee r a E EE E EE E E EE 18 2 6 Jersey Test Fram Work csee tees o pS E T a E abe EEEE usin EE E E REG 19 2 1 Jersey Test Framework Providers 3 sss ect0assesuccassuecesdaeedeougasncteugs ie sabegeevetes ERA Tisai T RPGS 19 2 8 Jersey Glassfish Bundles 2 3ccoecccscnetccs vetecdeas nene Ua dees ee a OEE EEE EET iesi 21 2 9 SOCUEILY ni rae aora E E E a E E S a EE T las Dos ea E E a EE S 21 2 10 Jersey Examples dsrs n reo E E ee EE EA oe EEEE EE E e 22 3 ly RESource SCOPES eraren eaan aier E E EEEE IELO Sper I EES Oa E EE EERO NS EESTE RISERS 43 3 2 Overview Of INjeCtiON types siie e e Eear EE E EE EAAS EEE EES KESE TE e SSS 45 4 1 Servlet 3 Pluggability Overview 2 c ccss sos ie inep a a a a E T a E 6l 8 1 Default property values for MOXy MessageBodyReader lt T gt MessageBodyWriter lt T gt 107 25 1 List of changed configuration properties essssessssssrrsr
20. jersey java net project info 2 10 jersey Jersey JSON with Jettison JAXB example 25 Modules and dependencies Jersey Examples project json jettison dependencies html json moxy https jersey java net project info 2 10 jersey project json moxy dependencies html Jersey JSON with MOXy example json processing webapp https jersey java net project info 2 10 jersey project webapp example parent json processing webapp dependencies html Jersey JSON P JSR 353 example json with padding https jersey java net project info 2 10 jersey project json with padding dependencies html Jersey JSON with Padding example managed beans webapp https jersey java net project info 2 10 jersey project webapp example parent managed beans webapp dependencies html Jersey Managed Beans Web Application Example managed client https jersey java net project info 2 10 jersey project managed client dependencies html Jersey managed client example managed client simple webapp https jersey java net project info 2 10 jersey project webapp example parent managed client simple webapp dependencies html Jersey Web Application Servlet examples parent POM managed client webapp https jersey java net project info 2 10 jersey project webapp example parent managed Jersey managed client web application examp
21. resource and method See the javadocs of the resource builder API for more information 13 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 161 1 Programmatic API for 2 Bupldintg Resvarcews rs GET 3 import javax ws rs Path Example 13 6 A programmatic resourvex ws rs Produces 5 import javax ws rs container ContainerRequestContext 6 import javax ws rs core Application 7 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 ModelPr
22. 9 lt response gt 10 lt representation mediaType application xml gt 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 lt representation mediaType application vnd sun wadl xml gt 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 structure 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 192 WADL Support Example 16 4 More complex WADL example JAX RS re
23. 94 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 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 lt T gt will be also considered It is a responsibility of the isReadable method to d
24. d efault Class lt 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 17 7 Validator implementation Example 17 7 Validator implementation public class EmailValidator implements ConstraintValidator lt Email String gt public void initialize Email email public boolean isValid String value ConstraintValidatorContext context Thus EmailValidator applies to values annotated with Email that are of type St ring Validators for other Java types can be defined for the same constraint annotation 17 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 17 8 Entity validation 204 Bean Validation Support Example 17 8 Entity validation StandardUser class User NotNull private String firstName Path class MyResourceClass POST Co
25. freemarker webapp dependencies html groovy https jersey java net project info 2 10 jersey project groovy dependencies html Groovy Jersey helloworld https jersey java net project info 2 10 jersey project helloworld dependencies html Jersey annotated resource class Hello world example helloworld programmatic https jersey java net project info 2 10 jersey project helloworld programmatic dependencies html Jersey programmatic resource API Hello world example helloworld pure jax rs https jersey java net project info 2 10 jersey project helloworld pure jax rs dependencies html Example using only the standard JAX RS API s and the lightweight HTTP server bundled in JDK helloworld spring annotations https jersey java net project info 2 10 jersey project helloworld spring annotations dependencies html Spring 3 Integration Jersey Example helloworld spring webapp https jersey java net project info 2 10 jersey project helloworld spring webapp dependencies html Spring 3 Integration Jersey Example helloworld webapp https jersey java net project info 2 10 jersey project webapp example parent helloworld webapp dependencies html Jersey annotated resource class Hello world example 24 Modules and dependencies Jersey Examples http patch https jersey java net project info 2 1
26. 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 JAX 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 139 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 as well as entity interceptors R
27. true FormDataParam enabled boolean enabled FormDataParam data FileData bean FormDataParam file InputStream file FormDataParam file FormDataContentDisposition fileDisposition GI In the example above the server consumes amultipart form data request entity body that contains one optional named body part 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 127 Support for Common Media Type Representations 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 Tip FormDataParam annotation can be also used on fields 128 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 a
28. 1 112 Support for Common Media Type Representations 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 below Example 8 21 JSON expression with XML namespaces mapped into JSON 1 2 Contact tof 3 example id 2 4 name Bob 5 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 Another configurable option introduced in Jersey version 2 2 is related to serialization of JSON arrays with Jettison s mapped notation When serializing elements representing single item lists arrays you might want to utilise the following Jersey configuration method to explicitly name which elements to treat as arrays no matter what the actual content is Example 8 22 JSON Array configuration for Jettison based mapped notation 1 cont
29. 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 in Section 1 1 Creating a New Project from Maven Archetype In addition to the Grizzly based archetype Jersey provides also a Maven archetype 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 DarchetypeGrouplId org glassfish jersey archetypes DinteractiveMo DgroupiId com exampl DartifactId simple service webapp Dpackage DarchetypeVersion 2 10 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 xm1 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
30. Content Type text plain hello Boundary_1_829077776_1369128119878 Content Type application xml lt xml 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 124 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart FormDataMultiPart html It automatically sets the media type for the FormDataMultiPart entity to multipart form data and Content Disposition header to FormDat aBodyPart body parts Example 8 46 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 47 FormDataMultiPart entity in HTTP message Content Type multipart form data bou
31. If no such Servlet is defined to handle the custom Application subclass Jersey dynamically adds a Servlet with a fully qualified name equal to the name of the provided Application subclass To define the mapping for the added Servlet you can either annotate the custom Application subclass with an ApplicationPath http jax rs spec java net nonav 2 0 apidocs javax ws rs ApplicationPath html annotation Jersey will use the annotation value appended with to 60 Application Deployment and Runtime Environments automatically define the mapping for the Servlet or specify the mapping for the Servlet in the web xm1 descriptor directly In the following example let s assume that the JAX RS application is defined using a custom Application subclass named org example MyApplication Then the web xml file could have the following structure Example 4 18 1 lt web app version 3 0 2 xmlns http java sun com xml ns javaee 3 xmlns xsi http www w3 org 2001 XMLSchema instance gt 4 5 lt Servlet declaration can be omitted in which case 6 it would be automatically added by Jersey gt 7 lt servlet gt 8 lt servlet name gt org example MyApplication lt servlet name gt 9 lt servlet gt 10 11 lt Servlet mapping can be omitted in case the Application subclass 12 is annotated with ApplicationPath annotation in such case 13 the mapping would be automatically added by Jersey gt 14 lt se
32. 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 WriterInterceptorContext 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
33. String s T5 injection into a sub resource locator parameter 16 return SubResource class 17 18 19 public SummaryOfInjectionsResource QueryParam 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 FormParam html annotation is special and may only be utilized on resource and sub resource methods This is because it extracts information from a request entity 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 co
34. The approach that will be demonstrated could be further generalized Bellow i will show how to make actual Servlet HttpSession http docs oracle com javaee 6 api javax servlet http HttpSession html injectable into JAX RS components and how to make this injection work with a custom inject annotation type Finally i will demonstrate how you can write HttpSession scoped JAX RS resources Implementing Custom Injection Provider Jersey implementation allows you to directly inject HttpServletRequest http docs oracle com javaee 6 api javax servlet http HttpServletRequest html instance into your JAX RS components It is quite straight forward to get the appropriate Ht tpSession instance out of the injected request instance Let say you want to get HttpSession instance directly injected into your JAX RS types like in the code snippet below Path di resource public class MyDiResource Inject HttpSession httpSession 252 Custom Injection and Lifecycle Management To make the above injection work you will need to define an additional HK2 binding in your application ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html Let s start with a custom HK2 Factory https hk2 java net apidocs org glassfish hk2 api Factory html implementation that knows how to extract HttpSession out of given HttpServletRequest import org glassfish hk2 api Factory public class HttpSess
35. The console output is 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 MyBean class System out println myBean OTA OABWN EF 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 J
36. 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 69 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 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 bas
37. 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 httpHeaders parameter that contains HTTP headers associated with the outbound message 92 JAX RS Entity Providers Note When a MessageBodyWriter 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 t
38. client resource restURL ClientResponse response webResource post ClientResponse class payload JAX RS 2 0 way Client client ClientBuilder newClient WebTarget target client target restURL Response response target request post Entity text payload 25 11 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 287 Appendix A Configuration Properties A 1 Common client server configuration properties List of common configuration properties that can be found in CommonProperties https jersey java net apidocs 2 10 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 https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html FEATU Value Description CommonProperties FEATURE_A U FOs BYSCOWERY DISABIM u Dosabkes ofeatmye auto discovery globally on client server Default value is false
39. 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 project 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 successful 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 l 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 SUCCE
40. eee eee cece eee eens ce eeceeece seen seca eens eeaes 43 3 23 INJSCtOM ss o arer dares be sr needs Sods Whe aban a REE A asa niilebstanag Seammesees EE sae deed ses Sad ERTES E 44 3 24 Wrong injection into a singleton SCOPE ee eee cece eee e cece ee cece ne ceneeeneeeeeeeeeeeeeeaeeeaeseaes 45 3 25 Injection of proxies into singleton ee eee cece eee ce ee a E a Tea Ipa E E 45 3 26 Example of possible injections cece eee cee cc ee ce eeceeeeaeeea seca eeeeeeae een eeneeeneeeeneeenes 47 4 1 Deployment agnostic application model eee eeccee cence eee ceeeca seca eens eens eeu eeneeeeeeeeees 49 4 2 Reusing Jersey implementation in your custom application model cece eee cence eeeees 50 4 3 Registering SPI implementations using ResourceConfig cece ee ceee cee ceee ce eece teen eeneeenes 52 4 4 Registering SPI implementations using ResourceConfig subclass ce eee eect ee eee eee 53 4 5 Using Jersey with JDK HPFTP Server socer rosins sieo resoa osr EEPOSE EES Eos Es ESTETEK STREE IPES 53 4 6 Using Jersey with Grizzly HTTP Server 00 0 eee cece cece cece ne cen een eeeeeeaeceeeeaeseaeeaaes 54 4 7 Using Jersey with the Simple framework sseesssseesrsrresrerrsrrerrsrerrreresrrrrerrerrsreeereresrere 54 4 8 Using Jersey with Jetty HTTP Server 0 cee cece cree cece ce eene eens eeneeeeeeeeeeeeeeeeaees 55 4 9 Hooking up Jersey asa Servlet lt sc irris seviesg
41. identifying a specific user resource The URI is built from the absolute path of the request URI by 151 URIs and Links calling Urilnfo getAbsolutePathBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html getA bsolutePathBuilder Q A new path segment is added which is the user ID and then the URI is built Notice that it is not necessary to worry about the inclusion of characters or that the user ID may contain characters that need to be percent encoded UriBuilder takes care of such 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 Urilnfo relativize ava net URI http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html relativizegjava net URD e UriBuilder resolveTemplate http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html resolveTemplate java lang String java
42. import import import com javax javax javax javax xample WS WS WS WS Root resourc F rs GET rs Path rs Produces rs core MediaType 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 TLT 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 aMyResourceTest 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 certai
43. in our model Project User and Task getters setter are omitted for brevity 214 Entity Data Filtering Example 18 5 Project 1 public class Project 2 3 private Long id 4 5 private String name 6 y private String description 8 9 private List lt Task gt tasks 10 deal private List lt User gt users 12 13 getters and setters 14 Example 18 6 User 1 public class User 2 3 private Long id 4 9 private String name 6 7 private String email 8 9 private List lt Project gt projects 10 11 private List lt Task gt tasks 12 13 getters and setters 14 Example 18 7 Task 1 public class Task 2 3 private Long id 4 5 private String name 6 7 private String description 8 9 private Project project 10 11 private User user 12 13 getters and setters 14 To retrieve the entities from server to client we have created also a couple of JAX RS resources from whose the Project sResource is shown as example 215 Entity Data Filtering Example 18 8 ProjectsResource 1 Path projects 2 Produces application json 3 public class ProjectsResource final Long id 4 5 GET 6 Path id i public Project getProject PathParam id 8 return getDetailedProject id 9 10 11 GET 12 public List lt Project gt getProjects 13 return getDetailedProjects 14 L5 18 3 Using custom annotations
44. link template is used to as page sent to the user Otherwise if an exception is raised then the error form template is shown to the user Example 19 5 Using ErrorTemplate on a resource method POST Produces text htm1 Consumes MediaType APPLICATION_FORM_URLENCODED Template name short link ErrorTemplate name error form public ShortenedLink createLink FormParam link final String link Note that ErrorTemplate https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc ErrorTemplate html can be used on a resource class or a resource method to merely handle error states There is no need to use Template https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Template html or Viewable https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Viewable html with it The annotation is handled by custom ExceptionMapper lt E extends Throwable gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ExceptionMapper html which creates an instance of Viewable that is further processed by Jersey This exception mapper is registered automatically with aMvcFeature 19 4 1 MVC amp Bean Validation ErrorTemplate can be used in also with Bean Validation to display specific error pages in case the validation of input output values fails for some reason Everything works as described above except the model
45. 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 can 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 46 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 T3 Path sub resource locator 14 public Class lt SubResource gt subResourceLocator QueryParam query
46. ng webapp simple heroku webapp in tmp build_992cc747 ng war project webapp resources tmp build_992cc747 26d6 4800 bdbl add Webapp assembled in 88 msecs Building war tmp build_992cc747 26d6 4800 bdb1 add47b9583cd ta WEB INF web xml already added skipping mav Copyi Copyi Copyi n dependency plugin 2 1 copy dependencies copy dependen guava 14 0 1l jar to tmp build_992cc747 26d6 4800 bdb1l a jJavax annotation api 1 2 jar to tmp build_992cc747 26d6 validation api 1 1 0 Final jar to tmp build_992cc747 26 Copyi Copyi Copyi Copyi Copyi Copyi Copyi Copyi Copyi Copyi Copyi javax ws rs api 2 0 jar to tmp build_992cc747 26d6 4800 etty http 9 0 6 v20130930 jar to tmp build_992cc747 26 ty io 9 0 6 v20130930 jar to tmp build_992cc747 26d6 ty security 9 0 6 v20130930 jar to tmp build_992cc74 ty server 9 0 6 v20130930 jar to tmp build_992cc747 ty servlet 9 0 6 v20130930 jar to tmp build_992cc747 ty util 9 0 6 v20130930 jar to tmp build_992cc747 26 etty webapp 9 0 6 v20130930 jar to tmp build_992cc747 etty xml 9 0 6 v20130930 jar to tmp build_992cc747 26d javax servlet 3 0 0 v201112011016 jar to tmp build_992c hk2 api 2 2 0 b21 jar to tmp build_992cc747 26d6 4800 b e PERSEE AREARE ERO PE e ihe E NE E P E PSE O POE Lassa Ca f Copyi Copyi hk2 locator 2 2 0 b21 jar to tmp build_992cc747 26d6 48 hk2 utils 2 2 0 b21 jar to tmp build_9
47. on how to use multipart features Client MultiPart https jersey java net apidocs 2 10 jersey org glassfish jersey media 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 Multipart_messages and is able to hold an arbitrary number of BodyPart https jersey java net apidocs 2 10 jersey org glassfish jersey media 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 44 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 45 MultiPart entity in HTTP message Content Type multipart mixed boundary Boundary_1_829077776_1369128119878 Boundary_1_829077776_1369128119878
48. or ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html Once done you are ready to add SSE support to your resource Example 14 2 Simple SSE resource method 1 ae 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 11 Produces SseFeature SERVER_SENT_EVENTS 12 public EventOutput getServerSentEvents 13 final EventOutput 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 Da new OutboundEvent Builder 22 eventBuilder name message to client 23 eventBuilder data String class 24 Hello world i 25 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 eventOutpu
49. ready it is sent back to the client on the same initial connection Client processes the messages sent 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 HTTP protocol and can be used for example for for online gaming or any 164 Server Sent Events SSE Support other applications that require fast exchange of small chunks of data in flowing in both direct
50. 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 10 Example 3 1 Simple hello world root resource class package org glassfish jersey examples helloworld import javax ws rs GET import javax ws rs Path import javax ws rs Produces Path helloworld public class HelloWorldResource public static final String CLICHED_MESSAGE Hello World OANA O 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 31 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
51. 10 jersey org glassfish jersey server spi ComponentProvider html SPI that would manage your custom components Although it might seem quite complex to implement such a thing the component provider concept in Jersey is in fact very simple It allows you to define your own HK2 injection bindings for the types that you are interested in while informing the Jersey runtime at the same time that it should back out and leave the component management to your provider in such a case By default if there is no custom component provider found for any given component type Jersey runtime assumes the role of the default component provider and automatically defines the default HK2 binding for the component type Following example shows a simple ComponentProvider implementation for our use case Some comments on the code follow port javax inject Inject port javax inject Provider port javax servlet http HttpServletRequest port javax servlet http HttpSession H H H H 3 5353 3 port org glassfi port org glassfi port org glassfi m k2 api DynamicConfiguration m m mport org glassfi m m m k2 api DynamicConfigurationService k2 api Factory k2 api PerLookup k2 api ServiceLocator k2 utilities binding BindingBuilderFactory jersey server spi ComponentProvider port org glassfi port org glassfi port org glassfis ES B OEA ER YD YD S S S S S S E H H He He He H oe javax
52. 288 Configuration Properties Table A 2 List of server configuration properties Constant Value Description ServerProperties APPLICATION NAMEy config server apDbfinestthoapplimation name The https jersey java net name is an arbitrary user defined apidocs 2 10 jersey org name which is used to distinguish glassfish jersey server between Jersey applications in the ServerProperties html APPLICATION_ NAME case that more applications are deployed on the same runtime container The name can be used for example for purposes of monitoring by JMX when name identifies to which application deployed MBeans belong to The name should be unique in the runtime The property does not have a default value ServerProperties B V_FEATURE D amp SABhEconfig beanValidbtsables Bean Whkdateonvesipport https jersey java net Default value is false apidocs 2 10 jersey org glassfish jersey server ServerProperties html B V_FEATIURE_DISABLE 3LE_VALIDATE_ON_EXECSBEFYeBPribpOWERRIDE_CHECK jersey config beanValidbtsables disable validateQnExecutablet https jersey java net ValidateOnExecution apidocs 2 10 jersey org check Default value is false glassfish jersey server ServerProperties html B V_DISABLE_VALIDATE_ON_EXECUTABLE OVERRIDE CHECK ServerProperties B V_SEND_ERRO amp r 8 yRESP NSEbeanValidEndbles senchigl e hidqtionVertardat ionErrorEr https jersey java net information to the client Default apidocs 2 10 jer
53. 4 3 Test Client configuration ms ee e a E EE AE E T EE IE S 266 23 4 4 Accessing the logged test records programmatically eeeessereeeeerrrrrrrrreeen 267 23 5 Parallel Testing with Jersey Test Framework ssesessessrerresrerrsrerrrrrsrrererrrersree 267 24 Binding and Testing Jersey neiitran e o R io Ee EA E a E 269 24 1 Checking Out th Sources secs pb eneee r a n Ee E EEE T E 269 24 2 B ilding the Source a iy ane E E E A E E E EEE A 269 PAS Tesina r aen E E R E N O T see EEE T E E E E SN 269 PAA USING NetBeans unen a E E A R EEOAE 270 25 Migration Guide i e aa E EA E EEEN T eesti 271 25 1 Migrating from Jersey 2 9 to 2 10 rerna eeann E a NE 271 25 1 1 Removed deprecated APIS cece cece cece eee S E EEE SRT 271 25 2 Migrating from Jersey 2 8 to 2 9 o ssectsects ee a Ee eaa bene eden thee eb eadeo eget E eT 271 252 Release 2 9 Highlights sires peesbb bes svec sven dads EE EE E E ES 271 25 2 2 CHANGES apee na yy suseod de vad ss E edn Sengreds utes N A saad EREE lees 272 25 3 Migrating from Jersey 2 7 tO 2 8 rrene a E E E E E sean eeaes 272 25 31 Chan BES eian e rn Peed sage A Sa yead ads dw tive Sees sede wund seer ead hess det heent eee 272 25 4 Migrating from Jersey 2 6 to 2 7 eect e cecc ence erae E EE EEEE E EEE EEE 275 D5 AN CHAN BES serne r ea e a e aE a OTE ESS 275 25 5 Migrating from Jersey 2 5 1 tO 2 Or eea E E E EE U E SER OS 276 25 5 1 Guava and ASM have been embedd
54. 5 Client code testing MyBeanMessageBody Writer 2 2 0 0 0 eee eee cee ce eeceeece teen teen eeeaeeaeeeueeee 93 7 6 Result of MyBeanMessageBodyWriter test cece cece eee ceece teen seca cece eeaeeeaeeeueceneeeenees 94 7 7 MessageBodyReader example n irnn n a E T T E S IE E E sean ERS 94 7 8 Testing MyBeanMessageBodyReader sseesnseesrsseesrrrrrsrerrsrrerrrrerrrreerrrrrsrrerrsrerrseeeeree 95 7 9 Result of testing MyBeanMessageBodyReader esesesseeerrsresrreresrerrsrrerrsrrrrreesrerrereee 96 7 10 MessageBodyReader registered on a JAX RS client 20 0 0 ceee eee ce eeca cece seen een eees 96 LAL Result of chent code execution irene n e su eels eee E edie ey ace pee eee 96 7 12 Usage of MessageBody Workers interface cece cece cece cece eee ce cece cece cena een eeneeeneeeeeeeeees 100 8 1 Simple JAXB bean implementation 0 2 0 0 cece ec cece cece cece ne cene een eeeeeeeeeeeeeeeaeeeaees 103 8 2 JAXB bean used to generate JSON representation eee eee cee cee ceeeceeeceeeeaeeeu seen eeaes 103 8 3 Tweaking JSON format using JAXB 0000 eee eee ceee cee eea ceca eeca sean cena cea eeneeeenees 104 8 4 JA XB Bean creation nesi niren ae a ies haan tee daweneeh E ten shea dee E agenesaenes 104 8 5 Constructing a JsonObject JSON Processing 2 2 0 0 cee ceeeceee cee ceeece teen eeea seen eens eeneeas 104 8 6 Constructing a JTSONOb ject Jettison eiee aare ns Er N ENES NERE ELERAN 105 8 7
55. 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 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 fur
56. 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 https jersey java net apidocs 2 10 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 Jetty HTTP client and Grizzly Asynchronous Client 5 1 Uniform Interface Constraint The uniform interface constraint bounds the architecture of RESTful Web services so that a client such as a browser can utilize the same interface to communicate with any service
57. Containers jersey container Grizzly 2 Http Container grizzly2 http https jersey java net project info 2 10 jersey project jersey container grizzly2 http dependencies html jersey container Grizzly 2 Servlet Container grizzly2 servlet https jersey java net project info 2 10 jersey project jersey container grizzly2 servlet dependencies html jersey container JDK Http Container jdk http https jersey java net project info 2 10 jersey project jersey container jdk http dependencies html jersey container Jetty Http Container jetty http https 15 Modules and dependencies Jersey Containers jersey java net project info 2 10 jersey project jersey container jetty http dependencies htm jersey container jetty servlet https jersey java net project info 2 10 jersey project jersey container jetty servlet dependencies html Jetty Servlet Container jersey container servlet https jersey java net project info 2 10 jersey project jersey container servlet dependencies html Jersey core Servlet 3 x implementation jersey container servlet core https jersey java net project info 2 10 jersey project jersey container servlet core dependencies html Jersey core Servlet 2 x implementation jersey container simple http https jersey java net project info 2 10 jersey project jersey container simple http depen
58. Headers er e a R E a eee Ma E ee aes 156 12 7 Configure and Tesisten ssie toee a a a EE EE AERE 156 13 Programmatic API for Building Resources e sseeesssessserrssrerrsrrerreresrrresrreresrrerreresereees 157 13 1 Introduction sener een e EA E aE EA EERS E aS 157 13 2 Programmatic Hello World example sssessseesseseesseresrrerrsrrsrrrresrrrrerrerrsrrerreresre 157 13 2 1 Deployment of programmatic resources se sseeseeseeseresrrerreresrrrrerreresreet 159 13 3 Additional examples ner 50382 Meee Mae a E E eas ee te EE A S E ANa 160 13 4 Model Processors ir sr ate e a O EN ston ENE AEE EEE ESEE EE ENE 161 14 Server Sent Events SSE SUpport sasra ae a rE E R E E SE 164 14 1 What are Server Sent Events oenen ne no n a E a S E E AE Ees 164 14 2 When to use Server Sent EyentS nescire e iea E EEE E R ESEE 165 14 3 Jersey Server Sent Events API ireset eade ee ea eE E T ES 165 14 4 Implementing SSE support in a JAX RS resource seeesseeeirererrerrerreererrerrerreree 166 14 4 1 Simple SSE resource method srren n a E ER a 166 14 4 2 Broadcasting with Jersey SSE sssssessessssrssrerrrrerrrerssrrrrsrrerrereerreeerrreeseeee 169 14 5 Consuming SSE events with Jersey clients 1 0 0 0 cece eee eeeceeece teen eeea een eeneees 171 14 5 1 Reading SSE events with Event Input 20 cee ceee eee ce eeea tena eeeeeene eens 171 14 5 2 Asynchronous SSE processing with Event SOULCE 0 eects ceeeceteee ener eens 1
59. Jersey 2 2 or later ClientProperties OUTBOUND_CONTENT FEENGIG_BIUEFER ca Ainemtegen yale taf fdefines the buffer size used to buffer the outbound message entity in order to determine its size and set ClientProperties html OUTBOUND_CONTENT_LENGTH_BUFFEHRg value of HTTP Content Length header Default value is 8192 ClientProperties PROX Y_URI https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html PROX Y_U RI jersey config client pyURl uof a HTTP proxy the client connector should use Default value is not set Currently supported with ApacheConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish 294 Configuration Properties Constant Value Description jersey apache connector ApacheConnectorProvider html and JettyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey jetty connector JettyConnectorProvider html only ClientProperties PROX Y_USERNAaMBey config client pu https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html PROX Y_U Jersey 2 5 or later SERNAME Oxer usamameme which will be used for HTTP proxy authentication Default value is not set Currently supported with ApacheConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey apache connector ApacheConnectorProvider html
60. Jersey Web Application Servlet examples parent POM xml moxy https jersey java net project info 2 10 jersey Jersey XML MOXy example 29 Modules and dependencies Jersey Examples project xml moxy dependencies html 30 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 index 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 0 apidocs javax ws rs POST html DELETE http jax rs spec java net nonav 2 0 apidocs javax ws rs DELETE html Resource methods are methods of a resource class annotated with a resource method designator This section shows how to use Jersey to annotate Java objects
61. Management including authentication filter e org glassfish jersey security oauthl signature provides support for OAuth request signatures This module is a dependency of previous two modules and as such it will be implicitly included in your maven project The module can be used as a standalone module but this will not be needed in most of the use cases You would do that if you wanted to implement your own OAuth support and would not want to deal with implementing the complex signature algorithms 15 3 1 1 Server To add support for OAuth into your server side application add the following dependency to your pom xml lt dependency gt lt grouplid gt org glassfish jersey security lt grouplId gt lt artifactId gt oauthl server lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt Again there is no need to add a direct dependency to the signature module it will be transitively included Let s now briefly go over the most important server Jersey OAuth APIs and SPIs e OAuthIServerFeature https jersey java net apidocs 2 10 jersey org glassfish jersey server oauth 1 OAuth 1ServerFeature html The feature which enables the OAuth 1 support on the server and registers OAuth1Provider explained in the following point e OAuth1Provider https jersey java net apidocs 2 10 jersey org glassfish jersey server oauth 1 OAuth 1Provider html Implementation of this SPI must be registered to the
62. MoxyJsonConfig Setting properties esssesessssesrserssrrrrsrrerrsrrerrrrerrrrrerreresrrerrsresrreeen 106 8 8 Creating ContextResolver lt MoxyJsonConfig gt oe ececeeeeeceeceee eee eeeeeeeeeeeaeeneeaeeees 106 8 9 Setting properties for MOXy providers into Configurable 0 eee eee cence eee eeeeeee ee 107 8 10 Building client with MOXy JSON feature enabled 2 0 0 0 cece cece cnee ee eeee een eene eens 107 8 11 Creating JAX RS application with MOXy JSON feature enabled eee 107 8 12 Building client with JSON Processing JSON feature enabled ceeeeeeeeeeceeneeeee teens 109 8 13 Creating JAX RS application with JSON Processing JSON feature enabled 00 109 8 14 ContextREsSOlLVeEr lt Ob JECCMAPPEL gt urepe E E EEA R EE NERE 110 8 15 Building client with Jackson JSON feature enabled 2 0 0 0 eee cee cence eeceeeeeeeea teen es 110 8 16 Creating JAX RS application with Jackson JSON feature enabled 0c ee eee eee 110 8 17 JAXB beans for JSON supported notations description simple address bean 0 112 8 18 JAXB beans for JSON supported notations description contact bean ceeeeeeeceeeeeee ee 112 8 19 JAXB beans for JSON supported notations description initialization eeeeeeee nsec eee ee 112 8 20 XML namespace to JSON mapping configuration for Jettison based mapped notation 113 8 21 JSON expression with X
63. Resource class JAXBElement cece ea E E E E EANES 120 Jersey 2 10 User Guide 8 36 Chent side JAXBElement san ear eos e specs Shek von aseps EI es aeseep S 121 8 37 PlanetJA XB ContextProvider a so nin erasan e vane deb lovee EE a AO E EE EE T 121 8 38 Using Provider with JAX RS client 2 0 0 eienenn n E e sean eeaeeeneeeneeennees 122 8 39 Add jersey media moxy dependency 20 20 eee ceeeeeceeeneceeeneeeeeneeeeeeeeaeeeeaeeeeaeeneeas 122 8 40 Register the MoxyXml Feature Class eres eee cece cece na ceca eap Ep aE e OSSEE S 122 8 41 Configure and register an MoxyXmlFeature instance 20 eee eeeeeeeeeceeeeeeeeeeeneeeenn eres 122 8 42 Building client with MultiPart feature enabled 0 ceeeceeseeceeececeeeeeaueeeeecenueeeeaees 123 8 43 Creating JAX RS application with MultiPart feature enabled eee cee cence ee eee 124 8 44 MiG Part entity sad eee n EEE dengy One aue pease a E Ee wen des ER R S eter eds 124 8 45 MultiPart entity in HTTP message oia e cece c cn ec cece cee c cen E E N 124 8 46 PormDataMuLe Part entity ona iss nue n te conven icathes fou csten deen e geno seer a NEES 125 8 47 FormDataMultiPart entity in HTTP message 0 00 0 cece cece ence ence eeeeeeeeeeenees 125 8 48 Multipart sending Tess sprone ved gees eocdesne Sen dbehesuauss vvvedeye ys oumece vedo E e REE S 126 8 49 Resource method using Mult iPart as input parameter return value
64. ResourceConfig 2 Set query parameter name for dynamic filtering 3 property SelectableEntityFilteringFeature QUERY_PARAM NAME select 4 Register the SelectableEntityFilteringFeature 5 register SelectableEntityFilteringFeature class 6 Further configuration of ResourceConfig 7 register Use similar steps to register entity filtering on client Example 18 4 Registering and configuring entity filtering feature on client 1 final ClientConfig config new ClientConfig 2 Set entity filtering scope via configuration 3 property EntityFilteringFeature ENTITY_FILTERING_SCOPE new Annotation 4 Register the EntityFilteringFeature 5 6 7 8 register EntityFilteringFeature class Further configuration of ClientConfig register 9 Create new client 10 final Client client ClientClientBuilder newClient config 11 12 Use the client 18 2 Components used to describe Entity Filtering concepts In the next section the entity filtering features will be illustrated on a project tracking application that contains three classes in it s domain model and few resources only Project resource will be shown in this chapter The full source code for the example application can be found in Jersey Entity Filtering example https github com jersey jersey tree 2 10 examples entity filtering Suppose there are three domain model classes or entities
65. Running TestNG Tests It is possible to run not only JUnit tests but also tests based on TestNG In order to do this you need to make sure the following 2 steps are fulfilled e Extend JerseyTestNg https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTestNg html or one of it s inner classes JerseyTestNg ContainerPerClassTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTestNg ContainerPerClassTest html JerseyTestNg ContainerPerMethodTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTestNg ContainerPerMethodTest html instead of JerseyTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html e Add TestNG to your class patch i e lt dependency gt lt groupid gt org glassfish jersey test framework lt grouplId gt lt artifactId gt jersey test framework core lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt lt dependency gt lt groupId gt org testng lt groupid gt lt artifactId gt testng lt artifactId gt lt version gt lt version gt lt dependency gt To discuss the former requirement in more depth we need to take a look at the differences between JUnit and TestNG JUnit creates a new instance of a test class for every test present in that class which from the point of view of Jersey Test Framework means that new test container and client is cr
66. RuntimeResource getFirstParentResource use Resource getParent _ https jersey java net apidocs 2 10 jersey org glassfish jersey server model Resource html getParent instead e WADL is by default displayed in the simplified form It does not contain supporting resources like OPTIONS methods or application wad1 itself In order to get the full WADL use query param detail true For example make a GET request to http localhost 8080 application wadl detail true 25 6 Migrating from Jersey 2 5 to 2 5 1 e WADL is by default displayed in the simplified form It does not contain supporting resources like OPTIONS methods or application wad1 itself In order to get the full WADL use query param detail true For example make a GET request to http localhost 8080 application wadl detail true 25 7 Migrating from Jersey 2 4 1 to 2 5 25 7 1 Client side API and SPI changes e Client chunked encoding configuration behaviour has changed Jersey client uses chunked encoding streaming for serialization of the entity as a default option Before Jersey 2 5 release entity buffering has been used by default The size of the chunk can still be controlled by ClientProperties CHUNKED_ENCODING_SIZE https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html CHUNKED_ENCODING_SIZE property this property however no longer enforces the use of chunked encoding To control request entity buffering and chunke
67. S 250 vi Jersey 2 10 User Guide 21 Custom Injection and Lifecycle Management 0 cece cece cece eee cee ce eece cena eens ceneeeneeennees 252 21 1 Implementing Custom Injection Provider e cece cece eee cee ceeeee seen seca eena sean eeaes 252 21 2 Defining Custom Injection Annotation 20 0 0 cece cece eecenece ence eeceeeeeeeaeeeaeeenes 254 21 3 Custom Life Cycle Management 00 ce cece cenecenece eee eeceeeeeeeeaeeea essa sean eeaes 256 222 Spring DI bs sces ogeh vonage sewedeycoseuatles a E A E amass tedue sees a EEE EA E deeb utes 260 221s Dependencies errana er te Sandee devs ased tusen EEE O ade prbueroeenuare indie x 260 22 2 Registration and Configuration cece cece ceeccn eee eece cena cen censeeeeeeeeeeeseeeseaeeaaes 260 22 3 BRAM DI lE E S ota A E inet eta tim iat Lt 260 23 Jersey Test Framework reyra eer r suds neues dba pe seedsseh wea tosh wenssstueenabep eens 261 D3 Ve Basis assis veces esata ese Un aden vino oe dae E abeenea dud asada aces E 261 23 27 Supported Containers wis ssc geet vetncs denn tact caatace ea nusdee se E dae seweeareagnenteeteewises 262 23 3 Running TestNG Tests enpor e wieod statin we enced estieed nese N EE A E 263 23 4 Advanced feurs sic nn a EEE sumads peter gun e OE AE EE O E near aeons dete 266 23 4 1 JSersevTest Features sorreran Eie a E E ETEN ceeten ones 266 23 42 External COMAMER cieren E NE T AE RE N tags 266 23
68. 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 Custom 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 89 JAX RS
69. T3 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 after this filter 140 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 cli
70. User getUser PathParam id String id User u findUser id return uj 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 17 4 4 Annotation Inheritance 17 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 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 17 11 Validate getter on execution Example 17 11 Validate getter on execution Path class MyResourceClass Email ValidateOnExecution public String getEmail return email Th
71. 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 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 https jersey java net apidocs 2 10 jersey org glassfish jersey client ChunkParser htm which reads chunks from the input stream and separates them Jersey provid
72. a bvienie E en 74 9 3 6 Example SUMMALY lt sos sesh cases ear e e SE de sanee ey E E EE E E AN 75 5 4 Java instances and types for representations ceeceeeceseeeeeeececneeeeueeeeeeceeueeeeneeeees 76 5 4 1 Adding support for new representations se sseeseseesrerresrerrerrerrreesreererreees 76 5 5 Client Transport Connectors mi enro E E E a EE T E EE I EANN 11 5 6 Using client request and response filters seseseeeseseeseeeetrestrerteertrestresrresrresereserss 79 5 7 Clos Si CONNECHONG esn e aee SET EE Lake N E E E EE Gee Raia 79 5 8 Injections into client provid fsi sessioissa seene ER R nE 80 X9 Securine a Chent e erine enia a E eee tab E E E E E AE E TE 80 5 9 1 Http Authentication Support essseessseesesseesrerrsrrerrsrrerrereserresrrereereerrereeeeee 81 6 Representationsand Responses snesena og bt ade och asada ended eed abe eee 83 6 1 Representations and Java Types ernennen nie a I Ea 83 6 2 Burlding Responses cist cccstan tegbeb pee gh else Psa ty ee ian ised taba ceeday Fs ed a ea ieee 84 6 3 WebApplicationException and Mapping Exceptions to Responses e eeeeeee ee ee 85 6 4 Conditional GETs and Returning 304 Not Modified Responses cceeeeeeeeeee es 87 T JAX RS Entity PLOVICELS erren Mow feet dae e a ce shoes laee uch thee eave dame Serwedecdebuadeseeuweaas dan 89 Cle Introd UCH ON lt 8 sec tic meant wre tate Tae ee eet Nea pE seed wens cele A re
73. 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 0 apidocs javax ws rs PathParam html and the other parameter based annotations MatrixParam _ http jax rs spec java net nonav 2 0 apidocs javax ws rs MatrixParam html HeaderParam http jax rs spec java net nonav 2 0 apidocs 36 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 extr
74. always null Use ContainerLifecycleListener https jersey java net apidocs 2 10 jersey org glassfish jersey server spi ContainerLifecycleListener html to listen on application destroy and get the destroy time org glassfish jersey spi ResponseExecutorsProvider contract has been completely removed from the Jersey SPI as it was inconsistently used by Jersey runtime and we did not find a suitable use case where a custom response executor would make sense While we have no indication that the removed SPI is used in the Jersey community please do not hesitate to contact us in case you think that you have a valid use case where the use of a custom response executor makes sense org glassfish jersey spi RequestsExecutorsProvider contract has been renamed to RequestExecutorProvider _ https jersey java net apidocs 2 10 jersey org glassfish jersey spi RequestExecutorProvider html It has been also extended with an additional releaseRequestingExecutor method to address executor shutdown handling issues reported in JERSEY 2205 https java net jira browse JERSEY 2205 As such any custom implementation of the SPI is now required to implement the new method 25 8 Migrating from Jersey 2 4 to 2 4 1 The unsupported ClientProperties BUFFER_RESPONSE_ENTITY_ON_EXCEPTION property with value of jersey config client bufferResponseEntityOnException has been removed from the API Since Jersey 2 4 where JERSEY 2157 https java net jira browse j
75. and JettyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey jetty connector JettyConnectorProvider html only ClientProperties PROX Y_PASSWORBsey config client pu https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html PROX Y_PASSWORD Jersey 2 5 or later Basswork swouhich will be used for HTTP proxy authentication Default value is not set Currently supported with ApacheConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey apache connector ApacheConnectorProvider html and JettyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey jetty connector Jetty ConnectorProvider html only ClientProperties READ_TIMEOU https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html 4READ_TIMEOUT Jersey 2 5 or later Fersey config client reReddmetmeout interval in milliseconds Default value is 0 infinity ClientProperties REQUEST_ENTITa amp PROCESSING client reefines whetherythe request entity https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html REQUEST Jersey 2 5 or later ENTITY_PROCESSING should be serialized using internal buffer to evaluate content length or chunk encoding should be used Possible values are BUFFERED 295
76. 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 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 CustomNotFound 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
77. are added to response 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 2 10 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 118 Support for Common Media Type Representations Example 8 32 Planet class 1 XmlRootElement 2 public class Planet 3 public int id 4 public String name 5 public double radius 6 Example 8 33 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 XmlRootElement http jaxb java net nonav 2 2 7 docs
78. 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 33 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 html annotation at the class level The doGetAsHtml method s Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation overrides the class level Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html setting and specifies that the method can produce HTML rather than plain text If a resource class is capable of producing more that one MIME media type then the resource method chosen will correspond to the most acceptable media type as declared by the client More specifically the Accept header of the HTTP request declares what is most acceptable For example if the Accept header is Accept text plain then the doGetAsPlainText method will be invoked Alternatively if the Accept header is Accept text plain q 0 9 text html which declares that the client can accept media types of text plain and text html but prefers the latter then the doGet
79. be achieved Example 17 13 Support for injecting Jersey s resources providers via ConstraintValidatorFactory public class InjectingConstraintValidatorFactory implements ConstraintValidatorFac Context private ResourceContext resourceContext Override public lt T extends ConstraintValidator lt gt gt T getInstance final Class lt T gt key return resourceContext getResource key Override public void releaseInstance final ConstraintValidator lt gt instance NOOP Note This behaviour may likely change in one of the next version of Jersey to remove the need of manually providing support for injecting resources providers from Jersey in your own ConstraintValidatorFactory implementation code 17 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 Constraint ViolationException 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
80. build Here we have built a OAuthlAuthorizationFlow utility component representing the OAuth 1 authorization flow using OAuth1ClientSupport and OAuth1Builder API The static builder method accepts mandatory parameter with ConsumerCredentials These are credentials earlier issued by Twitter for our application We have specified the Twitter OAuth endpoints where Request Token Access Token will be retrieved and Authorization URI to which we will redirect the user in order to grant user s consent Twitter will present an HTML page on this URI and it will ask the user whether he she would like us to access his her account Now we can proceed with the OAuth authorization flow Example 15 8 Perform the OAuth Authorization Flow String authorizationUri authFlow start here we must direct the user to authorization uri to approve our application The result will be verifier code String AccessToken accessToken authFlow finish verifier Bm wWN FP In the first line we start the authorization flow The method internally makes request to the http api twitter com oauth request_token URL and retrieves a Request Token Details of this request can be found in the OAuth 1 specification It then constructs a URI to which we must redirect the user The URI is based on the Twitter s authorization URI http api twitter com oauth authorize and contains a Request Token as a query parameter In the Twitter example we have a simp
81. by the client Once the connection is established by the client it is the server who provides the data and 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
82. current request context for any request event type See javadoc of events and event types to get familiar with event types and information valid for each event type Our MyRequestEvent Listener implementation is focused on processing 2 request events First it listens for an event that is triggered before a resource method is executed Also it hooks to a request finished event As mentioned earlier the request event START is handled only in the MyApplicationEventListener The START event type will never be invoked on RequestEventListener Therefore the logic for measuring the start Time is in the constructor which is invoked from MyApplicationEventListener onRequest An attempt to handling the request START event ina RequestEventListener onEvent method would be a mistake Let s deploy the application and use a simple test client code to produce some activity in order to spawn new events 1 target path resource request 2 post Entity entity post MediaType TEXT_PLAIN_TYP 3 target path resource request get GI Ve In the code above the target is a WebTarget http jax rs spec java net nonav 2 0 apidocs javax ws rs client WebTarget html instance pointing to the application context root path Using the Chapter 5 Client API we invoke GET and POST methods on the MyResource JAX RS resource class that we implemented earlier When we start the application r
83. extension module providing support for Entity Data Filtering jersey metainf services https jersey java net project info 2 10 jersey project jersey metainf services dependencies html Jersey extension module enabling automatic registration of JAX RS providers MBW MBR EM via META INF services mechanism jersey mvc https jersey java net project info 2 10 jersey project jersey mvc dependencies html Jersey extension module providing support for MVC jersey mvc bean validation https jersey java net project info 2 10 jersey project jersey mvc bean validation dependencies html jersey mvc freemarker https jersey java net project info 2 10 jersey project jersey mvc freemarker dependencies html Jersey extension module providing support for Bean Validation in MVC Jersey extension module providing support for Freemarker templates jersey mvc jsp https jersey java net project info 2 10 jersey project jersey mvc jsp dependencies html Jersey extension module providing support for JSP templates 18 Modules and dependencies Jersey Extensions jersey mvc mustache https jersey java net project info 2 10 jersey project jersey mvc mustache dependencies html jersey proxy client https jersey java net project info 2 10 jersey project jersey proxy client dependencies html Jersey extension module providing support for Mus
84. 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 and 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 exec java The application starts a
85. fo00 Foo index jsp provided there exists a com foo0 Foo index jsp JSP page in the web application Jersey will assign the model instance to the attribute named model or it So it is possible to reference the foo property on the Foo resource from the JSP template as follows 234 MVC Templates 19 7 lt h1 gt S model fo00 lt h1 gt or lt h1 gt S it foo lt h1 gt To include another JSP page in the currently processed one a custom include tag can be used Mandatory parameter page represents a relative template name which would be absolutized using the same resolving resource Class as the parent JSP page template Example 19 12 Including JSP page into JSP page lt t page contentType text htm1 gt lt S page pageEncoding UTF 8 gt lt S taglib prefix rbt uri urn org glassfish jersey servlet mvc gt lt html gt lt body gt lt rbt include page include jsp gt lt body gt lt html gt Available configuration properties e JspMvcFeature TEMPLATE BASE PATH jersey config server mvc templateBasePath jsp The base path where JSP templates are located Maven users can find this module at coordinates lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey mvc jsp lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt and for non Maven users the list of dependencies is available at jersey mvc j
86. following sub sections show code examples 25 11 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 ClientBuilder newClient WebTarget target client target restURL path myresource param String result target pathParam param value get String class 25 11 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 ClientBuilder newClient WebTarget target client target restURL target register new HttpBasicAuthFilter username password 25 11 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 ClientBuilder newClient WebTarget target client target restURL Response response target request text plain get 25 11 2 4 Attaching entity to request Jersey 1 x way 286 Migration Guide Client client Client create WebResource webResource
87. 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 Throwable 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 below 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 1 3 p 14 System out printin entityFuture get Here the generic type of the invocation callback information is used to unmarshall the HTTP response content into a desired Java
88. 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 produce new links 153 Chapter 12 Declarative Hyperlinking RESTful APIs must be hypertext driven http roy gbiv com untangled 2008 rest apis must be hypertext driven JAX RS currently offers UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html to simplify URI creation but Jersey adds an additional annotation based alternative that is described here Important This API is currently under development and experimental so it is subject to change at any time 12 1 Dependency To use Declarative Linking you need to add jersey jersey ent module to your pom xml file lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey declarative linking lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt If you re not using Maven make sure to have all needed dependencies see jersey declarative linking https jersey java net project info 2 10 jersey project jersey declarative linking dependencies html on the classpath 12 2 Links in Representations Links are added to
89. get Properties method jersey config workers legacyOrdering true Documentation of this property can be found in the javadoc of MessageProperties https jersey java net apidocs 2 10 jersey org glassfish jersey message MessageProperties html The algorithm for selection of MessageBodyReader lt T gt 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 lt T gt 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 readFrom method Select the set of available MessageBodyReader lt T gt providers that support the media type of the request Iterate through the selected MessageBodyReader lt T gt 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 lt T gt then use its readF rom method to map the entity body to the desired Java type 98 JAX RS Entity Providers e Otherwise the s
90. 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 possible 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 2 10 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 10 11 Chapter 2 Modules and dependencies 2 1 Java SE Compatibility Until version 2 6 Jersey was compiled with Java SE 6 This has changes in Jersey 2 7 Now almost all Jersey components are compiled with Java SE 7 target It means that you will need at least Java SE7 to be able to compile and run your application that is using latest Jersey Only core common and core client modules are still compiled with Java class version runnable with Java SE 6 2 2 Introduction to Jersey dependencies Jersey is built assembled and installed using Apache Maven htt
91. getAverageDuration 18 19 MonitoringStatistics _ https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring MonitoringStatistics html are injected into the resource using an Inject http docs oracle com javaee 6 api javax inject Inject html annotation Please note the usage of the Provider http docs oracle com javaee 6 api javax inject Provider html for injection it will be discussed later Firstly the snapshot of statistics is retrieved by the snapshot method The snapshot of statistics is an immutable copy of statistics which does not change over the time Additionally data in a snapshot are consistent It s recommended to create snapshots before working with the statistics data and then process the snapshot data Working with original non snapshot data makes sense when data consistency is not important and performance is of highest concern While it is currently not the case the injected non snapshot data may be implemented as mutable for performance reasons in a future release of Jersey The injected monitoring statistics represent the root of the collected statistics hierarchy The hierarchy can be traversed to retrieve any partial statistics data In the example we retrieve certain request TimeWindowStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring Time WindowStatistics html data In our case those are the request execution statistics for a time wi
92. gt 4 5 1 2 Grizzly HTTP Server Grizzly http grizzly java net is a multi protocol framework built on top of Java NIO http docs oracle com javase 6 docs api java nio package summary html Grizzly aims to simplify 53 Application Deployment and Runtime Environments development of robust and scalable servers Jersey provides a container extension module that enables support for using Grizzly as a plain vanilla HTTP container that runs JAX RS applications Starting a Grizzly server to run a JAX RS or Jersey application is one of the most lightweight and easy ways how to expose a functional RESTful services application Grizzly HTTP container supports injection of Grizzly specific org glassfish grizzly http server Request and org glassfish grizzly http server Response instances into JAX RS and Jersey application resources and providers However since Grizzly Request is not proxiable the injection of Grizzly Request into singleton by default JAX RS Jersey providers is only possible via javax inject Provider instance Grizzly Response does not suffer the same restriction Example 4 6 Using Jersey with Grizzly HTTP Server 1 URI baseUri UriBuilder fromUri http localhost port 9998 build 2 ResourceConfig config new ResourceConfig MyResource class 3 HttpServer server GrizzlyHttpServerFactory createHttpServer uri config The container extension module dependency to be added is l
93. html Filtering based on entity filtering annotations or i e external configuration file created using EntityFiltering https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering Entity Filtering html meta annotation SecurityEntityFilteringFeature https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering SecurityEntityFilteringFeature html Filtering based on security javax annotation security and entity filtering annotations SelectableEntityFilteringFeature https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering SelectableEntityFilteringFeature html Filtering based on dynamic and confi If you want to use both entity filterin it is enough to register Security gurable query parameters g annotations and security annotations for entity data filtering EntityFilteringFeature as this feature registers also EntityFilteringFeature Entity filtering currently recognizes one property that can be passed into the Configuration http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configuration html instance client server e EntityFilteringFeature ENTITY_FILTERING_SCOPE https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering EntityFilteringFeature html ENTITY_FILTERING_ SCOPE Jersey config entityFiltering scope Defines one or more annotations that entity Note s
94. html Jersey Servlet 3 example with missing servlet class in the web xml file shortener webapp https jersey java net project info 2 10 Jersey Shortener Webapp MVC Bean Validation 28 Modules and dependencies Jersey Examples jersey project webapp example parent shortener webapp dependencies html simple console https jersey java net project info 2 10 jersey project simple console dependencies html Jersey Simple Console example sparklines https jersey java net project info 2 10 jersey project sparklines dependencies html Jersey examples sse item store webapp https jersey java net project info 2 10 jersey project webapp example parent sse item store webapp dependencies html Jersey SSE based item store example sse twitter aggregator https jersey java net project info 2 10 jersey project sse twitter aggregator dependencies html Jersey SSE Twitter Message Aggregator Example system properties example https jersey java net project info 2 10 jersey project system properties example dependencies html Jersey system properties example tone generator https jersey java net project info 2 10 jersey project tone generator dependencies html Jersey examples webapp example parent https jersey java net project info 2 10 jersey project webapp example parent dependencies html
95. 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 16 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 7 init countryService 8 9 10 GET 11 Produces MediaType APPLICATION_XML 12 public Country getCountry PathParam countryId int countrylId 13 return countryService getCountry countrylId 14 ES The WADL of a Jersey application that contains the resource above can be requested by a HTTP GET requesttohttp localhost 9998 application wadl The Jersey will return a response with a WADL content similar to the one in the following example 1 lt xml version 1 0 encoding UTF 8 standalone yes gt 2 lt application xmlns http wadl dev java net 2009 02 gt 3 lt doc xmlns jersey http jersey java net jersey generatedBy Jersey 2 lt grammars gt lt resources base http localhost 9998 gt lt resource path country id gt lt param xmlns xs http www w3 org 2001 XMLSchema type xs int s lt method name GET id getCountry gt lt response gt LC OANA OB 188 WADL Support 10 lt representation mediaType application xml gt 11 lt response gt T2 lt method gt 13 lt resource gt 14 lt reso
96. jax rs spec java net nonav 2 0 apidocs javax ws rs BeanParam html can be used to inject such a bean into a resource or resource method The BeanParam http jax rs spec java net nonav 2 0 apidocs javax ws rs BeanParam htm is used this way to aggregate more request parameters into a single bean 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 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 QueryParam 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 BeanParam 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 0 apidocs javax ws rs QueryParam html MatrixParam http jax rs spec java net nonav 2 0 apidocs javax ws rs MatrixParam html
97. lang Object various arguments Resolve and relativize methods in Urilnfo _ http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo htm are essentially counterparts to the methods listed above Urilnfo resolve Gjava net URD http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html resolve Gjava net URD resolves 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 htm 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 h
98. 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 nonav 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 84 Representations and Responses Example 6 2 Returning 201 status code and adding Location header in response to POST request POST Consumes
99. modules dependencies and add a dependency of your own lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey bean validation lt artifactId gt lt version gt 2 10 lt version gt lt exclusions gt lt exclusion gt lt grouplid gt org hibernate lt grouplid gt 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 3 Auto Discoverable Features Jersey Bean Validation is one of the modules where you don t need to explicitly register it s Features ValidationFeature https jersey java net apidocs 2 10 jersey org glassfish jersey server validation ValidationFeature html on the server as it s 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 198 Bean Validation Support e CommonProperties FEATURE_AUTO_DISCOVERY_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE e ServerProperties FEATURE_AUTO_DISCOVERY_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html FEATURE_AUTO_DISCOVERY_DISABLE e ServerProperties BV_FEA
100. more than likely that URIs will be built from the base URI the web service is deployed at or from the request URI The class Urilnfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core Urilnfo html provides such information in addition to further information see next section The following example shows URI building with UriInfo and UriBuilder from the bookmark example Example 11 1 URI building 1 Path users 2 public class UsersResource 3 4 Context 5 UriiInfo urilInfo 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 Urilnfo is obtained using the Context annotation and in this particular example injection onto the field of the root resource class is performed previous examples showed the use of Context on resource method parameters UrilInfo 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
101. 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 WN EF 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 client Config 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 client instance are also reflected in the newConfiguration So newConfiguration is really 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 72 Client
102. 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 XmlRootElement 2 public class MyJaxbBean 3 public String name 4 public int age 5 6 public MyJaxbBean JAXB needs this 7 8 public MyJaxbBean String name int age 9 this name name 10 this age age 11 12 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 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 103 Support for
103. path directly Note however that template processors for custom templating engines may modify and the supported ones do absolute template reference by pre pending base template path if defined and appending template suffix i e foo if the suffix is not provided in the reference For example assume that we want to use Mustache templates for our views and we have defined base template path as pages For the absolute template reference com example Foo index the template processor will transform the reference into the following path pages com example Foo index mustache Handling errors with MVC In addition to Template https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Template html a ErrorTemplate https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc ErrorTemplate html annotation has been introduced in Jersey 2 3 The purpose of this annotation is to bind the model to an error view in case an exception has been raised during processing of a request This is true for any exception thrown after the resource matching phase i e this not only applies to JAX RS resources but providers and even Jersey runtime as well The model in this case is the thrown exception itself 229 MVC Templates Example 19 5 Using ErrorTemplate on a resource method shows how to use ErrorTemplate on a resource method If all goes well with the method processing then the short
104. resources are a standard part of your RESTful Web application that defines the REST API of your application The 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 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 Example 14 1 Add jersey media sse dependency 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 Note Prior to Jersey 2 8 you had to manually register SseFeature https jersey java net apidocs 2 10 jersey org glassfi
105. 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 BroadcasterResoutrce that is handled by the listenToBroadcast resource method The method creates a new Event Output representing 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 170 Server Sent Events SSE Support way and passed to the broadcaster The broadcast
106. test framework functionality JerseyTest constructor JerseyTest Class lt extends Application gt has been made deprecated and will be removed in the subsequent Jersey release It was previously possible to pass in a custom ContainerProvider https jersey java net apidocs 2 10 jersey org glassfish jersey server spi ContainerProvider html that was supposed to deploy and run the application as one of the JAX RS Jersey application providers This ability has been removed without any substitute as the concept was fundamentally flawed Typical use cases should not be affected by this change Factory methods createHttpServer which take Jersey ApplicationHandler https jersey java net apidocs 2 10 jersey org glassfish jersey server ApplicationHandler html as one of the input parameters have been removed from the Jersey container factory API as inherently broken This impacts GrizzlyHttpServerFactory https jersey java net apidocs 2 10 jersey org glassfish jersey grizzly2 httpserver GrizzlyHttpServerFactory html JdkHttpServerFactory _ https jersey java net apidocs 2 10 jersey org glassfish jersey jdkhttp JdkHttpServerFactory html JettyHttpContainerFactory https jersey java net apidocs 2 1O jersey org glassfish jersey jetty JettyHttpContainerFactory html and SimpleContainerFactory https jersey java net apidocs 2 10 jersey org glassfish jersey simple SimpleContainerFactory html implementations The methods that take Resou
107. 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 lt lt Ee A ONT O G LANT EF 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 core Form html instance is created with two form parameters Once ready the Form instance is POSTed to the target resource First t
108. the default relative template reference index will be used for more on this topic see Section 19 3 Absolute vs Relative template reference As for the missing resource methods a default GET method will be automatically generated by Jersey for the Foo resource which is the MVC Controller now The implementation of the generated resource method performs the equivalent of the following explicit resource method GET public Viewable get return new Viewable index this You can see that the resource class serves in this case also as the model Producible media types are determined based on the Produces annotation declared on the resource class if any Note In case of resource class based implicit MVC view templates the controller is also the model In such case the template reference index is special it is the template reference associated with the controller instance itself In the following example the MVC controller represented by a JAX RS GET sub resource method is also generated in the resource class annotated with Template GET Path implicit view path parameter public Viewable get PathParameter implicit view path parameter String templa return new Viewable template this This allows Jersey to support also implicit sub resource templates For example a JAX RS resource at path foo bar will try to use relative template reference bar that resolves to an ab
109. the following code sample 90 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 2 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 MyBean 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 th
110. their modules as well as discusses any module specific details 19 6 1 Mustache An integration module for Mustache https github com spullara mustache java based templating engine Mustache template processor resolves absolute template references to processable template references represented as Mustache templates as follows Procedure 19 1 Resolving Mustache template reference 1 if the absolute template reference does not end in mustache append this suffix to the reference and 2 if ServletContext getResource Class getResource or File existsreturns a non null value for the reference then return the reference as the processable template reference otherwise return null to indicate the absolute reference has not been resolved by the Mustache template processor Thus the absolute template reference com f00 Foo index would be resolved as com fo00 Foo index mustache provided there exists a com foo Foo index mustache Mustache template in the application Available configuration properties e MustacheMvcFeature TEMPLATE BASE PATH jersey config server mvc templateBasepath mustache The base path where Mustache templates are located e MustacheMvcFeature CACHE_TEMPLATES jersey config server mvc caching mustache Enables caching of Mustache templates to avoid multiple compilation 232 MVC Templates e MustacheMvcFeature TEMPLATE _OBJECT_FACTORY jersey config server mvc factory mu
111. this SPI are invoked to retrieve entity filtering scopes from an array of provided annotations Example 18 19 Entity filtering annotation with custom meaning 1 Target ElementType TYPE 2 Retention RetentionPolicy RUNTIME 3 EntityFiltering 4 public interface FilteringAggregator 5 6 7 Entity filtering scope to add given fields to 8 ef 9 Annotation filteringScope 10 11 12 Fields to be a part of th ntity filtering scope 13 14 String fields TSA 18 7 Supporting Entity Data Filtering in custom entity providers or frameworks To support Entity Data Filtering in custom entity providers e g as in Example 18 20 Entity Data Filtering support in MOXy JSON binding provider it is sufficient in most of the cases to implement and register the following SPI contracts 223 Entity Data Filtering e ObjectProvider ObjectProvider html https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering sp1 To be able to obtain an instance of a filtering object model your provider understands and can act on The implementations can extend AbstractObjectProvider https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering spi AbstractObjectProvider html e ObjectGraphTransformer https jersey java net apidocs 2 10 jersey org glassfish jersey m filtering spi ObjectGraphTransformer html essage To transfor
112. 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 matched 3 1 2 GET PUT POST DELETE HTTP Methods GET _ http jax rs spec java net nonav 2 0 apidocs javax ws rs GET html PUT http jax rs spec java net nonav 2 0 apidocs javax ws rs PUT html POST http jax rs spec java net nonav 2 0 apidocs javax ws rs POST html DELETE http jax rs spec java net nonav 2 0 apidocs javax ws rs DELETE html and HEAD http jax rs spec java net nonav 2 0 apidocs javax ws rs HEAD 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 32 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 met
113. use the standard JAXB mechanisms to 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 https jersey java net apidocs 2 10 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 39 Add jersey media moxy dependency lt dependency gt lt grouplid gt org glassfish jersey media lt groupId gt lt artifactId gt jersey media moxy lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt Example 8 40 Register the MoxyXmlFeature class 1 final ResourceConfig config new ResourceConfig 2 packages org glassfish jersey examples xmlmoxy 3 register MoxyXxXmlFeature class Example 8 41 Configure and register an MoxyXmlFeature instance Configure Properties final Map lt String Object gt properties new HashMap lt String Object gt Obtain a ClassLoader you want to use OANA OF WN 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 whet
114. used in the example for demonstration of how to configure the flow for needs of specific service providers in this case the readOn1ly param would be described in the service provider s documentation Between the calls to flow start and flow finish a user must be redirected to the authorization URL This means that the code will not be executed in a single method and the finish part will be invoked as a handler of redirect request back to our web from authorization URI Check the example OAuth 2 Google Client WebApp example https github com jersey jersey tree 2 10 examples oauth2 client google webapp for more details on this approach 187 Chapter 16 WADL Support 16 1 WADL introduction Jersey contains support for Web Application Description Language WADL http wad1 java net WADL is a XML description of 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 Important Since Jersey 2 5 1 the WADL generated by default is WADL in shorter form without additional extension resources OPTIONS methods WADL resource In order to get full WADL use the query parameter detail true Let s start with the simple WADL example In the example there
115. using two programming models Pull model pulling events from a EventInput https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventInput html or Push model listening for asynchronous notifications of Event Source Both models will be described 14 5 1 Reading SSE events with Event Input The events can be read on the client side from a EventInput https jersey java net apidocs 2 10 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 readData String class 14 In this example a client connects to the server where the SseResource from the Example 14 2 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 request The returned respons
116. ws rs ext Provider public class PerSessionComponentProvider implements ComponentProvider 257 Custom Injection and Lifecycle Management private ServiceLocator locator static class PerSessionFactory implements Factory lt PerSessionResource gt static ConcurrentHashMap lt String PerSessionResource gt perSessionMap new ConcurrentHashMap lt String PerSessionResource gt j private final Provider lt HttpServletRequest gt requestProvider private final ServiceLocator locator Inject public PerSessionFactory Provider lt HttpServletRequest gt request ServiceLocator locator this requestProvider request this locator locator Override PerLookup public PerSessionResource provide final HttpSession session requestProvider get getSession if session isNew PerSessionResource newlInstance createNewPerSessionResource perSessionMap put session getId newInstance return newlInstance else return perSessionMap get session getId Override public void dispose PerSessionResource r private PerSessionResource createNewPerSessionResource final PerSessionResource perSessionResource new PerSessionResource locator inject perSessionResource return perSessionResource Override public void initialize ServiceLocator locator this locator locator Override public boolean bind Class lt gt component Set lt Cl
117. 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 1
118. 0 jersey project http patch dependencies html http trace https jersey java net project info 2 10 jersey project http trace dependencies html Jersey example for implementing generic PATCH support via JAX RS reader interceptor Taken from Gerard Davison s blog entry http kingsfleet blogspot co uk 2014 02 transparent patch support in jax rs 20 html Jersey HTTP TRACE support example https clientserver grizzly https jersey java net project info 2 10 jersey project https clientserver grizzly dependencies html Jersey HTTPS Client Server example on Grizzly https server glassfish https jersey java net project info 2 10 jersey project webapp example parent https server glassfish dependencies html Jersey HTTPS server on GlassFish example jaxb https jersey java net project info 2 10 jersey project jaxb dependencies html jaxrs types injection https jersey java net project info 2 10 jersey project jaxrs types injection dependencies html Jersey JAXB example Jersey JAX RS types injection example jersey ejb https jersey java net project info 2 10 jersey project webapp example parent jersey ejb dependencies html Jersey Web Application Servlet examples parent POM json jackson https jersey java net project info 2 10 jersey project json jackson dependencies html Jersey JSON with Jackson example json jettison https
119. 0 lt version gt lt dependency gt and for non Maven users the list of dependencies is available at jersey mvc bean validation https jersey java net project info 2 10 jersey project jersey mvc bean validation dependencies html 19 5 Registration and Configuration To use the capabilities of Jersey MVC templating support in your JAX RS Jersey application you need to register specific JAX RS Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature html s provided by the MVC modules For jersey mvc module it is MvcFeature https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc MvcFeature html for others it could be for example FreemarkerMvcFeature https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc freemarker FreemarkerMvcFeature html jersey mvc freemarker Example 19 8 Registering MvcFeature new ResourceConfig register org glassfish jersey server mvc MvcFeature class Further configuration of ResourceConfig register Example 19 9 Registering FreemarkerMvcFeature new ResourceConfig register org glassfish jersey server mvc freemarker FreemarkerMvcFeatur Further configuration of ResourceConfig register Note Modules that uses capabilities of the base Jersey MVC module register MvcFeature automatically so you don t need to register this feature explicitly in your code Almost all of the MVC modules are f
120. 080 osgi jersey http service status Please see HTTP Service example https github com jersey jersey tree 2 10 examples osgi http service source code for more details on the example 4 10 Other Environments 4 10 1 Oracle Java Cloud Service As Oracle Public Cloud is based on WebLogic server the same applies as in the paragraph about WebLogic deployment see Section 4 8 4 2 Oracle WebLogic Server More on developing applications for Oracle Java Cloud Service can be found in this guide http docs oracle com cloud 13 1 developer_services CSJSU java develop htm BABHDAJH 68 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 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
121. 11 12 13 GET 14 Produces text plain 15 Interceptors MyInterceptor class 16 public String getIt 17 return Hi managed bean 18 19 4 8 2 Context and Dependency Injection CDI CDI beans can be used as Jersey root resource classes providers as well as Application subclasses Providers and Application subclasses have to be singleton or application scoped The next example shows a usage of a CDI bean as a JAX RS root resource class We assume that CDI has been enabled The code snipped uses the type safe dependency injection provided in CDI by using another bean MyOt herCdiBean 1 Path cdibean 2 public class CdiBeanResource 3 Inject MyOtherCdiBean bean CDI injected bean 4 5 GET 6 Produces text plain 7 public String getIt 8 return bean getIt 9 10 4 8 3 Enterprise Java Beans EJB Stateless and Singleton Session beans can be used as Jersey root resource classes providers and or Application subclasses You can choose from annotating the methods in the EJB s local interface or directly the method in an interface less EJB POJO JAX RS specifications requires its implementors to discover EJBs by inspecting annotations on classes or local interfaces but not in the deployment descriptors ejb jar xml As such to keep your JAX RS application portable do not override EJB annotations or provide any additional meta data in the deployment descriptor file Following example con
122. 120 8 2 4 Using custom JAXBContext oerien E e EE ENEE e REEE iS 121 8 29 5 LO DG A O N ea he mae aed al 122 8 3 Multipart sesse nnie e r Teton auedesss von ete E esp etlecateoretaaasahwon dbs AES NEES 123 83l OVERVIEW Sexist epee ae ne Soe aaah th Wee fa ee Neale eee Cece 123 8 32 Cent cs ase Foch ans etue austen eacu seeder ese dae sha cddeneh ere dccgeruades O N aa Ea ESES 124 8 33 SOMVED EESE EAA EE lel Seen cs eae sates Sadun eee sl eee dia cd tee edad eee eer 126 9 Filters anid Interceptors drina ea secgaeeeweasssen ese dy sh wondess E sete E E aE ERES 129 ONL MMO MUCH on ese re n vanes seb E E E E E T E SA 129 iv Jersey 2 10 User Guide OD FUELS 2420 deacesny ces EEE pa nevanesenwansseatec ANE E EE A shady sovaseypaevencsesdanes es 129 OD hs SOLVER TIMEES war Gass econ iaa ese a a EE sos Use ee E aet donee des EE S 129 O22 CONE filters enia en roe tae ties Saabs E ase daue secu edten Meruen aed Mau sewsarceetosy 132 OS IMUerceptOrs lt 2 rie chs beatae ti ercedts been ac yeceets Seatac E N canes eh Been 132 9 4 Filter and interceptor execution order 0 ee eee cece cece ence ence eeeeeeeeeeeaesea esau sean eeaes 134 9 5 Name DINGING shee Saioties oh nied ace dss e n ca dashes dee Slade ded ET A OA tuned Asis 136 9 6 Dynami Dinding sieisen n hen dsbedasee eves See cob sacnoderebesderbaden genes horace yeaes 138 O 7M PHIOTINLES tesa E TP cece sie eG E ete AEN NS S eth ie aS Ie Set aaa 2 oh 140 10 Asynch
123. 15 16 POST T7 Consumes 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 JAXBE1lement This is because now you need to explicitly set element name for P Lanet class XML representation Client side is even more complicated 120 Support for Common Media Type Representations than server side because you can t do JAXBElement lt Planet gt so JAX RS client API provides way how to workaround it by declaring subclass of GenericType lt T gt Example 8 36 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 lt Planet gt 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 JAXBContext 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 fo
124. 2 10 jersey org glassfish jersey server mvc spi TemplateProcessor html was modified by adding an argument MultivaluedMap lt String Object gt httpHeaders This is an incompatible change the method was modified directly in the interface All Jersey provided MVC implementation were adjusted but if you have your own MVC implementation then you need to modify the method signature of the implementation e A minor JAX RS incompatibility issue has been recently discovered and reported see JERSEY 2387 https java net jira browse JERSEY 2387 As part of the fix minor breaking changes related to URI resolving and creation have been introduced in the behavior of UriBuilder http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriBuilder html Link Builder http jax rs spec java net nonav 2 0 apidocs javax ws rs core Link Builder html and WebTarget http jax rs spec java net nonav 2 0 apidocs javax ws rs client WebTarget html classes It is no longer possible to successfully build a new URI instance from a UriBuilder that contains unresolved template parameters An IllegalArgumentException will be thrown in such case as mandated by JAX RS API javadoc Similarly it is not possible to successfully create a Link http jax rs spec java net nonav 2 0 apidocs javax ws rs core Link html instance from a URI template with unresolved template parameters Also it is not possible to successfully send a request ona WebTarget that represents a U
125. 2 10 lt version gt lt dependency gt lt dependency gt lt groupiId gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container simple http lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container jetty http lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt lt dependency gt lt groupiId gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container jetty servlet lt artifactId gt lt version gt 2 10 lt version gt 14 Modules and dependencies lt dependency gt 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 Jersey Core jersey client https Jersey core client implementation jersey java net project info 2 10 jersey jersey client dependencies html jersey common Jersey core common packages https jersey java net project info 2 10 jersey jersey common dependencies html jersey server https Jersey core server implementation jersey java net project info 2 10 jersey jersey server dependencies html Table 2 2 Jersey Containers Jersey
126. 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 lt dependency gt lt grouplid gt javax ws rs lt grouplid gt 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 lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container servlet lt artifactId gt 12 Modules and dependencies 2 3 2 2 3 3 lt version gt 2 10 lt version gt lt scope gt provided lt scope gt lt dependency gt lt if you are using Jersey client specific features without the server sid gt lt dependency gt lt groupid gt org glassfish jersey core lt groupId gt lt artifactId gt jersey client lt artifactId gt lt version gt 2 10 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 integrated JAX RS implementation Then application needs to include JAX RS API and Jersey implementation in depl
127. 3 69 ms 46 77 WriteTo summary The CATEGORY is used to categorize tracing events according to the following event types e START start of request processing information e PRE MATCH pre matching request filter processing e MATCH matching request URI to a resource method e REQ FILTER request filter processing e RI entity reader interceptor processing e MBR message body reader selection and invocation INVOKE resource method invocation e RESP FILTER response filter processing 249 4 Monitoring and Diagnostics e WI write interceptor processing e MBW message body writer selection and invocation e MVC template engine integration e EXC EPTION exception mapping e FINISHED processing finish summary The TIME if present is acomposite value that consists of 3 parts duration time_from_start total_req_ratio T 1 duration the duration of the current trace event milliseconds e g duration of filter processing time milliseconds time_from_start the end time of the current event with respect to the request processing start total_req_ratio the duration of the current event with respect to the total request processing time percentage this value tells you how significant part of the whole request processing time has been spent in the processing phase described by the current event There are certain tracing events that do
128. 57 Programmatic API for Building Resources Example 13 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 13 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 lt ContainerRequestC 22 23 Override 24 public String apply ContainerRequestContext co 25 return Hello World 26 27 p 28 29 final Res
129. 6 18 10 Annotated Project seori Seodavniden genet dca yeh iaones utes ogebyadeh daub das yteedace stunt daucewuadenseenss 217 18 11 Annotated Usercist s irises E E red ha ee ot ee ee etn ee dita 218 18 12 Annotated Task irena tees spececuga es ayer Sob soomages E tuades yh ned E A AEE ES ENAERE 218 18 13 ProjectsResource Response entity filtering annotations 0 cece ee eeceeece eter ener eens 219 18 14 ProjectsResource Entity filtering annotations on methods ceseeceeeeeeeeeceeneeeeee ees 220 18 15 Client Request entity filtering annotations 0 ee cece ce ee eens ce eece eee eeeeeeeeeeeeeeeaees 221 18 16 Client Request entity filtering annotations 0 cece cece ee ce ee ceneee eee eeeeeeeeeeeeeeeaees 221 18 17 Sever Query Parameter driven entity filtering 1 0 0 0 ceeecc cece ce eececeeeceueeeeeeneenaeeeeuees 222 TST Ss xedenciacts tis harden E E AEE stv daecaue E heeaeeda teaver dacs enh laewes ceed aruba tenes yell arash eenets 223 18 19 Entity filtering annotation with custom meaning eee ee ce ee ce neceeeceeeceeeeeeeeneeenes 223 18 20 Entity Data Filtering support in MOXy JSON binding provider cece eee eee 224 19 1 Using Viewable in a resource ClaSs strons eceee nec cece a E cena eens EE R E REE 226 19 2 Using Template on a resource method 2 0 0 eee cence nce e eee eeeeneeeeeeeeeeeeeeaeeeaees 227 19 3 Using Template on a resource Class 0 0 0 e
130. 6 Override 7 protected Application configure 18 return new ResourceConfig Resource class 19 20 21 Test priority 1 22 public void first throws Exception 23 test 1 24 25 26 Test priority 2 27 public void second throws Exception 28 test 2 29 30 31 private void test final Integer expected 32 final Response response target request get 33 34 assertEquals response getStatus 200 35 assertEquals response readEntity Integer class expected 36 37 e JerseyTestNg ContainerPerMethodTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTestNg ContainerPerMethodTest html creates separate container for each test Setup method is annotated with Be foreMethod teardown method with AfterMethod 264 Jersey Test Framework We can create a similar test to the previous one Take a look at ContainerPerMethodTest test It looks the same except the expected values and extending class it contains two test methods first and second one singleton resource that returns an increasing sequence of number In this case we create a separate test container for each test so value expected in the first test is 1 and in the second it s also 1 1 2 3 4 5 6 7 8 9 10 1 2 3 4 5 6 7 8 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 Sia public class ContainerPerMethodTest Path Singleton Produces text
131. 72 1352 SCCUIILY 2 see E eae ces tatugehds Wider adl lien us ea ca AN etad She ela ean oe weare Noam 176 15 3 SCCULIN BESELVET senor cones na ae E eats sewed EEE oven E e sume EPEE E E E e es 176 1ST As Security Comtext 13 eink ie hey MP heed ean adink Aue OT E ence debe 176 15 1 2 Authorization Securing resources 2 2 00 ee eee cee cece eeeceeece seca eeeu seen sean eeaes 177 15 2 Chent Security a5 cotter eed stati cee oles Bate eet Rata ties Mite eet SE 179 15 3 OAuth SUPPO aenieei a E ade goby ERN E ghey een ESS EEEE 180 15 3 OAN a A thse sed ea ck dal ae ee AI OESE 181 1533 2QAUIH 2 S UPpOrt aesecorta se des ec asesh teat aedaee thence elles bas eduae toe techn tet seme 4 185 16 WADE Supports 3 2cin cites E E sehen ece Saad E eee see he ond E tales 188 16 1 WADE introduction iss noFeh n ce tea E oa gs nadeb ep veada s dy EE we ess dovedey sel eee esa ES 188 16 2 Configuration senerare bi ceds eek Se E os EN EE Meee eb ase ene 196 Jersey 2 10 User Guide 16 3 Extended WADL SUpPOLt esy ene nae o e sa ER ENEE EE seen ageeb ER E REARS E 197 17 Bean Validation Support sienos n a oie E Gace eevee E aed E TE ee 198 17 1 Bean Validation Dependencies nicnn eE e EE EnS 198 17 2 Enabling Bean Validation in Jersey eseeesseerseeeerseesreersrrerrsrrsersrerrrererreersreee 198 17 3 Configuring Bean Validation Support seessssesesisssrresrresrrssrresrresreerrrsrrrerreereeeee 199 17 4 Validating JAX RS r
132. 8 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 method 100 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 oracl
133. 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 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 curl 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 E 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 darwinl1 3 0 libcurl 7 25 0 OpenSSL 1 0 1 gt Host localhost 8080 gt Accept gt lt HTITP 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
134. 92cc747 26d6 4800 Copyi Copyi Copyi osgi resource locator 1 0 1 jar to tmp build_992cc747 2 asm all repackaged 2 2 0 b21 jar to tmp build_992cc747 cglib 2 2 0 b21 jar to tmp build_992cc747 26d6 4800 bdb Copyi Copyi Copyi Copyi Copyi Copyi javax inject 2 2 0 b21 jar to tmp build_992cc747 26d6 4 jersey container servlet 2 5 jar to tmp build_992cc747 jersey container servlet core 2 5 jar to tmp build_992c jersey client 2 5 jar to tmp build_992cc747 26d6 4800 b jersey common 2 5 jar to tmp build_992cc747 26d6 4800 b jersey server 2 5 jar to tmp build_992cc747 26d6 4800 b maven install plugin 2 3 l install default install simpl Installing tmp build_992cc747 26d6 4800 bdb1 add47b9583cd targe Installing tmp build_992cc747 26d6 4800 bdb1 add47b9583cd pom x BUILD SUCCESS Total time 45 861s Finished at Mon Dec 09 19 51 34 UTC 2013 Final Memory 17M 514M gt Discovering process types declares types gt web Procfil 10 Getting Started Se gt Compiled slug size 75 9MB gt Launching done v6 http simple heroku webapp herokuapp com deployed to Heroku To git heroku com simple heroku webapp git new branch master gt master Now you can access your application at for example http simple heroku webapp herokuapp com myresource 1 6 Exploring Other Jersey Examples In the sections above we have covered an approach how to
135. AX 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 most suitable provider for entity 96 JAX RS Entity Providers 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 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
136. AsHtml 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 Produces application xml application json public String doGetAsXmlOrJson Oe WN PF The doGetAsXm1OrJson method will get invoked if either of the media types application xml and application json are acceptable If both are equally acceptable then the former will be chosen because it occurs first 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 w
137. Bean new MyJaxbBean Agamemnon 32 Above you construct a simple JAXB bean which could be written in JSON as name Agamemnon age 32 Now to build an equivalent JsonObject 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 104 Support for Common Media Type Representations Example 8 6 Constructing a JSONObject Jettison 1 JSONObject myObject new JSONOb ject 2 try 3 myObject put name Agamemnon 4 myObject put age 32 5 catch JSONException ex 6 LOGGER log Level SEVERE Error ex 7 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 lt dependency gt lt grouplid gt org
138. Builder 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 SslConfigurator https jersey java net apidocs 2 10 jersey org glassfish jersey SslConfigurator 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 keyStore and SslConfigurator will use such a variable to setup the SslContext See javadoc of SslConfigurator https jersey java net apidocs 2 10 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 3 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 Ssl1Context it will override any previously defined KeyStore and TrustStore settings ClientBu
139. CATION using constants from Priorities http jax rs spec java net nonav 2 0 apidocs javax ws ts Priorities htm 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 15 1 2 Authorization securing resources 15 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 lt security constraint gt 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 177 Security Example 15 3 Securing resources using web xml 1 lt security constraint gt 2 lt web resource collection gt 3 lt url pattern gt rest admin lt url pattern gt 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 lt security constraint gt 9 lt security constraint gt 10 lt web resource collection gt RT lt url pattern gt rest orders lt url pattern gt 12 lt web resource collection gt 13 lt auth constraint gt 14 lt role name gt customer lt ro
140. 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 _ https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientConfig html to the newClient Configurable ClientBuilder factory method ClientConfig https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientConfig htm 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 71 Client API ClientConfig clientConfig new ClientConfig clientConfig register MyClientResponseFilter class clientConfig register new AnotherClientFilter Client client ClientBuilder newClient clientConfig mw WDN FP In the example filters are registered using the ClientConfig register method There are multiple overloaded versions of the method that support registration of feature and provider classes or instances Once a Client Config instance is configured it c
141. 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 JSON 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 my
142. Configuration Properties Constant Value Description or CHUNKED Default value is BUFFERED ClientProperties SUPPRESS_HTTPeCOMPIGANGKH CALEDATIONp r exeHthep Stomp vakdatioadfi dation https jersey java net HTTP specification compliance apidocs 2 10 jersey org for client side requests will be glassfish jersey client suppressed When compliance ClientProperties html S UPPRES _HTTP_COMPLIANCE_VALIDAHdEXN are suppressed any Jersey 2 2 or later violations will be merely logged as warnings rather than causing exceptions being raised in Jersey runtime Default value is false ClientProperties USE_ENCODINGersey config client ug amp iincatesing the value of https jersey java net Content Encoding property apidocs 2 10 jersey org the EncodingFilter https glassfish jersey client jersey java net apidocs 2 10 ClientProperties html USE_ENCODING jersey org glassfish jersey client filter EncodingFilter html should be adding Default value is not set 296
143. EEA NEEESE ES youn 149 1197 URE building s aer ean cases E R ee OEA ds aE ASO A N T aoa 151 11 2 Building URIs using query parameters sesseeesseerrsereereresrrresrrerrsrreersrrsereeesrereerreees 152 12 1 Creating JAX RS application with Declarative Linking feature enabled 0 eee 156 I3 1 Av standard tesOurce Classin e e die nE See bushy eute sd EE R e Saa teens ons 158 13 2 A programmatic resource sorone es ea E sae tu ceed aceeas hues da dsktinn E E 158 13 3 Ay programmatie TESOULCES lt oo098 os dow csdengsved nE dee yedes gcnud damp deb RE ab goveaden greed eas 160 13 4 A programmatic reSOULCE e ce ce ee cence cence neces ceeeea seca tesa eeae eens ON E AO ENTS ri a 160 13 5 A prosrammMatie TESOULCE 2 2 02 s5se seduce nyess gees eenneseoeansaces tune cs ERE RIESE SEE ASEO get 161 13 6 A programmatic resources Tonne aae ea T Wade eee we ates ab ce E R 162 14 1 Add jersey media sse dependency 0 00 cee ceee cece ceecca cece cece cena eens eeneeeneeeeeeeeees 165 14 2 Simple SSE resource method sirs o nre E sven sven scessonssonsenssenesensessesseees 167 14 3 Broadcasting SSE Messages ss ssceee sens ss gave esis pp ywae sees Sen gvsh wens E aE RER EN EEE 170 14 4 Registering Event Listener with Event SOULCE o cece ee tee e cece eeae een eeneeeeeeeee es 172 14 5 Overriding Event Source onEvent InboundEvent method ce ceeeeeeeeeeeeeeeee 174 15 1 Using SecurityContext for a
144. 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 G 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 XmlRootElement 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 constructor needed for deserialization by JAXB 14 public MyBean T5 16 17 Override 18 public String toString 19 return MyBean 20 anyString anyString 21 anyNumber anyNumber 22 en eae 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
145. Factory 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 https jersey java net apidocs 2 10 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 17 12 Injecting Urilnfo into a ConstraintValidator Example 17 12 Injecting UriInfo into a ConstraintValidator public class EmailValidator implements ConstraintValidator lt Email String gt Context private UriInfo urilInfo public void initialize Email email public boolean isValid String value ConstraintValidatorContext context Use UrilInfo 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 207 Bean Validation Support provided by Jersey and injection support for resources providers if needed has to be provided by this new implementation Example 17 13 Support for injecting Jersey s resources providers via ConstraintValidatorFactory shows how this can
146. HK2 how to bind your component Jersey will invoke this method multiple times once for each type that is registered with the actual application Every time the bind method is invoked your component provider needs to decide if it is taking control over the component or not In our case we know exactly which Java type we are interested in PerSessionResource class so the logic in our bind method is quite straightforward If we see our PerSessionResource class it is our turn to provide our custom binding for the class otherwise we just return false to make Jersey poll other providers and if no provider kicks in eventually provide the default HK2 binding for the component Please refer to the HK2 http hk2 java net documentation for the details of the concrete HK2 APIs used in the bind method implementation above The main idea behind the code is that we register a new HK2 Factory https hk2 java net apidocs org glassfish hk2 api Factory html PerSessionFactory to provide the PerSessionResource instances to HK2 The implementation of the PerSessionFactory is is also included above Please note that as opposed to a component provider implementation that should never itself rely on an injection support the factory bound by our component provider would get injected just fine since it is only instantiated later once the Jersey runtime for the application is fully initialized including the fully configured HK2 runtime Whenever a new session is se
147. Item i getItems get itemid if i null throw new CustomNotFoundException 4 5 6 7 8 return i 9 String itemid Ttem 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 85 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 ard 6 7 8 public CustomNotFoundException super Responses notFound build 9 10 EA 11 Create a HTTP 404 Not Found exception 12 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 m
148. Jersey 2 10 User Guide Jersey 2 10 User Guide Table of Contents Preface 20s sotnedesacstedss EE e a E a E act ogteaatia ses E E Ea paca teleatts T E gents xiv Te Getting Startede eher aerer Eee o EEEE E E E EEE EEE TEE E E S aTe 1 1 1 Creating a New Project from Maven Archetype cc cce ee ceceeecenecenece eee eeeeeeeeeeenees 1 1 2 Exploring the Newly Created Project 00 ceeec cece eeeceeeceeeceeeeaeeeaeeaeeeueeenneennees 1 1 3 Running the Project sscc s cssccasdes cotecsas Sona ss tat se bos pate shee tana se ee ds etesag E teats as Verte 3 1 4 Creating a JavaEE Web Application 20 0 0 cece ceec ence cece cena ceneeeneeeneeeeeeeeeeeeeeaees 5 1 5 Creating a Web Application that can be deployed on Heroku 0 eee cence eee 6 15 12 Deploy it on Heeroksen nener erone ons E EAN EEE EEE E E 8 1 6 Exploring Other Jersey Examples sier pssrerssereotiisn rnein n ne a e eas 11 2 Modules and dependencies sinsir ene ig eos TE E Oi N ETE E E S E 12 2 1 Java SE Compatibility seeen seereis nad orse EEEn ods STEERS EREE beosesdaseriaadsstoees 12 2 2 Introduction to Jersey dependencies seessseeesseerssrsrrrterrrerssrerrsrrerrrreerrreerrerrsreee 12 2 3 Common Jersey Use Cases imer iieaeoe o E T E a E a T ai 12 2 3 1 Servlet based application on Glassfish 0c cece ceee cece nee ee eee eeneeneeeneeeneees 12 2 3 2 Servlet based server side application 0c ccs eeceee cece s
149. ML namespaces mapped into JSON cece ce eeceeeee nner eeees 113 8 22 JSON Array configuration for Jettison based mapped notation ec eeeeeeeeeeeeceeeeeee eee es 113 8 23 JSON expression with JSON arrays explicitly configured via Jersey ccseeeeeeeeeeeeee ees 113 8 24 JSON expression produced using badgerfish notation eee cece eee eeeee teen eenee 114 8 25 Context RESO LVEL lt ODJECEMAPPEL gt soricei ienr EEn EERE INE aS er EEES no EiS 115 8 26 Building client with Jettison JSON feature enabled 2 0 0 0 cece cceeeeceeececneeeeeeeeeneeceuneeeees 115 8 27 Creating JAX RS application with Jettison JSON feature enabled ceeceeeeeeeeeeeeeeeee 115 8 28 Simplest icase Of using USONP srini en e dev geet devas eu e Eae ete ser eden daragsbanen ss 116 8 29 JaxbBean for JSONP example ec e ec eee cece cee e ce eece seca ceca cena eeae eens eeneeeeeeeeeeeeees 116 8 30 Example of JSONP with configured parameters ccceeceeeeeeeeececeeeeeueeeeeeceaueeeeneees 117 8 31 Low level XML test methods added to He LLoWorldREsource Java eeeeeeeeeeeesee tenner 118 8 32 Planet Class c 3s socteoeh tne dh cence sects ce doe t a duce hasten sae en ay cota me Moh E E a dards weakeeaceed sade besrentaes 119 8 33 Resource Class cisosoet EEE nena ye a E O E E E tee veceuveaver a areas AEE 119 8 34 Method for consuming Planet passieren s oeiee eoan a En s E e E ESEE SI VEES 120 8 35
150. NP 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 you ll 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 queryParanm value if set always takes precedence over callback value 116 Support for Common Media Type Representations Lets modify our example a little bit Example 8 30 Example of JSONP with configured parameters GET Produces application json application javascript JSONP callback eval queryParam js
151. N_IGNORE_ERRORSJe Psteumaws v athethet i validatrony of application resource models should fail even in case of a fatal validation errors Default value is ServerProperties WADL_FEATU https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html WADL_FE REBAR fig server wa EATURE_ DISABLE Disatlesab WA AL generation Default value is false ServerProperties WADL_GENERA FORe CONFIGI g server waDefigeme thet o math f igenerator https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html W ADL_GENERATOR_CONFIG configuration that provides a Wad1IGenerator https jersey java net apidocs 2 10 jersey org glassfish jersey server wadl Wad1 Generator html ServerProperties RESPONSE_SE https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html RESPONS IE_SET_STATUS_OVER_SEND T STARUS OVER SENDe ERRORhene ver s atesponse s Gtasuss cis 4xx or 5xx it is possible to choose between sendError or set Status on container specific IERROR se implementation E g on servlet container Jersey can call HttpServletResponse set or HttpServletResponse sen Calling sendError method usually resets entity response headers and provide error page for specified status 292 op Sets i ther recnasnoni nstratesyu fori ve eErrors Error tatus
152. Note Simple framework HTTP container does not support deployment on context paths other than root path Non root context path is ignored during deployment 4 5 1 4 Jetty HTTP Server Jetty is a popular Servlet container and HTTP server We will not look into Jetty s capabilities as a Servlet container although we are using it in our tests and examples because there is nothing specific to Jetty when using a Servlet based deployment model which is extensively described later in our Section 4 7 Servlet based Deployment section We will here only focus on describing how to use Jetty s HTTP server Jetty HTTP container supports injection of Jetty specific org eclipse jetty server Request and org eclipse jetty server Response instances into JAX RS and Jersey application resources and providers However since Jetty HTTP Request is not proxiable the injection of Jetty Request into singleton by default JAX RS Jersey providers is only possible via javax inject Provider instance Jetty Response does not suffer the same restriction Example 4 8 Using Jersey with Jetty HTTP Server 1 URI baseUri UriBuilder fromUri http localhost port 9998 build 2 ResourceConfig config new ResourceConfig MyResource class 3 Server server JettyHttpContainerFactory createServer baseUri config And of course we add the necessary container extension module dependency 1 lt dependency gt 2 lt groupid gt or
153. 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 e 400 Bad Request Otherwise 17 7 1 ValidationError By default during mapping ConstraintViolationExceptions Jersey doesn t return any entities that would include validation errors to the client This default behaviour could be changed 208 Bean Validation Support by enabling ServerProperties BV_SEND_ERROR_IN_RESPONSE https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html B V_SEND_ERROR_IN_RESPONSE property in your application Example 17 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 https jersey java net apidocs 2 10 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 e text plain e text html application xml applicat
154. POJO based JSON binding support e JAXB based JSON binding support e 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 use the same Java model to generate JSON as well 102 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
155. Providers provider bundle dependencies html jersey test framework provider external https jersey java net project info 2 10 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 10 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 10 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 10 jersey project project jersey test framework provider jdk http dependencies html Jersey Test Framework JDK HTTP container jersey test framework provider jetty https jersey java net project info 2 10 jersey project project jersey test framework provider jetty dependencies html Jersey Test Framework Jetty HTTP container jersey test framework provider simple https jersey java net project info 2 10 jersey project project jersey test framework provider simple dependencies html Jersey Test Framework Simple HTTP container 20 Modules and dependencies Table 2 8 Jers
156. RI template that does not have all the template parameters properly resolved Any attempt to do so will fail with an exception Note that this also applies to any managed clients injected into JAX RS server side components using Uri https jersey java net apidocs 2 10 jersey org glassfish jersey server Uri html annotation In Jersey 2 6 and earlier producing a URI from an incompletely resolved URI template would succeed and all unresolved template parameter locations would be encoded without change into the resulting URI for example path param would be implicitly encoded as path 7Bparam 7D 275 Migration Guide While we do not expect our users to depend on this functionality if the former behavior is desired for some reason UriComponent encodeTemplateNames method can be used instead URI create UriComponent encodeTemplateNames UriBuilder fromUri path or simply URI create UriComponent encodeTemplateNames path param 25 5 Migrating from Jersey 2 5 1 to 2 6 25 5 1 Guava and ASM have been embedded Jersey no longer depend directly on Guava and ASM artifacts which means that users are free to use their own versions of mentioned libraries New bundle has been created for Guava bundles repackaged jersey guava with Maven coordinates org glassfish jersey bundles repackaged jersey guava Repackaged ASM is now part of Jersey Server Jersey currently uses ASM 5 for package scanning ca
157. RequestRate requestsPerSeconds 1s 1 0 v MethodTimes RequestRate requestsPerSeconds total _ 0 620271946680937 gt RequestTimes gt OPTIONS gt GenericOptionsinflector apply Object a6707a1e gt OPTIONS gt OptionsHandler apply Object 1020dad0 gt gt OPTIONS gt PlainTextOptionsinflector apply Object e71c36d7 POST gt TestResource testPost e5a93a2a gt resource exception gt resource locator gt resource sub gt resource sub2 gt sub resource gt sub2 resource Refresh S pid 4599 com intellij rt execution application AppMain com intellij rt execution junit JUni Under the root org glassfish jersey Jersey MBean group you can find your application If the server contains more Jersey application all will be present under the root Jersey the group In the screen shot the deployed JAX RS application is named myApplication the name can be defined via ResourceConfig https jersey java net apidocs 2 1 O jersey org glassfish jersey server ResourceConfig html directly or by setting the ServerProperties APPLICATION NAME https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html APPLICATION_NAME property Each application contains Global Resource and Uris sub groups The Global group contains all global statistics like overall requests statistics of the entire application AllRequestTimes c
158. Resource Selection eee cece eect eee eeeeeeeneeeenees 176 15 2 Injecting SecurityContext into a singleton resource 0 0 0 eee eee cee cence ee ceeeee teenies 176 15 3 Securing resources using Web XM oo ec eee cere e cee T AE EE eens EORI 178 15 4 Registering RolesAllowedDynamicFeature using ResourceConfig cece ee cece eee e tees 178 15 5 Registering RolesAllowedDynamicFeature by extending ResourceConfig c eee 179 15 6 Applying javax annotation security to JAX RS resource methods 06 179 15 7 Build the authorization flow utility 20 0 ec ce cece cc eeceeeeeeeceeeeeeesaeeeaeeeaeeea sean eeaes 183 xi Jersey 2 10 User Guide 15 8 Perform the OAuth Authorization FlOW 20 00 00 cece ece cece eece ence ence eeceeeceeeeaeeea sees eens eeae esas 183 15 9 Authenticated requests n eren a ete ote Sin Raed a aaag a E ge aa cl Rabie tiara soe ae ey 184 15 10 Build feature from Access Token nimesen anna ee ae et a eee 184 15 11 Specifying Access Token on a Request e sseesisseesseresrrerrsrrerrrrerrrrrerreresrrerrerrerreeen 185 15 12 Creating Public Private RSA SHA1 keys 2 0 0 0 eee ee cee ceeeceeece seca eeea sean eeu eeneeeeeees 185 15 13 Building OAuth 2 Authorization FlOW 2 0 0 0 cece cece eee cee ce eeceeeceeeceeesaeeeaeeea essa sean eeaes 187 16 1 A simple WADL example JAX RS resource definition 2 0 0 0 eee cece ce tece nsec teen e
159. SS 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 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 Creating a Web Application that can be deployed on Heroku To create a Web Application that can be either packaged as WAR and deployed in a Servlet container or that can be pushed and deployed on Heroku https www heroku com the process is very similar to the one described in Section 1 4 Creating a JavaEE Web Application 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 heroku webapp DarchetypeGrouplId org glassfish jersey archetypes DinteractiveMo Dgroupid com exampl DartifactId simple heroku webapp Dpackage DarchetypeVersion 2 10 Adjust the groupId package and or artifact Id of your new web application project to your needs or alternatively you can change it by updating the new project pom xm1 once it gets generated Getting Star
160. 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 class CompressionDynamicBinding implements DynamicFeature 28 29 Override 30 public void configure ResourceInfo resourceInfo FeatureContext context 31 if HelloWorldResource class equals resourceInfo getResourceClass 32 amp amp resourceInfo getResourceMethod 33 getName contains VeryLongString 34 context register GZIPWriterInterceptor class 35 36 37 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 ResourcelInfo 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
161. TURE_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html B V_FEATURE_DISABLE Note Jersey does not support Bean Validation on the client at the moment 17 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 https jersey java net apidocs 2 10 jersey org glassfish jersey server validation ValidationConfig 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_VALIDRsAbIEs GN cEXREUPABLIe OVERR I DikecKHMOkKe on this is https jersey java net described in Section 17 5 ValidateOnExecution apidocs 2 10 jersey org glassfish jersey server ServerProperties html B V_DISABLE_VALIDATE_ON_EXECUTABLE_OVERRIDE_ CHECK ServerProperties BV_SEND_ERROR HiibRis SPONSE validation errors in response entity to the client https jersey java net More on this in Section 17 7 1 ValidationError apidocs 2 10 jersey org glassfish jersey server ServerProperties html B V_SEND_ERROR_IN_RESPONSE Example 17 1 Configuring Jersey specific prop
162. Token html ConsumerCredentials https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth1 ConsumerCredentials html Interfaces that define Access Token classes and Consumer Credentials Interfaces contains getters for public keys and secret keys of token and credentials An example of how Jersey OAuth 1 client API is used can be found in the OAuth 1 Twitter Client example https github com jersey jersey tree 2 10 examples oauth client twitter The following code snippets are extracted from the example and explain how to use the Jersey OAuth client API Before we start with any interaction with Twitter we need to register our application on the Twitter See the example README TXT file for the instructions As a result of the registration we get the consumer credentials that identify our application Consumer credentials consist of consumer key and consumer secret As a first step in our code we need to perform the authorization flow where the user grants us an access to his her Twitter client Example 15 7 Build the authorization flow utility 1 ConsumerCredentials consumerCredentials new ConsumerCredentials 2 a846d84e68421b321a32d fl3aed84190bc 3 OAuthlAuthorizationFlow authFlow OAuthiClientSupport builder consumerCredent 4 authorizationF low 5 http api twitter com oauth request_token 6 http api twitter com oauth access_token 7 http api twitter com oauth authorize 8
163. With OAuth a resource owner Adam grants an access to a consumer HelloWorldWeb without giving the web his password This access grant achieved by a procedure called authorization flow Authorization flow is out of the scope of this documentation and it s description can be found in the OAuth specification linked above The result of the authorization flow is an Access Token which is later used by consumer to authenticate against service provider While this brief description applies to both OAuth 1 and 2 note that there are some differences in details between these two specifications Jersey OAuth is currently currently supported for the following use cases and OAuth versions 180 Security e OAuth 1 Client consumer and server service provider e OAuth 2 Client consumer With client and server support there are two supported scenarios e Authorization flow e Authentication with Access Token support for authenticated requests 15 3 1 OAuth 1 OAuth 1 protocol is based on message signatures that are calculated using specific signature methods Signatures are quite complex and therefore are implemented in a separate module The OAuth 1 Jersey modules are groupId artifactId description e org glassfish jersey security oauthl client provides client OAuth 1 support for authorization flow and Authentication e org glassfish jersey security oauthl server provides server OAuth 1 support for authorization flow SPI for Token
164. _FEATURE_DISABLE _ https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html JSON_PROCESSING_FEATURE_DISABLE ClientProperties JSON_PROCESSING_FEATURE_DISABLE _ https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html JSON_PROCESSING_FEATURE_DISABLE 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 JSON P you can simply add values for supported properties 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 108 Support for Common Media Type Representations Example 8 12 Building client with JSON Processing JSON feature enabled ClientBuilder newClient new ClientConfig The line below that registers JSON Processing feature can be omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled register JsonProcessingFeature class property JsonGenerator PRETTY_PRINTING true i Example 8 13 Creating JAX RS application with JSON Processing JSON feature enabled Create JAX RS application final Application ap
165. a 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 T7 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 VAS aR 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 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 87 Representations and Responses core Request html evaluatePreconditions javax ws rs core EntityTag returns null and the normal response can be returned Notice that
166. ables usage of Jersey monitoring statistics provided that the statistic feature is turned on in CDI environment where injection is the only mean to get access to monitoring data Since both CDI and HK2 use the same injection annotation Jersey could get confused in certain cases which could lead to nasty runtime issues The get better control over what Jersey evaluates as HK2 injection end users could take advantage of newly introduced Hk2CustomBoundTypesProvider https jersey java net apidocs 2 10 jersey org glassfish jersey gf cdi spi Hk2CustomBoundTypesProvider html SPI Please see the linked javadoc to get detailed information on how to use the SPI in your application 4 8 4 2 Oracle WebLogic Server WebLogic currently supports JAX RS 1 1 JSR 311 http jcp org en jsr detail id 311 out of the box with Jersey 1 x To use more recent version with WebLogic please follow this guide http docs oracle com middleware 1212 wls RESTF version restful service htm 4 8 4 3 Other Application Servers Third party Java EE application servers usually ship with a JAX RS implementation If you want to use Jersey instead of the default JAX RS provider you need to add Jersey libraries to your classpath and disable the default JAX RS provider in the container In general Jersey will be deployed as a Servlet and the resources can be deployed in various ways as described in this section However the exact steps will vary from vendor to vend
167. ach message is received with a delay of one second Note If you have worked with streams in JAX RS you may wonder what is the difference between ChunkedOutput https jersey java net apidocs 2 10 jersey org glassfish jersey server ChunkedOutput html and StreamingOutput http jax rs spec java net nonav 2 0 apidocs javax ws rs core StreamingOutput html ChunkedOutput is Jersey specific API It lets you send chunks of data without closing the client connection using series of convenient calls to ChunkedOutput write methods that take POJO chunk media type as an input and then use the configured JAX RS MessageBodyWriter lt T gt providers to figure out the proper way of serializing each chunk POJO to bytes Additionally ChunkedOutput writes can be invoked multiple times on the same outbound response connection i e individual chunks are written in each write not the full response entity StreamingOutput is on the other hand a low level JAX RS API that works with bytes directly You have to implement StreamingOutput interface yourself Also its write OutputStream method will be invoked by JAX RS runtime only once per response and the call to this method is blocking i e the method is expected to write the entire entity body before returning 14 4 2 Broadcasting with Jersey SSE Jersey SSE server API defines SseBroadcaster https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseBroadcaster html which all
168. acts information from the cookies declared in cookie related HTTP headers FormParam _ http jax rs spec java net nonav 2 0 apidocs javax ws rs FormParam html is slightly special because it extracts information from a request representation that is of the MIME media type application x www form urlencoded and conforms to the encoding specified by HTML forms as described here This parameter is very useful for extracting information that is POSTed by HTML forms for example the following extracts the form parameter named name from the POSTed form data Example 3 10 Processing POSTed HTML form 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 j MultivaluedMap lt String String gt pathParams ui getPathParameters j Ope 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 gt headerParams hh getRequestHeaders Map lt String Coo
169. al 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 lt String gt 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 appe7 i cation new ResourceConfig Validation register ValidationConfigurationContextResolver class Further configuration t register Ng ode snippet has been taken from Bean Validation example https github com jersey jersey tree 2 10 examples bean validation webapp 201 Bean Validation Support 17 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 followin
170. ameter Example 4 13 Configuring Jersey container Servlet or Filter to use a list of classes 1 lt init param gt 2 lt param name gt jersey config server provider classnames lt param name gt 3 lt param value gt 4 org foo myresources MyDogResource 5 org bar otherresources MyCatResource 6 lt param value gt 7 lt init param gt Note All of the techniques that have been described in this section also apply to Servlet containers that support Servlet API 3 0 and later specification Newer Servlet specifications only give you additional features deployment options and more flexibility 4 7 2 Serviet 3 x Container 4 7 2 1 Descriptor less deployment There are multiple deployment options in the Servlet 3 0 container for a JAX RS application defined by implementing a custom Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html subclass For simple deployments no web xml is necessary at all Instead an ApplicationPath http jax rs spec java net nonav 2 0 apidocs javax ws rs A pplicationPath html annotation can be used to annotate the custom Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html subclass and define the base application URI for all JAX RS resources configured in the application Example 4 14 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 1 ApplicationPath resources 2 public class MyApplic
171. ample 14 2 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 172 Server Sent Events SSE Support initialized with SseFeature https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseFeature html Then the 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 Builder https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventSource Builder html instance that is used to build a new EventSource The choice of build method is important as it tells the EventSource Builder to create a new EventSource that is not automatically connected to the target The connection is established only later by manually invoking the eventSource open method A custom EventListener https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventListener html implementation is used to listen to and process incoming SSE events The method readData Class says that the event data should be de serialized from a received InboundEvent https jersey java net apidocs 2 10 jersey org glassfish jersey media sse InboundEvent html instance into a String Java type This method call internally execut
172. an be passed to the ClLientBuilder 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 DB WN FP 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 https jersey java net apidocs 2 10 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 Client register method supports the fluent API style multiple client instance configuration calls can be chained 1 client register FilterA class 2 register
173. and HeaderParam http jax rs spec java net nonav 2 0 apidocs javax ws rs 38 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 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 0 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 bean
174. and configuration of the provided feature by the end users For example MoxyJsonFeature https jersey java net apidocs 2 10 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 HttpUrlConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnector html that implements Jersey specific Connector https jersey java net apidocs 2 10 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 HttpUrlConnection based transport layer Jersey provides several alternative client transport connector implementations that are ready to use You can use ApacheConnectorProvider _ https jersey java net apidocs 2 10 jersey org glassfish jersey apache connector ApacheConnectorProvider html add a maven dependency to org glassfish jersey connectors jersey apach connector or GrizzlyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey grizzly connector GrizzlyConnectorProvider html add a maven dependency to org glassfish jersey connectors jersey grizzly connector or JettyConnectorProvider https jersey java net
175. 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 lt Context PerRequestType gt Override public Injectable lt PerRequestType gt getInjectable ComponentContext ic C LA es H Jersey 2 0 HK2 Module public static class MyBinder extends AbstractBinder Override protected void configure request scope binding 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 construc
176. api javax xml bind 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 XmlRootElement name yourName Our resource class will respond to GET planet with lt xml version 1 0 encoding UTF 8 standalone yes gt lt planet gt lt id gt 1 lt id gt lt name gt Earth lt name gt lt radius gt 1 0 lt radius gt lt planet gt which might be exactly what we want or not Or we might not really care because we can use 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 119 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 34 Method for consuming Planet 1 POST 2 Consumes MediaType APPLICATION_XML 3 pub
177. apidocs 2 10 jersey org glassfish jersey jetty connector JettyConnectorProvider html add a maven dependency to org glassfish jersey connectors jersey jetty connector alternatively Warning Be aware of using other than default Connector implementation There is an issue handling HTTP headers in WriterInterceptor or MessageBodyWriter lt T gt If you need to change header fields do not use nor ApacheConnectorProvider nor GrizzlyConnectorProvider neither JettyConnectorProvider The issue for example applies to Jersey Multipart feature that also modifies HTTP headers On the other hand in the default transport connector there are some restrictions on the headers that can be sent in the default configuration HttpUr1lConnectorProvider uses HttpUrlConnectionas an underlying connection implementation This JDK class by default restricts the use of following headers e Access Control Request Headers e Access Control Request Method Connection with one exception Connection header with value Closed is allowed by default e Content Length 77 Client API e Content Transfer Encoding e Host e Keep Alive e Origin e Trailer e Transfer Encoding e Upgrade e Via e all the headers starting with Sec The underlying connection can be configured to permit all headers to be sent however this behaviour can be changed only by setting the system property sun net http allowRestrictedHead
178. apter 17 Bean Validation Support 17 1 17 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 lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey bean validation lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt Note If you re not using Maven make sure to have also all the transitive dependencies see jersey bean validation https jersey java net project info 2 10 jersey project jersey bean 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
179. ass lt gt gt providerContracts if component PerSessionResource class 258 Custom Injection and Lifecycle Management final DynamicConfigurationService dynamicConfigService locator getService DynamicConfigurationService class final DynamicConfiguration dynamicConfiguration dynamicConfigService createDynamicConfiguration BindingBuilderFactory addBinding BindingBuilderFactory newFactoryBinder PerSessionFacto to PerSessionResource class dynamicConfiguration dynamicConfiguration commit return true return false Override public void done The first and very important aspect of writing your own ComponentProvider in Jersey is to store the actual HK2 ServiceLocator https hk2 java net apidocs org glassfish hk2 api ServiceLocator html instance that will be passed to you as the only argument of the provider initialize method Your component provider instance will not get injected at all so this is more less your only chance to get access to the HK2 runtime of your application Please bear in mind that at the time when your component provider methods get invoked the ServiceLocator is not fully configured yet This limitation applies to all component provider methods as the main goal of any component provider is to take part in configuring the application s ServiceLocator Now let s examine the bind method which is where your provider tells the
180. asynchronous invocation callback can be registered as shown in the following example 147 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 lt Response gt 3 Override 4 public 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 p 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
181. at 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 159 Programmatic API for Building Resources Example 13 3 A programmatic resource 1 2 ae 3 lt servlet gt 4 lt servlet name gt org glassfish jersey examples hellow 5 lt servlet class gt org glassfish jersey servlet SsServl 6 lt init param gt 7 lt param name gt javax ws rs Application lt param nam 8 lt param value gt org glassfish jersey examples hel 9 lt init param gt 10 lt load on startup gt 1 lt load on startup gt TI lt servlet gt 12 lt servlet mapping gt 13 lt servlet name gt org glassfish jersey examples hellow 14 lt url pattern gt lt url pattern gt 15 lt servlet mapping gt 16 de If you use another deployment options and you have accessible instance of ResourceConfig which you use for configuration you can register programmatic resources directly by registerResources method called on the ResourceConfig Please note that the method registerResources replaces all the previously registered resources Because Jersey programmatic API is not a standard JAX RS feature the ResourceConfig must be used to register programmatic r
182. ated 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 to receive more messages it would have to send a new request to the server to initiate anew 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 168 Server Sent Events SSE Support vent message to client data Hello world 1 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 E
183. ately as the tracing events occur The default n ame of the tracing logger is prefixed org glassfish jersey tracing with a default suffix general This logger name can be customized per request by including a X Uersey Tracing Logger will be shown later 20 2 3 Configuring tracing support via HTTP headers HTTP request header as request Whenever the tracing support is active ON_DEMAND or ALL you can customize the tracing behaviour by including one or more of the following request HTTP headers in your individual requests e X Jersey Tracing Accept used to enable the tracing support for the particular request It is EMAND mode The value applied only when the application level tracing support is configured to ON_D of the header is not used by the Jersey tracing facility and as such it can be any arbitrary even empty string e X Jersey Tracing Threshold used to override the tracing level of detail Allowed values are SUMMARY TRACE VERBOSE e X Jersey Tracing Logger used to override the tracing Java logger name suffix 20 2 4 Format of the HTTP response headers At the end of request processing all tracing messages are appended to the HTTP response as individual headers named X Jersey Tracing nnn where nnn is index number of me ssage starting at 0 Each tracing message is in the following format CATEGORY TIME TEXT e g X Jersey Tracing 007 WI 85 95 18
184. atically Example 4 12 Configuring Jersey container Servlet or Filter to use package scanning lt init param gt lt param name gt jersey config server provider packages lt param name gt lt param value gt org foo myresources org bar otherresources lt param value gt lt init param gt lt init param gt lt param value gt false lt param value gt lt init param gt COO WMWAATA UO BWN EF ny Jersey will automatically discover the resources and providers in the selected packages You can also decide whether Jersey should recursively scan also sub packages by setting the jersey config server provider scanning recursive property The default value is true ie the recursive scanning of sub packages is enabled 4 7 1 3 Selecting concrete resource and provider classes While the above mentioned package scanning is useful esp for development and testing you may want to have a little bit more control when it comes to production deployment in terms of being able to enumerate specific resource and provider classes In Jersey it is possible to achieve this even without a need to implement a custom Application subclass The specific 57 lt param name gt jersey config server provider scanning recursive lt param name gt Application Deployment and Runtime Environments resource and provider fully qualified class names can be provided in a comma separated value of jersey config server provider classnames initialization par
185. ation deployment For example for a Jersey application deployed in a Servlet container the Jersey SecurityContext will encapsulate information from a security context retrieved from the Servlet request In case of a Jersey application 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 based on the specific roles a user principal is included in For example a sub resource locator could return a different resource if a user is a preferred customer Example 15 1 Using SecurityContext for a Resource Selection 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 is inherently request scoped yet can be also injected into fields of singleton resources and JAX RS providers In such case the proxy of the request scoped SecurityContext will be injected Example 15 2 Injecting SecurityContext into a singleton resource 1 Path resource 2 Singleton 3 public static class MyResource 4 Jersey will inject proxy of Security Context 5 Context 6 SecurityContext securityContext 7 8 GET 9 public String getUserPrincipal 10 return securityContext getUserP
186. ation extends ResourceConfig 3 public MyApplication packages org foo rest org bar rest Does Note There are many other convenience methods in the ResourceConfig that can be used in the constructor of your custom subclass to configure your JAX RS application see ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html API documentation for more details In case you are not providing web xml deployment descriptor for your maven based web application project you need to configure your maven war plugin to ignore the missing web xml file by setting failOnMissingWebXml http maven apache org plugins maven war plugin war mojo html failOnMissingWebXml configuration property to false in your project pom xml file 58 Application Deployment and Runtime Environments Example 4 15 Configuration of maven war plugin to ignore missing web xml 1 lt plugins gt 2 oes 3 lt plugin gt 4 lt groupId gt org apache maven plugins lt grouplId gt 5 lt artifactId gt maven war plugin lt artifactId gt 6 lt version gt 2 3 lt version gt 7 lt configuration gt 8 lt failOnMissingWebXml gt false lt failOnMissingWebXml gt 9 lt configuration gt 10 lt plugin gt 11 ENE 12 lt plugins gt 4 7 2 2 Deployment using web xm1 descriptor Another Servlet 3 x container deployment model is to declare the JAX RS application details in the web xml This is typicall
187. ation 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 ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html Jersey s own implementations of Application class This class can either be directly instantiated and then configured or it can be extended and the configuration code placed into the constructor of the extending class The approach typically depends on the chosen deployment runtime Compared to Application the ResourceConfig provides advanced capabilities to simplify registration of JAX RS components such as scanning for root resource and provider classes in a provided classpath or a in a set of package names etc All JAX RS component classes that are either manually registered or found during scanning are automatically added to the set of classes that are returned by getClasses For example the following application class that extends from ResourceConfig scans during deployment for JAX RS components
188. ava net nonav 2 0 apidocs javax ws rs ext Provider htm annotation packaged with the application will be automatically registered in the JAX RS application The web application has to be packaged with a deployment descriptor specifying at least the mapping for the added javax ws rs core Application Servlet Example 4 17 web xml of a JAX RS application without an Application subclass 1 lt web app version 3 0 2 xmlins http java sun com xml ns javaee 3 xmlns xsi http www w3 org 2001 XMLSchema instance gt 4 5 lt Servlet declaration can be omitted in which case 6 it would be automatically added by Jersey gt 7 lt servlet gt 8 lt servlet name gt javax ws rs core Application lt servlet name gt 9 lt servlet gt 10 11 lt servlet mapping gt 12 lt servlet name gt javax ws rs core Application lt servlet name gt 13 lt url pattern gt myresources lt url pattern gt 14 lt servlet mapping gt 15 lt web app gt 4 7 2 3 2 JAX RS application with a custom Application subclass When a custom Application subclass is provided in such case the Jersey server runtime behavior depends od whether or not there is a Servlet defined to handle the application subclass If the web xml contains a Servlet definition that has an initialization parameter jJavax ws rs Application whose value is the fully qualified name of the Application subclass Jersey does not perform any additional steps in such case
189. ay 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 http jax rs spec java net nonav 2 0 apidocs javax ws rs ext Provider html this declares that the class is of interest to the JAX RS runtime Such a class may be added to the set of classes of the Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html instance that is 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 excep
190. been introduced to provide access to the raw SSE event data content Generic Broadcaster https jersey java net apidocs 2 10 jersey org glassfish jersey server Broadcaster html methods for adding removing BroadcasterListener https jersey java net apidocs 2 10 jersey org glassfish jersey server BroadcasterListener html registrations have been renamed from addBroadcasterListener removeBroadcasterListener to simply add remove Generic Broadcaster https jersey java net apidocs 2 10 jersey org glassfish jersey server Broadcaster html and transitively SseBroadcaster https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseBroadcaster html add remove methods that are responsible for adding removing BroadcasterListener https jersey java net apidocs 2 10 jersey org glassfish jersey server BroadcasterListener html and ChunkedOutput https jersey java net apidocs 2 10 jersey org glassfish jersey server ChunkedOutput html or EventOutput https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventOutput html registrations no longer try to avoid duplicate registrations by comparing hash code of the added removed instance with the hash codes of already registered instances This behavior has been identified as a potential source of hard to discover bugs and was removed as such The issue with the former behavior was that hash codes as integer values provide only a very limited value spa
191. blic class Foo GET public Viewable get return new Viewable index foo FOO In this example the Foo JAX RS resource class is the controller and the Viewable instance encapsulates the provided data model FOO string and a named reference to the associated view template index foo Tip All HTTP methods may return Viewab1e instances Thus a POST method may return a template reference to a template that produces a view as a result of processing an HTML Form http jax rs spec java net nonav 2 0 apidocs javax ws rs core Form html 226 MVC Templates 19 2 Template 19 2 1 Annotating Resource methods There is no need to use Viewable every time you want to bind a model to a template To make the resource method more readable and to avoid verbose wrapping of a template reference and model into Viewable you can simply annotate a resource method with Template https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Template html annotation An updated example using Template from previous section is shown in Example 19 2 Using Template on a resource method example Example 19 2 Using Template on a resource method package com example Path foo public class Foo GET Template index foo public String get return FOO In this example the Foo JAX RS resource class is still the controller as in previous section but the MVC m
192. 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 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 144 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
193. ce class allows you to count the number of requests made within a single client session and provides you a handy sub resource method to obtain the number via a HTTP GET method call Path session public class PerSessionResource 256 Custom Injection and Lifecycle Management SessionInject HttpSession httpSession AtomicInteger counter new AtomicInteger GET Path id public String getSession counter incrementAndGet return httpSession getId GET Path count public int getSessionRequestCount return counter incrementAndGet Should the above resource be per request scoped default option you would never be able to obtain any other number but 1 from it s getReqs sub resource method because then for each request a new instance of our PerSessionResource class would get created with a fresh instance counter field set to 0 The value of this field would get incremented to in the the get SessionRequestCount method before this value is returned In order to achieve what we want we have to find a way how to bind the instances of our PerSessionResource class to HttpSession instances and then reuse those bound instances whenever new request bound to the same HTTP client session arrives Let s see how to achieve this To get better control over your Jersey component instantiation and life cycle you need to implement a custom Jersey ComponentProvider https jersey java net apidocs 2
194. ce that could lead to false positive duplicate registration rejections especially with larger number of simultaneously connected SSE clients represented by ChunkedOut put or Event Output broadcaster registrations Consequently users who rely on the old registration behavior in their application code need to adapt the code to the revised behavior of Broadcaster add remove methods 25 11 Migrating from Jersey 1 x to 2 0 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 incompatibilities between Jersey 1 x and Jersey 2 0 This chapter summarizes how to migrate the concepts found in Jersey 1 x to Jersey JAX RS 2 0 concepts 25 11 1 Server API Jersey 1 x contains number of proprietary server APIs This section covers migration of application code relying on those APIs 280 Migration Guide 25 11 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
195. cence eee eeeeeeeeeeeeeeeaees 13 2 3 3 Client application on JDK 0 0 eee cece ce eecceeceeeceeeeaeeeaeeeaeeae sean eens eegs 13 2 3 4 Server side application on supported containers cece eee ee ee ee eee ence eeeeeees 14 2A List of MOMMIES ss 5550800 3 Ani a st ec E E Eo Libs wes ies URN hotel ete eS A ast 15 3 JAX RS Application Resources and Sub Resources 2 0 2 0 cece cece eeee cece ce eeneceneceneceneeeeeeeeees 31 3 1 Root Resource Classes orres eenst neoion Ba igecdea ee eucawe sien gusta oven E REEERE IS KETE 31 3AT Pafe an e nates E E E a E cates E EE 31 3 1 2 GET PUT POST DELETE HTTP Methods seeeceeeeeeene 32 3 1 3 PrOdUCES ieies saeka EEE POE sca ESEESE EA TESEO ESEESE ROSEE EPOS E E 33 3 L4 CONSUMES ne ee eea be es EE EE eee NTE 34 3 2 Parameter Annotations Param cccceceec ee ee cee ee cence ee ee eens ece ease eeneeeeneeeeneenee 35 3 3 SUD TESOULCES eree aa E EE a VAE EEOAE EESAN odes ene eset lies 39 3 4 Life cycle of Root Resource Classes 2 0 0 0 cece cece eece reret e rrp Ture Earias SE aiD 43 3 5 RULES OL Injection 232546 sock vial eee teste e agg edbs AOT EE EEE EAEE KES eE EEEE EEE ap edec ont 44 3 0 Use of CONTE Le rreri ca yertells senig Sea vias cateaca bat ahes E a aa i aa dag ates 47 3 7 Programmatic resource model eee cee cece cece cece cece cece nace ne eeneeeeeeeeeeeeeeeeeeaeeeaeeeaes 48 4 Application Deployment and Runtime Environments
196. cept 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 following useful client side filters and features registering filters that you may want to use in your applications CsrfProtectionFilter https jersey java net apidocs 2 1 0 jersey org glassfish jersey client filter CsrfProtectionFilter html Cross site request forgery protection filter adds xX Requested By to each state changing request EncodingFeature https jersey java net apidocs 2 10 jersey org glassfish jersey client filter EncodingFeature html Feature that registers encoding filter which use registered ContentEncoder https jersey java net apidocs 2 10 jersey org glassfish jersey 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 https jersey java net apidocs 2 10 jersey org glassfish jersey client filter EncodingFeature html in order to use it HttpAuthenticationFeature https jersey java net apidocs 2 10 jersey org glassfish jersey client authentication HttpAuthenticationFeature html HTTP Authentication Feature see below Note that these features are provided by J
197. configure Jersey resources 4 7 1 1 Custom Application subclass If you extend the Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html class to provide the list of relevant root resource classes get Resources and 56 Application Deployment and Runtime Environments singletons get Singletons i e your JAX RS application model you then need to register it in your web application web xm1 deployment descriptor using a Servlet or Servlet filter initialization parameter with a name of javax ws rs Application sic as follows Example 4 11 Configuring Jersey container Servlet or Filter to use custom Application subclass 1 lt init param gt 2 lt param name gt javax ws rs Application lt param name gt 3 lt param value gt org foo MyApplication lt param value gt 4 lt init param gt Jersey will consider all the classes returned by getResources and getSingletons methods of your Application implementation Note The name of the configuration property as defined by JAX RS specification is indeed javax ws rs Application and not javax ws rs core Application as one might expect 4 7 1 2 Jersey package scanning If there is no configuration properties to be set and deployed application consists only from resources and providers stored in particular packages you can instruct Jersey to scan these packages and register any found resources and providers autom
198. cs 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 xm1 file lt dependency gt lt grouplid gt org glassfish jersey media lt groupId gt lt artifactId gt jersey media json jettison lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt 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 10 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 notations serializes JSON in a different way Following is a list of supported notations e JETTISON_MAPPED default notation e 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 below 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 111 Support for Common Media Type Representations Example 8 17 JAXB beans for JSON supported notations description simple address bean 1 XmlRootElement 2 public class Address
199. ction extension in Jersey you must register your custom HK2 Binder https hk2 java net apidocs org glassfish hk2 utilities Binder html implementation in your application ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig htm Defining Custom Injection Annotation Java annotations are a convenient way for attaching metadata to various elements of Java code Sometimes you may even decide to combine the metadata with additional functionality such as ability to automatically inject the instances based on the annotation provided metadata The described scenario is one of the use cases where having means of defining a custom injection annotation in your Jersey application may prove to be useful Obviously this use case applies also to re used existing 3rd party annotation types In the following example we will describe how a custom injection annotation can be supported Let s start with defining a new custom SessionInject injection annotation that we will specifically use to inject instances of HttpSession http docs oracle com javaee 6 api javax servlet http HttpSession html similarly to the previous example Retention RetentionPolicy RUNTIME Target ElementType FIELD public interface SessionInject lt The above SessionInject annotation should be then used as follows Path di resource public class MyDiResource SessionInject HttpSession httpSession
200. ctly 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 13 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 th
201. d 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 resources 3 4 Life cycle of Root Resource Classes By default the life cycle of root resource classes is per request which namely that a new instance of a root resource class is created every time the request URI path matches the root resource This makes for a very natural programming model where constructors and fields can be utilized as in the previous section showing the constructor of the SoarklinesResource class without concern for multiple concurrent requests to the same resource In general this is unlikely to be a cause of performance issues Class construction and garbage collection of JVMs has vastly improved over the years and many objects will be created and discarded to serve and process the HTTP request and return the HTTP response Instances of singleton root resource classes can be declared by an instance of Application http jax rs spec java net nonav 2 0 apidocs
202. d transfer coding selection please utilize use the new ClientProperties REQUEST_ENTITY_PROCESSING https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html REQUEST_ENTITY_PROCESSING property The behaviour of the property is however not unified across the available Connector https jersey java net 277 Migration Guide apidocs 2 10 jersey org glassfish jersey client spi Connector html implementations and depends on the connector implementation configured for the Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html instance Default connector produced by HttpUrlConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnector html still uses buffering as default options due to bugs in HttpURLConnection On the other hand Jetty HTTP Client based connectors produced by JettyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey jetty connector JettyConnectorProvider html do not support chunked encoding at all Please note that this is not a newly introduced limitation it s merely an official acknowledgement of the fact that different connectors have different capabilities and limitations something that has always been part of the individual connector implementations it just was not publicly acknowledged New ConnectorProvider _ https jersey java net apidocs 2 10 jersey org glassfish jerse
203. dencies html Simple Http Container Table 2 3 Jersey Connectors Jersey Connectors jersey apache connector https jersey java net project info 2 10 jersey project jersey apache connector dependencies html Jersey Client Transport via Apache jersey grizzly connector https jersey java net project info 2 10 jersey project jersey grizzly connector dependencies html Jersey Client Transport via Grizzly jersey jetty connector https jersey java net project info 2 10 Jersey Client Transport via Jetty 16 Modules and dependencies Jersey Connectors jersey project jersey jetty connector dependencies html Table 2 4 Jersey Media Jersey Media html json https jersey java net project info 2 10 jersey project html json dependencies html jersey media json jackson https jersey java net project info 2 10 jersey project jersey media json jackson dependencies html JAX RS Reader Writer via net java html json library that provides JSON serialization and deserialization using lightweight no reflection net java html json library Define your objects via Model annotation Use them in Jersey Jersey JSON Jackson 2 x entity providers support module jersey media json jettison https jersey java net project info 2 10 jersey project jersey media json jettison dependencies html Jersey JSON Jettiso
204. description of all Jackson features is out of scope of this guide The example below 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 https jersey java net apidocs 2 10 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 109 Support for Common Media Type Representations Example 8 14 ContextResolver lt ObjectMapper gt 1 Provider 2 public class MyObjectMapperProvider 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 de T2 Override 13 public ObjectMapper getContext Class lt gt type 14 if type CombinedAnnotationBean class 15 return combinedObjectMapper 16 else 17 return defaultObjectMapper 18 19 20 21 private static ObjectMapper createDefaultMapper 22 final ObjectMapper result new ObjectMapper 23 result configure Feature INDENT_OUTPUT true 24 29 return result 26 27 28 29 Example 8 15 Building client with Jackso
205. details about client security please see theClient chapter Jersey client allows to define parameters of SSL communication using HTTPS protocol You can also use jersey built in authentication filters which perform HTTP Basic Authentication or HTTP Digest Authentication See the client chapter for more details 179 Security 15 3 OAuth Support OAuth is a specification that defines secure authentication model on behalf of another user Two versions of OAuth exists at the moment OAuth 1 defined by OAuth 1 0 specification http tools ietf org html rfc5849 and OAuth 2 defined by OAuth 2 0 specification http tools ietf org html rfc6749 OAuth 2 is the latest version and it is not backward compatible with OAuth 1 specification OAuth in general is widely used in popular social Web sites in order to grant access to a user account and associated resources for a third party consumer application The consumer then usually uses RESTful Web Services to access the user data The following example describes a use case of the OAuth similar for OAuth 1 and OAuth 2 The example is simple and probably obvious for many developers but introduces terms that are used in this documentation as well as in Jersey OAuth API documentation Three parties act in an OAuth scenario Adam 7 gt i Service i Provider Twitter Resource owner HelloWorldWeb Consume The first party represents a user in our case Adam who is called in the OA
206. dia 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 below 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 https jersey java net apidocs 2 10 jersey org glassfish jersey server ChunkedOutput html on the servers side and ChunkedInput https jersey java net apidocs 2 10 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 Out boundEvents Instead a new instance of EventOutput https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventOutput html is returned EventOutput is a typed extension of ChunkedOutput lt OutboundEvent gt Similarly to receive InboundEvents on a client side Jersey SSE API provides a EventInput that represents a typed extension of ChunkedInput lt InboundEvent gt The Jersey
207. dicate the absolute reference has not been resolved by the Freemarker template processor Thus the absolute template reference com foo Foo index would be resolved to com foo Foo index ftl provided there exists a com foo Foo index ft1 Freemarker template in the application Jersey will assign the model instance to an attribute named model So it is possible to reference the foo key from the provided Map MVC Model resource from the Freemarker template as follows lt h1 gt S model f00 lt h1 gt Available configuration properties e FreemarkerMvcFeature TEMPLATE BASE PATH jersey config server mvc templateBasepath freemarker The base path where Freemarker templates are located 233 MVC Templates e FreemarkerMvcFeature CACHE_ TEMPLATES jersey config server mvc caching freemarker Enables caching of Freemarker templates to avoid multiple compilation e FreemarkerMvcFeature TEMPLATE OBJECT_FACTORY jersey config server mvc factory freemarker Property used to pass user configured FreemarkerFactory e FreemarkerMvcFeature ENCODING jersey config server mvc encoding freemarker Property used to configure a default encoding that will be used if none is specified in Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation If property is not defined the UTF 8 encoding will be used as a default value Maven users can find this mo
208. dividual 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 Let s 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 73 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 anew 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 1 Invocation Builder invocationBuilder 2 helloworldWebTargetWithQueryParam request MediaType TEXT_PLAIN_TYP 3 invocationBuilder header
209. dows have different update intervals The shorter the time window the shorter the update interval This causes that immediately after the application start the shorter time windows such as 15 seconds may contain higher values than longer ones e g 1 hour time window The reason is that 1 hour interval will show information that is not up to date and therefore has smaller value This inconsistency is not so much significant when application is running longer time Total unlimited time windows contains always up to date data This inconsistency will get fixed in a future Jersey release MXBeans can be also accessed using JMX To do so you would need to use the interfaces of MXBeans These interfaces are even useful when working with MXBeans only trough JConsole as they contain Javadocs for each MXBean and attribute Monitoring MBeans are defined by following interfaces e ApplicationMXBean https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ApplicationMXBean html contains configuration statistics e ExceptionMapperMXBean https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ExceptionMapperMXBean html contains statistics of exception mappers e ResourceMethodMxXBean https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ResourceMethodMXBean html contains statistics of resource method e ResourceMXBean _ https jersey java net apidocs 2 10 jersey org
210. dule at coordinates lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey mvc freemarker lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt and for non Maven users the list of dependencies is available at jersey mvc freemarker https jersey java net project info 2 10 jersey project jersey mvc freemarker dependencies html 19 6 3 JSP An integration module for JSP based templating engine Limitations of Jersey JSP MVC Templates Jersey web applications that want to use JSP templating support should be registered as Servlet filters rather than Servlets in the application s web xm1 The web xm1 less deployment style introduced in Servlet 3 0 is not supported at the moment for web applications that require use of Jersey MVC templating support JSP template processor resolves absolute template references to processable template references represented as JSP pages as follows Procedure 19 3 Resolving JSP template reference 1 if the absolute template reference does not end in jsp append this suffix to the reference and 2 if ServletContext getResource returns a non null value for the reference then return the reference as the processable template reference otherwise return nu11 to indicate the absolute reference has not been resolved by the JSP template processor Thus the absolute template reference com foo0 Foo index would be resolved to com
211. e 900000 15min gt stats measured in last 15 minutes 244 Monitoring and Diagnostics e 3600000 lhour gt stats measured in last hour minutes All the time window statistics can be retrieved from a Map lt Long TimeWindowStatistics gt map returned from ExecutionStatistics getTimeWindowStatistics Key of the map is the number of milliseconds of interval so for example key 60000 points to statistics for last one minute Note that snapshot method was called in the example only on the top level MonitoringStatistics This produced a snapshot of the entire tree of statistics and therefore we do not need to call snapshot on TimeWindowStatistics again Statistics are injected using the Provider http docs oracle com javaee 6 api javax inject Provider html This is preferred way of injecting statistics The reason is simple Statistics might change over time and contract of MonitoringStatistics does not make any assumptions about mutability of monitoring statistics instances to allow future optimizations and changes in implementation strategy In order to get always latest statistics we recommend injecting a Provider http docs oracle com javaee 6 api javax inject Provider html rather than a direct reference and use it s get method to retrieve the latest statistics For example in singleton resources the use of the technique is very important otherwise statistics might correspond to the time when singleton was firs
212. e 4 401s INFO Finished at Mon Dec 09 20 19 06 CET 2013 INFO Final Memory 20M 246M INFO Now that you know everything went as expected you are ready to e make some changes in your project e take the packaged WAR located under target simple service webapp war and deploy it to a Servlet container of your choice or e Section 1 5 1 Deploy it on Heroku Tip If you want to make some changes to your application you can run the application locally by simply running mvn clean package jetty run which starts the embedded Jetty server or by java cp target classes target dependency com example heroku Main this is how Jetty is started on Heroku Deploy it on Heroku We won t go into details how to create an account on Heroku https www heroku com and setup the Heroku tools on your machine You can find a lot of information in this article Getting Started with Java on Heroku https devcenter heroku com articles getting started with java Instead we ll take a look at the steps needed after your environment is ready The first step is to create a Git repository from your project git init Initialized empty Git repository in simple heroku webapp git Then create a Heroku https www heroku com instance and add a remote reference to your Git repository heroku create Creating simple heroku webapp done stack is cedar http simple heroku webapp herokuapp com git heroku com simpl
213. e This change may affect 3rd party libraries e g Jackson 2 x in a way their provider would not be registered in an JAX RS app You need to either register them manually or use mentioned jersey metainf services module 25 2 1 4 Jersey Test Framework Jersey Test Framework now supports TestNG to run the tests in addition to the JUnit which is supported by default You can now run the tests in parallel using either JUnit or TestNG See chapters dedicated to TestNG and parallel testing for more information Section 23 3 Running TestNG Tests and Section 23 5 Parallel Testing with Jersey Test Framework 271 Migration Guide 25 2 2 Changes Some of the feature specific configuration properties disable WADL disable BV disable JSON Processing enable Monitoring and their server client counterparts are no longer affected by a value of properties CommonProperties FEATURE_AUTO_DISCOVERY_DISABLE or CommonProperties METAINF_SERVICES_LOOKUP_DISABLE The specific properties have to be used to change default behaviour of mentioned features e g ServerProperties WADL_FEATURE_DISABLE Automatic registration of MessageBodyWriter MessageBodyReaders and ExceptionMappers via META INF services mechanism has been removed Disabling the automatic registration of providers via META INF services may affect 3rd party libraries i e Jackson 2 x that are using this mechanism t
214. e ceeeceee cece ce eece cece een eeneeeeeceeeeeeeeeeeeaees 227 19 4 Using absolute path to template in Viewable oo ce cece ce ee ce eeceeeeeeeeeeeeeeeeaeeenes 229 19 5 Using ErrorTemplate on a resource method 2 0 0 0 eee eee cee ce eeceeece teen seca tenn cones 230 xii Jersey 2 10 User Guide 19 6 Using ErrorTemplate with Bean Validation 2 0 0 0 cece cece eece ence eeeeeeeeeeeeeeeeees 230 19 7 Iterating through ValidationError in JSP oo eee eee cece cece eeneeeneeeneeeeeeeeees 230 19 8 Registering MV GP Satur S renren ch dau E a E tess eels pau entrees hea dun eieds sons 231 19 9 Registering FreemarkerMVvCFEatuLe oo cceeceeeceeecseec eee eeeceneceeeeseeceeeeeeeseeseaeeeaes 231 19 10 Setting MvcFeature TEMPLATE_BASE_PATH value in ResourceConfig 231 19 11 Setting FreemarkerMvcProperties TEMPLATE_BASE_PATH value in web xml debasing Pras E Gru decd Ss owdaondeuadeedawe ad ant weacws ry oulassdduuddertuct hee Pub davest ont ieaau tsar dunt kerudeh ESS 232 19 12 Including JSP page into JSP page 0 eee cece eee ce eeceeeca seca ceca sean esas een eeneeeeeees 235 19 13 Custom TemplateProcessor sreo soci seni nb seces bvenmecep were stor ER EEEE EE SESEK EEES EErEE es 236 19 14 Registering custom TemplateProcessor 1 2 0 0 0 cee eseeeeecc ence ence neces ceeeeeeseaeeeueeaa eens eeaeeees 236 20 1 Application event istenei sosiete ana e e Seon dee ssae weet aduntacedereadensereed
215. e 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 xm1l 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 xm1 MultivaluedMap lt K V gt 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 a resource method Boolean http docs oracle 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 t ext 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 https jer
216. e 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 Controller Note Some of the passages examples from this chapter have been taken from MVCJ https blogs oracle com sandoz entry mvcj blog article written by Paul Sandoz In Jersey 2 the base MVC API consists of two classes org glassfish jersey server mvc package that can be used to bind model to view template namely Viewable https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Viewable html and Template https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Template html These classes determine which approach explicit implicit you would be taking when working with Jersey MVC templating support 19 1 Viewable 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 https jersey java net apidocs 2 10 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 19 1 Using Viewable ina resource class Example 19 1 Using Viewable in a resource class package com example Path foo pu
217. e default value for the type attribute of ValidateOnExecution is IMPLICIT which results in method get Email being validated 206 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 https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html B V_DISABLE_VALIDATE_ON_EXECUTABLE_OVERRIDE_ CHECK property Jersey specific to t rue 17 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 htm and Validator http docs jboss org hibernate beanvalidation spec 1 1 api javax validation Validator html as required by Bean Validation spec Note Injected Configuration _ http docs jboss org hibernate beanvalidation spec 1 1 api javax validation Configuration htm Validator
218. e 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 171 Server Sent Events SSE Support 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 InboundEvent The method InboundEvent readData 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 readEntity Class The method readData can also throw a ProcessingException http jax rs spec java net nonav 2 0 apidocs javax ws rs ProcessingException html The null check on inboundEvent 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 t Hello world 0 t Hell
219. e heroku weba Getting Started Git remote heroku added Note The name of the instance is changed in the output to simple heroku webapp Your will be named more like tranquil basin 4744 Add and commit files to your Git repository git add src pom xm 1 Procfile system properties e2b58e3 initial commit insertions rc main java com example MyResource java rc main java com example heroku Main java rc main webapp WEB INF web xml rc test java com example MyResourceTest java git commit a m initial commit master root commit 7 files changed 221 create mode 100644 Procfile create mode 100644 pom xml create mode 100644 s create mode 100644 s create mode 100644 s create mode 100644 s create m Push changes to Heroku ode 100644 system properties git push heroku master Counting objects 21 done Delta compression using up to 8 threads Compressing objects Writing objects 100 100 11 11 done 21 21 3 73 KiB 0 bytes s done Total 21 delta 0 reused 0 delta 0 gt Java app detected gt Installing OpenJDK 1 7 done gt Installing Maven 3 0 3 done gt Installing settings xml done gt executing app Z ry O tmp cache maven bin mvn B Duser home tmp build_992cc INFO Scanning for projects Ze Fy OO Building simple heroku webapp 1 0 SNAPSHOT Ze a OO
220. e output stream jaxbExcepti 39 36 Z 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 91 JAX RS Entity Providers Parameters type and genericType both define the entity where t ype is a raw 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 ParameterizedType html including generic information for example List lt String gt Parameter annotations 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 2 public Response get 6 Annotation annotation AnnotatedResource class 7 getAnnotation Path class 8 return Response ok 9 entity Entity new Annotation f annotation build 10 11 In the example above the Me
221. e 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 server container 14 Server MessageBody Writer 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 ret
222. e 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 ItemContentSingletonResource 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 42 JAX RS Application Resources an
223. eaderInterceptor WriterInterceptor 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 are executed in the reverse order using descending manner so a provider with the priority defined with Priority 2000 will be executed before another provider with priority defined with Priority 1000 It s 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 Lee 2 import javax annotation Priority 3 import javax ws rs Priorities 4 5 6 Priority Priorities HEADER_DECORATOR 7 public class ResponseFilter implements ContainerResponseFilter 8 9 Override 10 public void filter ContainerRequestContext requestContext 11 ContainerResponseContext responseContext 12 throws IOException
224. eam 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 and on the interceptor GZIPWriterInterceptor The interceptor will 137 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 Compress and GZIP otherwise the i
225. ean 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 3 1 Configuring Feature Auto discovery Mechanism namely e WadlFeature https jersey java net apidocs 2 10 jersey org glassfish jersey server wadl WadlFeature html enables WADL processing e UriConnegFilter https jersey java net apidocs 2 10 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 AutoDiscoverable Jersey SPI This interface is not public at the moment and is subject to change in the future so be careful when trying to use it 4 3 1 Configuring Feature Auto discovery Mechanism The mechanism of feature auto discovery in Jersey that described above is enabled by default It can be disabled by using special common server client properties 50 Application Deployment and Runtime Environments Common auto discovery properties e CommonProperties FEATURE_AUTO_DISCOVERY_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE When set disables auto discovery globally on client server CommonProperties JSON_PROCESSING_FEATURE_DISABLE https je
226. eans EIB reres ani nao u dia au a us E PAASA 63 4 8 4 Java EE Servers oos resen ers toe e VE E E TEE ESE os ee EE E RE 64 AOS OSGI a a E E E e ae E a a o T EA EE TTE 65 4 9 1 Enabling the OSGi shell in Glassfish 2 0 0 0 cece eecc ence eeeeeeeeeeeeeeeneeeaes 65 4 9 2 WAB Example si cicsosssoscagsctscusncsotes Syeda segiscotsassectan nda snseasg OSE EEEE REIRE 66 lil Jersey 2 10 User Guide 4 9 3 HTTP Service Example siei 0s esses ssigs secdeehevaeses veer ghey eeunageaveseunss eemeees eevee 67 4 10 Other Environments aaien seh sedan telsee des Sea ges baatoosh Lag cdey Dla feb ence E ace nanos 68 4 10 1Oracle Jaya Cloud Services sci Sans eee a onae Aa wa E EENE 68 De Cent API iea a E EE A E E E Ea meee E E de hee E TO staeey 69 5 1 Uniform Interface Constraint mp arse pesoen e e p E E A ESE okt 69 5 2 Ease of use and reusing JAX RS artifacts sseesneeeesseeessreersrsrrrresrrrrsrrrrrsrrerrsreerere 70 5 3 Overview of the Client APE ogia eten a e A A feodaawhe Sead cagdeen ERT AS 71 5 3 1 Getting started with the client API sseeeseeeesseeserseesrrressrerrerrerrrrerrereerreees 71 5 3 2 Creating and configuring a Client instance seeseeeeeeereerererrrerrrerrerrrerrreree 71 5 3 3 Targeting a web TeSoUrC eoni E E TEE E E S O S 73 5 3 4 Identifying resource on WebTarget ccc eeceee cece cece ee ce ence eeceeeeeeeeeeeeeeeaees 73 3 3 5 Invoking a HTTP request vic2 tenci e EE edb uscd
227. eated for each test of a test class However TestNG creates only one instance of a test class and the initialization of the test container depends more on setup teardown methods driven by BeforeXXX and AfterXXX annotations than in JUnit This means that basically you can start one instance of test container for 263 Jersey Test Framework all tests present in a test class or separate test container for each and every test For this reason a separate subclasses of JerseyTestNg https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTestNg html have been created e JerseyTestNg ContainerPerClassTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTestNg ContainerPerClassTest html creates one container to run all the tests in Setup method is annotated with BeforeClass teardown method with AfterClass For example take a look at ContainerPerClassTest test It contains two test methods first and second one singleton resource that returns an increasing sequence of number Since we spawn only one instance of a test container for the whole class the value expected in the first test is 1 and in the second it s 2 1 public class ContainerPerClassTest extends JerseyTestNg ContainerPerClassTest 2 3 Path 4 Singleton 5 Produces text plain 6 public static class Resource 7 8 private int i 1 9 0 GET 1 public int get 2 return i 3 4 5
228. eature can provide both authentication methods digest and basic Feature can work in the following modes e BASIC Basic preemptive authentication In preemptive mode the authentication information is send always with each HTTP request This mode is more usual than the following non preemptive mode if you require BASIC authentication you will probably use this preemptive mode This mode must be combined with usage of SSL TLS as the password is send only BASE64 encoded e BASIC NON PREEMPTIVE Basic non preemptive authentication In non preemptive mode the authentication information is added only when server refuses the request with 401 status code and then the request is repeated with authentication information This mode has negative impact on the performance The advantage is that it does not send credentials when they are not needed This mode must be combined with usage of SSL TLS as the password is send only BASE64 encoded e DIGEST Http digest authentication Does not require usage of SSL TLS e UNIVERSAL Combination of basic and digest authentication The feature works in non preemptive mode which means that it sends requests without authentication information If 401 status code is returned the request is repeated and an appropriate authentication is used based on the authentication requested in the response defined in WWW Authenticate HTTP header The feature remembers which authentication requests were successful for given URI and next
229. ecide 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 i sReadable executions always define correctly the consumable media type s with the Consumes annotation on your custom MessageBodyReader lt T gt 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 yourMessageBodyReader lt T gt implementation The stream will be automatically closed by Jersey runtime 7 2 2 3 Testing a MessageBodyWriter lt T gt 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 3 6 7 8 95 JAX RS Entity Providers
230. ed 0 eee eee eeceeeceeeeeeeeeeeeeeeenees 276 25 5 2 New deprecated APIs internal classes ccc cece cece ce eeceeeee eee eeneeeneeeenees 276 25 5 3 Removed deprecated APISis cs essp ssness sand eo e o e wotess devee tyes eames KSO 276 25 6 Migrating from Jersey 2 5 to 2 5 1 oo ee cece E ee ca cece cece eens cena EEEE ER 277 25 7 Migrating from Jersey 2 4 10 toZ Jrone se aaa Qenqeeed deen ceeeusee ye NEEE 277 25 7 1 Client side API and SPI changes cece ceeceeece ence eeceeeeneeea seen sean eeaes 277 25 7 2 Other changes sos asevets see diseswed ghey sun a doce eeu pen vese pees EEVEE EEEE REE EAEE 279 25 8 Migrating from Jersey 2 4 to 2 4 1 riei oriire eee ceeca E E R S 279 25 9 Migrating from Jersey 2 3 to 2 4 0 eee ceeecc cece aa e R e Eee E sean eeans 279 25 10 Migrating from Jersey 2 0 2 1 or 2 2 to 2 3 occ cee e cee ceeeee teen essa sean eene eens 280 25 11 Migrating from Jersey 1 X to 2 0 oe cece sene eE E E AT e aa SE 280 QS NUM Server ARI R tuctetisc ees stunted da ssstan ed deta de T E aie deastu gee E shes ERNAS 280 25 112 Migrating Jersey Clhent APIs 3s2ocs02s seecvesans nave aes a dee Gevus teas sebense ever ceded 284 Ae Conhiguration Properties a yc cesta heh ade oe Os eee eel ee a Saves taba ee eae eee hs 288 A 1 Common client server configuration properties cece cece cece eeeeeeee seen seen eenes 288 A 2 Server configuration properties
231. ed 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 0 apidocs javax ws rs core UriBuilder html and UriTemplate https jersey java net apidocs 2 10 jersey org glassfish jersey uri 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart package summary 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 too much code to do something relatively simple especially when the client needs to understand different payload representations This is why
232. ee 2 10 examples osgi helloworld webapp source code This example does not package into a single war file Instead a war and a set of additional jars is produced during the build See the next example to see how to deploy OSGi based Jersey application to GlassFish 4 9 3 HTTP Service Example Note When deploying an OSGi HTTP Service example to GlassFish please make sure the OSGi HTTP Service bundle is installed on your GlassFish instance You can directly install and activate the Jersey application bundle In case of our example you can either install the example bundle stored locally and alternatively build from Jersey sources 1 Build optional 1 2 examples cd osgi http service bundle 3 bundle S mvn clean package You can also get the binary readily compiled from maven repository https maven java net content repositories releases org glassfish jersey examples os gi http service bundle 2 10 2 Install into OSGi runtime 1 2 gogo install file path to file bundle jar 3 Bundle ID 303 or install it directly from the maven repository 1 2 gogo install http maven java net content repositories releases org glassfis 3 Bundle ID 303 Make sure to replace lt version gt with an appropriate version number Which one is appropriate depends on the specific GlassFish 4 x version you are using The version of the bundle cannot be higher than the version of Jersey integrated in your GlassFish 4 x server Jersey bund
233. efined 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 17 5 Constraint annotations on class Example 17 5 Constraint annotations on class Path NonEmptyNames class MyResourceClass NotNull FormParam firstName private String firstName NotNull FormParam lastName private String lastName private String email 203 Bean Validation Support Constraint annotations on resource classes are useful for defining cross field and cross property constraints 17 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 17 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 17 6 Definition of a constraint annotation Example 17 6 Definition of a constraint annotation T Target METHOD FIELD Retention RUNTIME Constraint validatedBy public interface Email PARAMETER EmailValidator class String message default com example validation constraints email Class lt gt groups
234. egister 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 entity or representation as a stream of bytes use InputStream as follows InputStream in response readEntity InputStream cla
235. ell commands by typing osgi lt felix_command gt inthe asadmin console For example 1 2 asadmin gt osgi lb 3 list of bundles or launching the shell using osgi she11 command in the admin console the domain must be started otherwise the osgi shell won t launch 1 2 asadmin gt osgi shell 3 Use exit to exit and help for online help 4 gogos and execute the osgi commands directly without the osgi prefix 1 2 gogo lb 3 list of bundles WAB Example As mentioned above WAB is just an OSGi fied WAR archive Besides the usual OSGi headers it must in addition contain a special header Web ContextPath specifying the web application context path Our WAB has beside some other the following headers present in the manifest 66 Application Deployment and Runtime Environments 1 Web ContextPath helloworld 2 Webapp Context helloworld 3 Bundle ClassPath WEB INF classese Here the second header is ignored by GlassFish but may be required by other containers not fully compliant with the OSGi Enterprise Specification mentioned above The third manifest header worth mentioning is the Bundle ClassPath specifying where to find the application Java classes within the bundle archive More about manifest headers in OSGi can be found in the OSGi WIKI http wiki osgi org wiki Category Manifest_Header For more detailed information on the example please see the WAB Example https github com jersey jersey tr
236. en the factory instantiates and injects a new PerSessionResource instance The instance is then stored in the perSessionMap for later use for future calls In a real life scenario you would want to pay more attention to possible synchronization issues Also we do not consider a mechanism that would clean up any obsolete resources for closed expired or otherwise invalidated HTTP client sessions We have omitted those considerations here for the sake of brevity of our example 259 Chapter 22 Spring DI Jersey provides an extension to support Spring DI This enables Jersey to use Spring beans as JAX RS components e g resources and providers and also allows Spring to inject into Jersey managed components The Spring extension module configuration is based on annotations Spring beans are injected and JAX RS classes are made Spring managed using annotations Injected Spring beans can have further dependencies injected using Spring XML configuration Spring singleton and request scopes are supported Limitations e Spring beans can t be injected directly into JAX RS classes by using Spring XML configuration 22 1 Dependencies If you want to use Jersey Spring DI support you will need to add the jersey spring3 https jersey java net project info 2 10 jersey project jersey spring3 dependencies html module into the list of your dependencies lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt ar
237. ens 188 16 2 A simple WADL example WADL content 0 0 0 0 cece eee cnec ca eece cece eene een eeneeeneees 190 16 3 OPTIONS method returning WADL 0 ee cece cece cc cece e cence eeeeeceaeeeeeeeeeaeeeaeeeaes 192 16 4 More complex WADL example JAX RS resource definition eee eee eee eee ee 193 16 5 More complex WADL example WADL content cece ce ee eens ce eeeeeeeeeeeeeeenees 195 17 1 Configuring Jersey specific properties for Bean Validation eceeeceeeeeeeeeeeeneeeeee eens 199 17 2 Using ValidationConfig to configure Validator wo ceeecenteeeeeeeeeeees 201 17 3 Constraint annotations on input parameters cece cess eens ce eece ence eeeeeeeeeeeeeeneeeaes 202 17 4 Constraint annotations on fields zase egere eaea ea E Ra ei 203 17 5 Constraint annotations on class ee ssseesserstesrrreesreresrrerrsrrerrrresrreeesreresrrerrsreerreeen 203 17 6 Definition of a constraint annotation ssseseeesstiestisstrestrserresrrssrresrrssrresrrereresrreerreert 204 17 7 Validator implementations 222 irei ar a a a E E A EE RE 204 17 8 Entity validation saena a a e a das E a a E a e EEE 205 17 9 Entity Validation 2e ne r a e pee ab E E e E A ae re Mabie ae E T RNS 205 17 10 Response entity validation esnin neess aa e e Ea Ea EER I E OESE anea 206 17 11 Validate getter on execution virens eersianr ef re a E R E TEA E N 206 17 12 Injecting Urilnfo into a ConstraintValidator
238. ent 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 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
239. ent equivalent functionality as a JavaEE web application you can deploy on any servlet container supporting Servlet 2 5 and higher 1 1 Creating a New Project from Maven Archetype 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 lt id gt snapshot repository java net lt id gt lt name gt Java net Snapshot Repository for Maven lt name gt lt url gt https maven java net content repositories snapshots lt url gt lt layout gt default lt layout gt lt repository gt 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 t
240. equest post Entity entity multipart multipart getMediaType Warning Do not use ApacheConnectorProvider nor GrizzlyConnectorProvider neither JettyConnectorProvider connector implementations with Jersey Multipart features See Header modification issue warning for more details 8 3 3 Server Returning a multipart response from server to client is not 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart MultiPart html entity e Injecting particular parts of a form data multipart request via FormDataParam _ https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart FormDataParam htm 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 49 Resource method using MultiPart as input parameter return value POST Produces mult
241. er 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 SseBroadcaster is not mandatory to complete the use case individual EventOutput https jersey java net apidocs 2 10 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 https jersey java net apidocs 2 10 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 14 5 Consuming SSE events with Jersey clients On the client side Jersey exposes APIs that support receiving and processing SSE events
242. ere are no annotations on the class or it s fields the default scope is assumed During the filtering first the annotations on root model class and it s fields are considered For all composite fields that have not been filtered out the annotations on the referenced child class and it s fields are considered next and so on 18 3 1 Server side Entity Filtering To pass entity filtering annotations via Response http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response html returned from a resource method you can leverage the Response ResponseBuilder entity Object Annotation http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response ResponseBuilder html entity java lang Object java lang annotation Annotation method The next example illustrates this approach You will also see why every custom entity filtering annotation should contain a factory for creating instances of the annotation Example 18 13 ProjectsResource Response entity filtering annotations 1 Path projects 2 Produces application json 3 public class ProjectsResource 4 5 GET 6 public Response getProjects QueryParam detailed final boolean isDetail J return Response 8 ok 9 entity new GenericEntity lt List lt Project gt gt EntityStore getProjec 10 isDetailed new Annotation ProjectDetailedView Fact 11 build 12 13 Annotating a resource method class is typically easier al
243. ers Example 5 4 Sending restricted headers with HttpUr1lConnector Client client ClientBuilder newClient header Origin http example com get O ON GAUN Note that internally the HttpUrlConnection instances are pooled so un setting the property after already creating a target typically does not have any effect The property influences all the connections created after the property has been un set but there is no guarantee that your request will use a connection created after the property change In a simple environment setting the property before creating the first target is sufficient but in complex environments such as application servers where some poolable connections might exist before your application even bootstraps this approach is not 100 reliable and we recommend using a different client transport connector such as Apache Connector These limitations have to be considered especially when invoking CORS Cross Origin Resource Sharing requests As indicated earlier Connector https jersey java net apidocs 2 10 jersey org glassfish jersey client spi Connector html and ConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client spi ConnectorProvider html contracts are Jersey specific extension APIs that would only work with Jersey and as such are not part of JAX RS Following example shows how to setup the custom Grizzly Asynchronous HTTP Client based ConnectorPr
244. ersey 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 Closing connections The underlying connections are opened for each request and closed after the response is received and entity is processed entity is read See the following example Example 5 5 Closing connections 1 final WebTarget target some web target 2 Response response target path resource request get 3 System out printin Connection is still open 4 System out printin string response response readEntity String class 5 System out printin Now the connection is closed If you don t read the entity then you need to close the response manually by response close Also if the entity is read into an InputStream http docs oracle com javase 6 docs api java io InputStream html by response readEntity InputStream class the connection stays 79 Client API open until you finish reading from the InputStream In that case the InputStream or the Response should be closed manually at the end of reading from InputStream 5 8 Injections into client providers In some cases you might need to inject some custom types into your client provider instance JAX RS types do not need to be injected as they are passed as arguments into API me
245. ersey 2157 issue has been fixed Jersey client runtime automatically buffers error response entities This behavior is automatic and there is no need to set any property 25 9 Migrating from Jersey 2 3 to 2 4 All deprecated SSE InboundEvent https jersey java net apidocs 2 10 jersey org glassfish jersey media sse InboundEvent html getData methods have been removed from the API Use the 279 Migration Guide new readData methods have been introduced instead in Jersey 2 3 for consistency with other parts of client side JAX RS API Access to the raw SSE event data content is provided via a InboundEvent s byte getRawData method that has been too introduced in Jersey 2 3 All EJB and CDI integration classes have been moved into internal Jersey packages to clearly state the integration code should not be used as a public API 25 10 Migrating from Jersey 2 0 2 1 or 2 2 to 2 3 All existing SSE InboundEvent https jersey java net apidocs 2 10 jersey org glassfish jersey media sse InboundEvent html getData methods have been made deprecated and new readData methods have been introduced instead for consistency with other parts of client side JAX RS API The deprecated getData methods will be removed in Jersey 2 4 A new SSE InboundEvent https jersey java net apidocs 2 10 jersey org glassfish jersey media sse InboundEvent html byte getRawData method has
246. erties 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 17 2 Using ValidationConfig to configure Validator You can set custom instances for the following interfaces from the Bean Validation API 199 Bean Validation Support MessagelInterpolator http docs jboss org hibernate beanvalidation spec 1 1 api javax validation MessagelInterpolator html interpolates a given constraint 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 Cons
247. erver runtime MUST generate a NotSupportedException HTTP 415 status code and no entity and the client runtime MUST generate an instance of ProcessingException 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 lt T gt 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 MessageBodyWorkers https jersey java net apidocs 2 10 jersey org glassfish jersey message MessageBodyWorkers html interface and Jersey provides an implementation that can be injected using the 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 lt T gt 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 intercep
248. erviceLocatorClientProvider getServic 10 11 and ask for MyInjectedService 12 final MyInjectedService service locator getService MyInjectedService 13 14 final String name service getName 15 16 17 For more information see javadoc of ServiceLocatorClientProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client ServiceLocatorClientProvider html and javadoc of ServiceLocatorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey ServiceLocatorProvider html which supports common JAX RS components 5 9 Securing a Client This section describes 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 80 Client API 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 Client
249. es 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 readData can throw a ProcessingException http jax rs spec java net nonav 2 0 apidocs javax ws rs ProcessingException html The custom event source listener is registered in the event source via EventSource register EventListener String method The next 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 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
250. es 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 processed by the proper MessageBodyReader lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext 149 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 150 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
251. esources and methods 1 0 0 0 0 cece eee cece eeeeeeca seca essa eens eeaes 202 17 4 1 Constraint Annotations ou 2 39 fered saga en sen qeudd n RS a E euseeden tes 202 17 4 2 Annotation constraints and Validators cece cee eee ceeeceeeee teen een eene eens 204 17 4 3 Entity Validation 23 5 scseco esse den r a covanae soe veedebepe tus dospheedees bested 204 17 4 4 Annotation Inheritance cies een r E ces te eet ede oad eee ee deh ned sees 206 17 3 NahdateOn Execution 054 552 355 tase soeestve tact deve gases aE denn seen seve ygee dene AEE a EES S 206 1750 Im CCE Bassas Sasicd Seder dat eee can EE N tun ead be oS ease E A N E E 207 V7 7 Error REPOrting rosene ebass e stitess dp nsded soy aE AS the be Sete se shed tees a E 208 T t Vali dation Exton sinen tet aetna a aN 208 17 8 Example rie sders cet Asad aeadawns E ANE dsea pou saeeb seat Senden ison sur atd aaa gidacwnaetbors 211 t8 Entity Data Filter e oen teks oe iapeeie eden Saget EES AEE ee Ee 212 18 1 Enabling and configuring Entity Filtering in your application cece eee 212 18 2 Components used to describe Entity Filtering concepts cece cee cent ee ee erence 214 18 3 Using custom annotations to filter entities 0 0 0 cece eens ce eeceeeceeeeeeeeeeeaeeeaes 216 18 3 1 Server side Entity Filtering sores cece ee cece cece cece ne tinsi i a e pi 219 18 3 2 Client side Entity Filtering sornes cece a ea E r seen ESET ERESSE 221 18 4 Role ba
252. esources as shown above See deployment chapter for more information 13 3 Additional examples Example 13 4 A programmatic resource final Resource Builder resourceBuilder Resource builder resourceBuilder addMethod OPTIONS handledBy new Inflector lt ContainerRequestContext Resp Override public Response apply ContainerRequestContext cont return Response ok This is a response to an O final Resource resource resourceBuilder build ani m E e E ATA S A E O S gt S 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 Hel 1oWorldResource resource class and enhanced it by OPTIONS method The OPTIONS method is handled by an Inflector which returns Response http jax rs spec java net nonav 2 0 apidocs javax ws rs core Response html The following sample shows how to define sub resource methods methods that contains sub path 160 Programmatic API for Building Resources Example 13 5 A programmatic resource final Resource Builder resourceBuilder Resource builder final Resource Builder childResource resourceB
253. esrerrerrrererrerrereerreresrrrrerreerrt 274 25 2 Mapping of Jersey 1 x to JAX RS 2 0 client classes 2 0 0 ceeeceec ce eece een eeneeeneeeenees 285 A 1 List of common configuration properties 2 0 0 0 cceeeeeeecceeeeeeececueeeeeeceeeeseeaaeeeeeseeauereeuaes 288 A 2 List of server configuration properties 2 0 0 0 cece cece cece cece ce cence ne eeneceneeeeeeeeseeeeaeeeaeeeaes 289 A 3 List of client configuration properties cece ce ec eeceeece ence eceeeeeeeceeeeaeeeaeeeaeeea sean eeaee 293 Vili List of Examples 3 1 Simple hello world root resource Class cece cece cece ence cece cece cena eeneceaeeeeeeeeeseeeeeeeeaeeenes 31 3 2 Specifying URI path parameter cece cece nce ne cence eeeeeeceeeceeeeaeeeaeeeaeeea een ecae esas 32 3 3 PUT Method cscaicseseeses soa ac eae a asles AEAEE E EES SERTE EEEE SEEE PRESPA STERS 33 3 4 Specifying output MIME type 2 0 0 eee cee cee cc eeceeeee teen eeea ceca sean eeas eens eeneeneeeeeee ees 33 3 5 Using multiple output MIME types 20 0 0 s siipeen ae cece e easa a T aa E eert 34 3 6 Server side content negotiation 2 2 0 0 cece cence cece e ccc ce nace ne ceeeeeeeeeeeeeeeeaeeeaesea esau eeaaeeaes 34 3 7 Specifying input MIME type sssrini eessen e eseon roe nE EE EEEE OSESE ETTO dss PEORES ESTES 35 3 6 Query parameters coN reen dese e n e a eate aae e E EEEE S ES E E T E 35 3 9 Custom Java type for consuming request parameters ee ssseres
254. est 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 PreMatchingFilter implements ContainerRequestFilter OrArNA 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 LS 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 PreMat chingFilter 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 P 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 in
255. ested JAX RS Jersey application This factory would be picked and used by JerseyTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html to instantiate TestContainer https jersey java net apidocs 2 10 jersey org glassfish jersey test spi TestContainer html that will host the tested application This feature was unreliable and redundant As such support for the feature has been removed To specify a custom TestContainerFactory to be used by your JerseyTest subclass please override the JerseyTest getTestContainerFactory method instead Overriding getTestContainerFactory now remains the only reliable way of specifying custom TestContainerFactory implementation to be used in your tests Protected method set TestContainerFactory has been removed from the JerseyTest API as calling the method had no effect on the TestContainerFactory instance used by the JerseyTest subclass Protected method get Client has been removed from the JerseyTest API To configure test client instances please override the configureClient method instead Utility methods JerseyTest that provide access to pre configured Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html and WebTarget _ http jax rs spec java net nonav 2 0 apidocs javax ws rs client WebTarget html instances client target have been made final to prevent overriding in subclasses and thus ensure consistency of the jersey
256. et gt tr lt method gt lt jersey extended xmlns jersey http jersey java net gt true lt lt resource gt lt jersey extended xmlns jersey http jersey java net gt true lt jers lt resource gt lt resources gt lt application gt 190 WADL Support In the example above the returned application WADL is shown in full WADL schema is defined by the WADL specification so let s look at it in more details 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 Pr
257. ethod 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 filter method is finished the response passed as a parameter 130 Filters and Interceptors to the abortWith method is used to respond to the request Response filters if any are 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 resource 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 requ
258. 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 t Hello world 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 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 3538383583883 88 Se Sy MES iano Et Sy ES teins SSeS When browsing through the Jersey SSE API documentation you may have noticed that the EventSource https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventSource html implements lEventListener https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventListener html and provides an empty implementation for the 173 Server Sent Events SSE Support 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 fr
259. ext new JettisonJaxbContext 2 JettisonConfig mappedJettison serializeAsArray name build 3 types Resulting JSON will look like in the example below unimportant lines removed for sanity Example 8 23 JSON expression with JSON arrays explicitly configured via Jersey Contact if name Bob WUHAN OBPWBN EF 113 Support for Common Media Type Representations 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 Example 8 24 JSON expression produced using badgerfish notation TA 2 contacts 3 WM sf 4 WOM ewe 5 6 name 7 Woe Bob 8 9 addresses 10 street 11 S Long Street 1 12 13 town 14 S Short Village T5 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 https jersey java net apidocs 2 10 jersey org glassfish jersey jettison JettisonFeature html and a ContextResolver lt T gt for JAXBContext if needed in your C
260. ey Glassfish Bundles Jersey Glassfish Bundles jersey gf cdi https jersey java net project info 2 10 jersey project project jersey gf cdi dependencies html jersey gf cdi ban custom hk2 binding https jersey java net project info 2 10 jersey project project jersey gf cdi ban custom hk2 binding dependencies html Jersey CDI for GlassFish integration Jersey CDI for GlassFish integration this module disables custom HK2 binding jersey gf ejb https jersey java net project info 2 10 jersey project project jersey gf ejb dependencies html Jersey EJB for GlassFish integration Table 2 9 Security Security oauth1 client https jersey java net project info 2 10 jersey project oauth 1 client dependencies html Module that adds an OAuth 1 support to Jersey server oauth1 server https jersey java net project info 2 10 jersey project oauth1 server dependencies html Module that adds an OAuth 1 support to Jersey client oauth1 signature https jersey java net project info 2 10 jersey project oauth1 signature dependencies html OAuth signature module oauth2 client https jersey java net project info 2 10 jersey project oauth2 client dependencies html Module that adds an OAuth 2 support to Jersey client 21 Modules and dependencies Table 2 10 Jersey Examples Jersey Examples assemblies http
261. ey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html FEATURE eDISGOVERN DISABLE di AUTO_DISCOVERY_DISABLI BDasablea tieatire autovdescpvery on client Default value is false i https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html FOLLOW ClientProperties FOLLOW_REDIREC 8y config client fdDbolw amp sdithatctthe client REDIRECTS will automatically redirect to the URI declared in 3xx responses Default value is true https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html JSON_PR https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html METAINF ClientProperties JSON_PROCESSiINGsSERATURE PISA BET di CESSING_FEATURE_DISABLI SERVICES_LOOKUP_DISABLE Dasables s ootfigneationirof Json Processing JSR 353 feature Default value is false i ClientProperties METAINF_SER VIEESe LOOKUP DISABLE eMe Disables e rv ME FEAdNFhgervi eise lookup on client Default value is false 4 https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html MOXY_JS ClientProperties MOXY_JSON_HBATBRE DIBABGEclient di ON_FEATURE_DISABLE Dasabkewicconfiguration of MOXy Json feature Default value is false https jersey java net apidocs 2 10 jersey org glassfish jersey client
262. ey java net apidocs 2 10 jersey org glassfish jersey test TestProperties html RECORD_LOG_LEVEL for more information 23 5 Parallel Testing with Jersey Test Framework For a purpose of running multiple test containers in parallel you need to set the TestProperties CONTAINER_PORT https jersey java net apidocs 2 10 jersey org glassfish jersey test TestProperties CONTAINER _PORT html to 0 value This will tell Jersey Test Framework and the underlying test container to use the first available port You can set the value as a system property via command line option or directly in the test to not affect ports of other tests 1 Override 2 protected Application configure 3 Find first available port 4 forceSet TestProperties CONTAINER_PORT 0O 5 6 return new ResourceConfig Resource class 7 The easiest way to setup your JUnit or TestNG tests to run in parallel is to configure Maven Surefire plugin You can do this via configuration options parallel and threadCount i e lt configuration gt lt parallel gt methods lt parallel gt lt threadCount gt 5 lt threadCount gt lt configuration gt For more information about this topic consult the following Maven Surefire articles e Fork Options and Parallel Test Execution http maven apache org surefire maven surefire plugin examples fork options and parallel execution html e Using TestNG Running tests in parallel http maven apache org suref
263. ey mvc jsp integration from examples bookstore webapp module 250 Monitoring and Diagnostics Example 20 6 On demand request snippet of MVC JSP forwarding 1 2 3 4 5 6 7 8 9 10 11 12 curl i http localhost 9998 items 3 tracks 0 Jersey Traci Jersey Traci Jersey Traci Jersey Traci Jersey Traci Jersey Traci Jersey Traci Jersey Traci ng 033 ng 034 ng 035 ng O036 ng O37 ng 038 ng 039 ng 040 WI WI MBW MBW MVC MBW WI WI 0 00 0 01 109 0 00 0 00 Pal at Pa a ae ea 23 23 23 233 05 24 24 24 24 39 42 45 52 63 67 70 H X Jersey Tracing Accept wh 35333838838 HAHoHDHA HA HHA DA ae le o9 o9 A 0 o org glassfis org glassfis Find MBW for org glassfis Forwarding vi WriteTo by o org glassfis org glassfis 251 Lie ers ty tees ew rg nN nN Chapter 21 Custom Injection and Lifecycle Management 21 1 Since version 2 0 Jersey uses HK2 http hk2 java net library for component life cycle management and dependency injection Rather than spending a lot of effort in maintaining Jersey specific API as it used to be before Jersey 2 0 version Jersey defines several extension points where end user application can directly manipulate Jersey HK2 bindings using the HK2 public API to customize life cycle management and dependency injection of application components Jersey user
264. f 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 lt gt 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 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 Fut ure 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
265. following URL http jersey exampl addresses 51234 select region streetAddress may render only the address s region and XmlRootElement public class Address private String streetAddress private String region private PhoneNumber phoneNumber street address properties as in the following example 222 http docs oracle com javaee 6 api javax annotation security RolesAllowed html com Entity Data Filtering Example 18 18 regron 3 CAT streetAddress 1234 Fake St Bw WN PF 18 6 Defining custom handling for entity filtering annotations To create a custom entity filtering annotation with special handling i e an field aggregator annotation used to annotate classes like the one in Example 18 19 Entity filtering annotation with custom meaning it is in most cases sufficient to implement and register the following SPI contracts e EntityProcessor https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering spi EntityProcessor html Implementations of this SPI are invoked to process entity class and it s members Custom implementations can extend from AbstractEntityProcessor https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering spi AbstractEntityProcessor html e ScopeResolver _ https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering spi ScopeResolver htm Implementations of
266. g String methods that give you control over configuring values of the properties defined and described in the TestProperties class A typical code that overrides the default property values is listed below 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 23 4 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 lt groupid gt org glassfish jersey test framework providers lt groupld gt lt artifactId gt jersey test framework provider external lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt 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 info
267. g TestNG as well It works almost out of the box and 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 23 1 Basics 1 public class SimpleTest extends JerseyTest 2 3 Path hello 4 public static class HelloResource 5 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 Zils If you want to develop a test using Jersey Test Framework you need to subclass JerseyTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest 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 He1loResource used in tests defined as part of the SimpleTest class The overridden configure method returns a ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html of the test application that contains only the HelloResource resource class ResourceConfig is a sub class of JAX RS Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Appl
268. g eclipse jetty lt groupId gt 3 lt artifactId gt jetty server lt artifactId gt 4 lt version gt 2 10 lt version gt 5 lt dependency gt Note Jetty HTTP container does not support deployment on context paths other than root path Non root context path is ignored during deployment 4 6 Creating programmatic JAX RS endpoint JAX RS specification also defines the ability to programmatically create a JAX RS application endpoint i e container for any instance of a Application subclass For example Jersey supports creation of Grizzly http grizzly java net Htt pHandler instance as follows HttpHandler endpoint RuntimeDelegate getInstance createEndpoint new MyApplication HttpHandler class Once the Grizzly Htt pHandler endpoint is created it can be used for in process deployment to a specific base URL 4 7 Serviet based Deployment In a Servlet container JAX RS defines multiple deployment options depending on the Servlet API version supported by the Servlet container Following sections describe these options in detail 55 Application Deployment and Runtime Environments 4 7 1 Servlet 2 x Container Jersey integrates with any Servlet containers supporting at least Servlet 2 5 specification Running on a Servlet container that supports Servlet API 3 0 or later gives you the advantage of wider feature set especially asynchronous request processing support and easier and more flexible deploymen
269. g har ieee 89 7 2 How to Write Custom Entity Providers 2 0 0 0 cece ceeeceeeceeeceeeceeecaeeeaeeee sean eeu eees 89 7 2 k MeSsaseB ody Writer sasni arien sea devues od a EE tee ed ee 90 T22 MessageBody Reader mesinna oenene eee dane duedaww na ebad ence eaten stenndes 94 T3 Entity Provider Selection cenre eek NGI Saeed EA eee ae en E Mabey 96 7A Jersey MessageBodyWorkers AP menoissa e E R E ENR 99 7 5 Default Jersey Entity Providers 0 0 0 0 e E E ceca ceca E E E OSER 101 8 Support for Common Media Type Representations 2 0 0 0 cece cece ee eee cece cece een eeneeeeeeeeeeeeees 102 Sel JSON seat e a e e neh E Geeta eed A deee Nan Sure sie alt a doa heehee ans 102 8 1 1 Approaches to JSON Support esessesererereesssereressrerrererresrertereesrersrsereeere 102 8 1 2 MOXY a e a ad lash eastie cules dudsebna dy ace Be TE EAE EE 105 8 1 3 Java API for JSON Processing JSON P ccceeececeeeceeeneceeeeeeeeeeaeeeenees 108 Su 4 Jacksonian tic ircctan Siete Giceti heats eden dda eee ed se ul a EA TES 109 81 3 Jeti SON 935 iee aE e eae deters sendendy soveuc peoeeespateeadepeywensses EE sede 111 8 1 6 JSONP JSON with Padding Support 2 2 0 0 cece ee eect ee eee eeeeeeeeees 115 82 IM Din eee Sods Suid bah e ae dyed a Ane R a shee Seehidne coubemes ar ovaacadeueedel 117 8 2 1 Low level XML support oreca e sei S a EAE ESS 117 8 2 2 Getting started with JAXB eres eens Ern A Suede AREE aa 118 8 2 32 POJOS rn hea E A E OE E E
270. g 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 17 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 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 17 3 Constraint annotations on input parameters augmented with constraint annotations Example 17 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 la
271. glassfish jersey media lt groupId gt lt artifactId gt jersey media moxy lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt If you re not using Maven make sure to have all needed dependencies see jersey media moxy https jersey java net project info 2 10 jersey project jersey media moxy dependencies html on the classpath 8 1 2 2 Configure and register As stated in the Section 4 3 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 registration of MoxyJsonFeature besides the generic CommonProperties FEATURE_AUTO_DISCOVERY_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE an the its client server variants CommonProperties MOXY_JSON_FEATURE_ DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties htmlHMOXY_JSON_FEATURE_ DISABLE ServerProperties MOXY_JSON_FEATURE_DISABLE __ https jersey java net apidocs 2 10 jer
272. glassfish jersey server monitoring ResourceMXBean html contains statistics of resource e ResponseMXBean __ https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ResponseMXBean html contains statistics of responses The list does not contain MXBean for the execution and time window statistics The reason is that this bean is defined as a DynamicMBean http docs oracle com javase 6 docs api javax management DynamicMBean html Attributes of this dynamic MBean contains statistics for all time windows available 247 Monitoring and Diagnostics MxXBeans do not reference each other but can be retrieved by their ObjectName http docs oracle com javase 6 docs api javax management ObjectName html s which are designed in the way that final MBean tree looks nicely organized in JConsole Each MXBean is uniquely identified by its Ob jectName and properties of Ob ject Name are structured hierarchically so that each MXBean can be identified to which parent it belong to e g execution statistics dynamic MXBean belongs to resource method MXBean which belongs to resource and which belongs to application Check the Ob ject Names of exposed MXBeans to investigate the structure for example through JConsole To reiterate exposing Jersey MXBeans and the calculating monitoring statistics may have an performance impact on your application and therefore should be enabled only when needed Also please note that it Jer
273. guide can by no means supply an exhaustive documentation of HK2 API in it s entire scope This chapter only points out the most common scenarios related to dependency injection in Jersey and suggests possible options to implement these scenarios It is highly recommended to check out the HK2 http hk2 java net website and read HK2 documentation in order to get better understanding of suggested approaches HK2 documentation should also help in resolving use cases that are not discussed in this writing There are typically three main use cases where your application may consider dealing with HK2 APIs exposed in Jersey e Implementing a custom injection provider that allows an application to define additional types to be injectable into Jersey managed JAX RS components e Defining a custom injection annotation other than Inject http docs oracle com javaee 6 api javax inject Inject html or Context http jax rs spec java net nonav 2 0 apidocs javax ws rs core Context html to mark application injection points e Specifying a custom component life cycle management for your application components Relying on Servlet HTTP session concept is not very RESTful It turns the originally state less HTTP communication schema into a state full manner However it could serve as a good example that will help me demonstrate implementation of the use cases described above The following examples should work on top of Jersey Servlet integration module
274. h OAuth versions as such Note OAuth 2 support is in a Beta https jersey java net apidocs 2 10 jersey org glassfish jersey Beta html state and as such the API is subject to change 185 Security To add support for Jersey OAuth 2 Client API into your application add the following dependency to your pom xml lt dependency gt lt grouplid gt org glassfish jersey security lt grouplId gt lt artifactId gt oauth2 client lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt OAuth 2 in contrast with OAuth 1 is not a strictly defined protocol rather a framework OAuth 2 specification defines many extension points and it is up to service providers to implement these details and document these implementations for the service consumers Additionally OAuth 2 defines more than one authorization flow The authorization flow similar to the flow from OAuth 1 is called the Authorization Code Grant Flow This is the flow currently supported by Jersey Jersey currently does not support other flows Please refer to the OAuth 2 0 specification http tools ietf org html rfc6749 for more details about authorization flows Another significant change compared to OAuth is that OAuth 2 is not based on signatures and secret keys and therefore for most of the communication a SSL needs to be used i e the requests must be made through HTTPS This means that all OAuth 2 endpoint URIs must use the https scheme Due to t
275. he 70 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 lt T gt 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 would have to be written to make it easy to reuse the logic when communicating with the same resource http localhost 8080 res
276. he JavaDoc of Viewable https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Viewable html class which in our case is com fo00 Foo index Jersey will then search all the registered template processors see Section 19 7 Writing 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 Note If none or empty template reference is provided either in Viewable or via Template then the index reference is assumed and all further processing is done for this value 19 3 2 Absolute template reference 19 4 Let s change the resource GET method in our Foo resource a little Example 19 4 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 Absolute template references start with leading i e com example index foo character and are not further resolved with respect to the resolving resource class which means that the template is looked for at the provided
277. he annotation can be directly created The annotation factory class can be created by extending the HK2 AnnotationLiteral class and implementing the annotation interface itself It should also provide a static factory method that will create and return a new instance of the Fact ory class when invoked Such annotation instances can be then passed to the client and server run times to define or override entity filtering scopes By placing an entity filtering annotation on an entity class fields getters or setters we define a so called entity filtering scope for the entity The purpose of entity filtering scope is to identify parts of the domain model that should be processed when the model is to be sent over the wire in a particular entity filtering scope We distinguish between e global entity filtering scope defined by placing filtering annotation on a class itself and e local entity filtering scope defined by placing filtering annotation on a field getter or setter Unannotated members of a domain model class are automatically added to all existing global entity filtering scopes If there is no explicit global entity filtering scope defined on a class a default scope is created for this class to group these members Creating entity filtering scopes using custom entity filtering annotations in domain model classes is illustrated in the following examples Example 18 10 Annotated Project 1 public class Project 2 3 priva
278. he 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 https jersey java net apidocs 2 10 jersey org glassfish jersey message MessageProperties html property OUTBOUND_CONTENT_LENGTH_BUFFER which configures the 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 lt T gt 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 https jersey java net apidocs 2 10 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 annota
279. he fact that OAuth 2 does not define a strict protocol it is not possible to provide a single universal pre configured tool interoperable with all providers Jersey OAuth 2 APIs allows a lot of extensibility via parameters sent in each requests Jersey currently provides two pre configured authorization flow providers for Google and Facebook The most important entry points of Jersey client OAuth 2 API and SPI are explained below e OAuth2ClientSupport https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth2 OAuth2ClientSupport html The main class which contains builder methods to build features that enable the OAuth 2 support Start with this class every time you need to add any OAuth 2 support to the Jersey Client build an Authorization flow or initialize client to perform authenticated requests The class contains also methods to get authorization flow utilities adjusted for Facebook or Google e OAuth2CodeGrantFlow https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth2 OAuth2CodeGrantFlow html API that allows to perform the authorization flow defined as Authorization Code Grant Flow in the OAuth 2 specification Implementation of this interface is a class that is used as a standalone utility and is not part of the JAX RS client In other words this is not a feature that should be registered into the client ClientIdentifier https jersey java net apidocs 2 10 jersey org glassfish jer
280. he longer the scanning time In use cases where you need to save every millisecond of application bootstrap time you may typically want to disable the services provider lookup in Jersey List of SPIs recognized by Jersey e AutoDiscoverable server client it means if you disable service loading the AutoDiscoverable feature is automatically disabled too e ForcedAutoDiscoverable server client Jersey always looks for these auto discoverable features even if the service loading is disabled e HeaderDelegateProvider server client e ComponentProvider server e ContainerProvider server e AsyncContextDelegateProvider server Servlet 51 Application Deployment and Runtime Environments List of additional SPIs recognized by Jersey in case the metainf services module is on the classpath e MessageBodyReader server client e MessageBodyWriter server client e ExceptionMapper server client Since it is possible to configure all SPI implementation classes or instances manually in your Application subclass disabling services lookup in Jersey does not affect any functionality of Jersey core modules and extensions and can save dozens of ms during application initialization in exchange for a more verbose application configuration code The services lookup in Jersey enabled by default can be disabled via a dedicated CommonProperties METAINF_SERVICES_LOOKUP_DISABLE https jersey java net apidocs 2 10 jersey o
281. he new project should reside mvn archetype generat DarchetypeArtifactId jersey quickstart grizzly2 DarchetypeGrouplId org glassfish jersey archetypes DinteractiveMode false DgroupId com exampl DartifactId simple servic Dpackage com example DarchetypeVersion 2 10 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 EF Ne 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 packag import
282. her eclipselink oxm xml file should be 14 CustomClassA class CustomClassB class Classes to be bound 15 122 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 e 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 e A MessageBodyWriter lt T gt implementation for producing MIME MultiPart entities The appropriate P 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media m
283. her user implemented annotations that are applied to a providers and resource methods See the following example 136 Filters and Interceptors Example 9 7 NameBinding example O a OBWN EF T U Go G G w a a G w A NONNA NaO DGO NANN G NG FFF RFR RP RP FP FP PE OO OA ga G AOA NH O Oa a a T e Ae OA WAATAABWBNF OY 41 42 43 44 45 46 47 48 The Compress NameBinding Retention RetentionPolicy RUNTIM import 3 import j import 3 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 OutputStr
284. hod 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 uriInfo 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 automatically support the methods HEAD and OPTIONS if not explicitly implemented For HEAD the runtime will invoke the implemented GET method if present and ignore the response entity if set A response returned for the OPTIONS method depends on the requested media type defined in the Accept header The OPTIONS method can return a response with a set of supported resource methods in the Allow header or return a WADL http wadl java net document See wad 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
285. hod and not any other requests In our case the returned request event listener keeps information about the request number of the current request and a start time of the request which is later used to print out the request processing times statistics This demonstrates the principle of listening to request events for one request there is a one instance which can be used to hold all the information about the particular request In other words RequestEvent Listener is designed to be implicitly request scoped Jersey represents lifecycle events via RequestEvent https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring RequestEvent html and ApplicationEvent https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ApplicationEvent html types Instances of these classes contain information about respective events The most important information is the event type Type retrievable via get Type method which identifies the type of the event Events contain also additional information that is dependent on a particular event type This information can be retrieved via event getters Again some getters return valid information for all event types some are specific to a sub set of event types For example in the RequestEvent the getExceptionCause method returns valid information only when event type is ON_EXCEPTION On the other hand a getContainerRequest can be used to return
286. hould be used as entity filtering scope when reading writing an Processing of entity filtering annotations to create an entity filtering scope is defined by following Request Resourc ntity annotations gt Configuration gt Resource method class annotations on server You can configure entity filtering on server basic security examples as follows Example 18 1 Registering and new ResourceConfig Set entity filt configuring entity filtering feature on server ring scope via configuration property EntityFilteringFeature ENTITY_FILTERING_SCOPE new Annotation register EntityFilteringFeature class Further configuration of ResourceConfig 1 2 3 4 Register the EntityFilteringFeature 5 6 7 register 213 Entity Data Filtering Example 18 2 Registering and configuring entity filtering feature with security annotations on server new ResourceConfig Set entity filtering scope via configuration property EntityFilteringFeature ENTITY_FILTERING_SCOPE new Annotation Register the SecurityEntityFilteringFeature register SecurityEntityFilteringFeature class Further configuration of ResourceConfig register WUHAN OBPWBN EH Example 18 3 Registering and configuring entity filtering feature based on dynamic and configurable query parameters 1 new
287. 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 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 https jersey java net apidocs 2 10 jersey org glassfish jersey server ChunkedOutput 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 l
288. ication html It is a Jersey convenience class 261 Jersey Test Framework 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 23 2 Supported Containers JerseyTest https jersey java net apidocs 2 10 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 Simple HTTP container org simpleframework http and Jetty HTTP container org eclipse jetty A test container is selected based on various inputs JerseyTest getTestContainerFactory https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html getTestContainerFactory is always executed so if you override it and provide your own version of TestContainerFactory https jersey java net apidocs 2 10 jersey org glassfish jersey test spi TestContainerFactory html nothing else will be considered Setting a system variable TestProperties CONTAINER_ FACTORY __ https jersey java net apidocs 2 10 jersey org glassfish jersey test TestProperties html CONTAINER FACTORY has similar effect This way you may defer the decision
289. ication will run in Jetty on Heroku To compile and package the application into a WAR invoke the following maven command in your console mvn clean package A successful build output will produce an output similar to the one below Results Tests run 1 Failures 0 Errors 0 Skipped 0 INFO INFO maven war plugin 2 2 war default war simple heroku webapp INFO Packaging webapp INFO Assembling webapp simple heroku webapp in simple heroku webapp t INFO Processing war project INFO Copying webapp resources simple heroku webapp src main webapp INFO Webapp assembled in 57 msecs INFO Building war simple heroku webapp target simple heroku webapp war INFO WEB INF web xml already added skipping INFO INFO maven dependency plugin 2 8 copy dependencies copy dependencies INFO Copying hk2 locator 2 2 0 b21 jar to simple heroku webapp target de INFO Copying jetty security 9 0 6 v20130930 jar to simple heroku webapp INFO Copying asm all repackaged 2 2 0 b21 jar to simple heroku webapp ta INFO Copying jersey common 2 5 jar to simple heroku webapp target depend INFO Copying validation api 1 1 0 Final jar to simple heroku webapp targ INFO Copying jetty webapp 9 0 6 v20130930 jar to simple heroku webapp ta INFO Copying jersey container servlet 2 5 jar to simple heroku webapp ta INFO Copying cglib 2 2 0 b21 jar to simple herok
290. icitly 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 resource method s invoked from another request thread s can write data into the chunked output and or close the chunked response 146 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 printin Request is being processed asynchronously 5 final Response response responseFuture get 6 get waits for the response to be ready 7 System out printin 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 AsynclInvoker http jax rs spec java net nonav 2 0 apidocs javax ws rs client AsyncInvoker html The AsyncInvoker is returned from the call o
291. idden method on the event source allows you to handle messages even when no additional listeners are registered yet 14 5 2 1 Event Source reconnect support Starting in Jersey 2 3 the EventSource implementation supports automated recuperation from a connection loss including negotiation of delivery of any missed events based on the last received SSE event id field value provided this field is set by the server and the negotiation facility is supported by the server In case of a connection loss the last received SSE event id field value is send in the Last Event ID HTTP request header as part of a new connection request sent to the SSE endpoint Upon a receipt of such reconnect request the SSE endpoint that supports this negotiation facility is expected to replay all missed events Note Note that SSE lost event negotiation facility is a best effort mechanism which does not provide any guaranty that all events would be delivered without a loss You should therefore not rely on receiving every single event and design your client application code accordingly By default when a connection the the SSE endpoint is lost the event source will use a default delay before attempting to reconnect to the SSE endpoint The SSE endpoint can however control the client side retry delay by including a special ret ry field value in the any send event Jersey Event Source implementation automatically tracks any received SSE event re
292. ider http jax rs spec java net nonav 2 0 apidocs javax ws rs ext Provider html annotation or adding it to the Jersey ResourceConfig https jersey java net apidocs 2 1 O 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 283 ER_NOTIFIER Migration Guide Example 25 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 de T2 13 Override 14 public void onStartup Container container 15 this container container 16 17 18 Override 19 public void onReload Container container 20 ignore or do whatever you want after reload has been done 21 22 23 Override 24 public void onShutdown Container container 25 ignore or do something after the container has been shutdown 26 244 Example 25 4 Jersey 2 reloader registration 1 Reloader reloader new Reloader 2 resourceConfig addSingletons reloader 3 25 11 1 3 MessageBodyReaders and MessageBodyWriters ordering JAX RS 2 0 defines new order of MessageBodyWorkers whole set is sorted by declaration distance
293. ify properties only for entity serialization and deserialization purposes Let s now look at an example of aWriterInterceptor 133 Filters and Interceptors Example 9 6 GZIP reader interceptor public class GZIPReaderInterceptor implements ReaderInterceptor de 2 3 Override 4 public Object aroundReadFrom ReaderInterceptorContext context 5 throws IOException WebApplicationException 6 7 8 9 0 final InputStream originalInputStream context getInputStream context setInputStream new GZIPInputStream originalInputStream 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 intercepto
294. igured and started programmatically In general Jersey container for a specific HTTP server provides a custom factory method that returns a correctly initialized HTTP server instance 4 5 1 1 JDK Http Server Starting with Java SE 6 Java runtime ships with a built in lightweight HTTP server Jersey offers integration with this Java SE HTTP server through the jersey container jdk http container extension module Instead of creating the HttpServer http docs oracle com javase 6 docs jre api net httpserver spec com sun net httpserver HttpServer html1 instance directly use the createHttpServer method of JdkHttpServerFactory https jersey java net apidocs 2 10 jersey org glassfish jersey jdkhttp JdkHttpServerFactory html which creates the HttpServer instance configured as a Jersey container and initialized with the supplied Application subclass Creating new Jersey enabled jdk http server is as easy as Example 4 5 Using Jersey with JOK HTTP Server 1 URI baseUri UriBuilder fromUri http localhost port 9998 build 2 ResourceConfig config new ResourceConfig MyResource class 3 HttpServer server JdkHttpServerFactory createHttpServer baseUri config A JDK HTTP Container dependency needs to be added lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container jdk http lt artifactId gt lt version gt 2 10 lt version gt lt dependency
295. ilder also offers a method for defining a custom HostnameVerifier http docs oracle com javase 6 docs api javax net ssl 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 provider HttpUrlConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnector html provides connectors based on HttpUrlConnection which implement support for SSL defined by JAX RS configuration discussed in this example 5 9 1 Http Authentication Support Jersey supports Basic and Digest HTTP Authentication Important In version prior to Jersey 2 5 the support was provided by org glassfish jersey client filter HttpBasicAuthFilter and org glassfish jersey client filter HttpDigestAuthFilter Since Jersey 2 5 these filters are deprecated and removed in 2 6 and both authentication methods are provided by single Feature HttpAuthenticationFeature https jersey java net apidocs 2 10 jersey org glassfish jersey client authentication HttpAuthenticationFeature html In order to enable http authentication support in Jersey client register the HttpAuthenticationFeature https jersey java net apidocs 2 10 jersey org glassfish jersey client 81 Client API authentication HttpAuthenticationFeature html This f
296. ilding Resources The MyOpt ionsModelProcessor from the example is a relatively simple model processor which iterates over all registered resources and for all of them builds a new resource that is equal to the old resource except it is enhanced with a new OPTIONS method Note that you only need to register such a ModelProcessor as your custom extension provider in the same way as you would register any standard JAX RS extension provider During an application deployment Jersey will look for any registered model processor and execute them As you can seem model processors are very powerful as they can do whatever manipulation with 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 subReso
297. in packages org foo rest and org bar rest 49 Application Deployment and Runtime Environments 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 D Note Later in this chapter the term Application subclass is frequently used Whenever used this term refers to the JAX RS Application Model explained above 4 3 Auto Discoverable Features By default Jersey 2 x does not implicitly register any extension features from the modules available on the classpath unless explicitly stated otherwise in the documentation of each particular extension Users are expected to explicitly register the extension Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature html s using their Application subclass For a few Jersey provided modules however there is no need to explicitly register their extension Features as these 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 runtime whenever the modules implementing these features are present on the classpath of the deployed JAX RS application The modules that are automatically discovered include e JSON binding feature from jersey media moxy e jJersey media json processing e jersey b
298. in the application import org glassfish hk2 api TypeLiteral import org glassfish hk2 utilities binding AbstractBinder import javax inject Singleton public class MyApplication extends ResourceConfig public MyApplication register new AbstractBinder Override protected void configure bindFactory HttpSessionFactory class to HttpSession class bind SessionInjectResolver class to new TypeLiteral lt InjectionResolver lt SessionInject gt gt in Singleton class 21 3 Custom Life Cycle Management The last use case discussed in this chapter will cover managing custom scoped components within a Jersey application If not configured otherwise then all JAX RS resources are by default managed on a per request basis A new instance of given resource class will be created for each incoming request that should be handled by that resource class Let say you want to have your resource class managed in a per session manner It means a new instance of your resource class should be created only when a new Servlet HttpSession http docs oracle com javaee 6 api javax servlet http HttpSession html is established As with previous examples in the chapter this example assumes the deployment of your application to a Servlet container Following is an example of such a resource class that builds on the support for Ht tpSession injection from the earlier examples described in this chapter The PerSessionResour
299. 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 88 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 object 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 ty
300. injects a JAX RS AsyncResponse http jax rs spec java net nonav 2 0 141 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 injected 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 GET http jax rs spec ja
301. ion OAuth 1 2 MEO Sete 2y name OAUTH J users email very secret com War Fer alk name Jersey Robot bee For the default entity filtering scope the filtered model would look like 220 Entity Data Filtering e Project id name description Or in JSON format 1 2 description Jersey is the open source under dual CDDL GPL license JA 3 WEAN gz Ty 4 name Jersey 5S 18 3 2 Client side Entity Filtering As mentioned above you can define applied entity filtering scopes using a property set either in the client run time Configuration see Example 18 4 Registering and configuring entity filtering feature on client or by passing the entity filtering annotations during a creation of an individual request to be sent to server Example 18 15 Client Request entity filtering annotations 1 ClientBuilder newClient config 2 target uri 3 request 4 post Entity entity project new Annotation ProjectDetailedView Factory You can use the mentioned method with client injected into a resource as well Example 18 16 Client Request entity filtering annotations 1 Path clients 2 Produces application json 3 public class ClientsResource 4 5 Uri projects 6 private WebTarget target 7 8 GET 9 public List lt Project gt getProjects 10 return target request 11 post Entity entity project new Annotation
302. ion 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 https jersey java net apidocs 2 10 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 messageTemplate 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 209 Bean Validation Support Example 17 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 17 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 lt div c
303. ionFactory implements Factory lt HttpSession gt private final HttpServletRequest request Inject public HttpSessionFactory HttpServletRequest request this request request Override public HttpSession provide return request getSession Override public void dispose HttpSession t Please note that the factory implementation itself relies on having the actual HttpServletRequest instance injected In your implementation you can of course depend on other types and inject them conveniently as long as these other types are bound to the actual HK2 service locator by Jersey or by your application The key notion to remember here is that your HK2 Factory implementation is responsible for implementing the provide method that is used by HK2 runtime to retrieve the injected instance Those of you who worked with Guice binding API in the past will most likely find this concept very familiar Once implemented the factory can be used in a custom HK2 Binder to define the new injection binding for HttpSession Finally the implemented binder can be registered in your ResourceConfig https jersey java net apidocs 2 1 O jersey org glassfish jersey server ResourceConfig html import org glassfish hk2 utilities binding AbstractBinder public class MyApplication extends ResourceConfig public MyApplication register new AbstractBinder Override protected void configure bindFactory HttpSe
304. ions 14 2 When to use Server Sent Events 14 3 As explained above SSE is a technology that allows clients 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
305. ipart 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 FormDataParam https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart FormDataParam htm annotation 126 Support for Common Media Type Representations 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart FormDataParam htm l e FormDataBodyPart The value of the parameter will be the first named body part or nu11 if such a named body part is not present e 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 e 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 e A List or Collection of FormDataContentDisposition The value of the parameter will one or more content dispositi
306. ire maven surefire plugin examples testng html Running_tests_in_parallel 267 Jersey Test Framework e Using JUnit Running tests in parallel http maven apache org surefire maven surefire plugin examples junit html Running_tests_in_parallel 268 Chapter 24 Building and Testing Jersey 24 1 24 2 24 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 7 or higher The build is based on Maven Maven 3 1 or higher is highly recommended Also it is recommended you use the follo
307. is not the thrown exception but rather a list of ValidationError https jersey java net apidocs 2 10 jersey org glassfish jersey server validation ValidationError html s This list can be iterated in the template and all the validation errors can be shown to the user in a desirable way Example 19 6 Using ErrorTemplate with Bean Validation POST Produces text html Consumes MediaType APPLICATION_FORM_URLENCODED Template name short link ErrorTemplate name error form Valid public ShortenedLink createLink NotEmpty FormParam link final String link Example 19 7 Iterating through ValidationError in JSP lt c forEach items model var error gt S error message lt strong gt S error invalidValue lt strong gt lt br gt lt c forEach gt Support for Bean Validation in Jersey MVC Templates is provided by a jersey mvc bean validation extension module The JAX RS Feature http jax rs spec java net nonav 2 0 apidocs 230 MVC Templates javax ws rs core Feature html provided by this module MvcBeanValidationFeature has to be registered in order to use this functionality see Section 19 5 Registration and Configuration Maven users can find this module at coordinates lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey mvc bean validation lt artifactId gt lt version gt 2 1
308. isatrleMetainf Ceppi sbisedaleMetainf sableMoxyJso sableMoxyJso ClientProperties OUTBOUND_COAHENT dENGGHcBURFERLErextde pictcteti amp Loeldemrnt cantentLength Migration Guide Constant Old value Jersey 2 7 and New value Jersey 2 8 before ServerProperties OUTBOUND_CONEENT cbhN GP He RUREER ette pinthteit_gesererer cantentLength https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html OUTBOUND_CONTENT_LENGTH_BUFFER ServerProperties TRACING jersey config server tpersey config server tyacing type https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html TRACING 4 The old names are still working for now but are deprecated There is a fallback mechanism implemented while reading the property and each get that resolves the value from the old named property will log a CONFIG level warning 25 4 Migrating from Jersey 2 6 to 2 7 25 4 1 Changes e Until version 2 6 Jersey was compiled with Java SE 6 This has changes in Jersey 2 7 Now almost all Jersey components are compiled with Java SE 7 target It means that you will need at least Java SE 7 to be able to compile and run your application that is using latest Jersey Only core common and core client modules are still compiled with Java class version runnable with Java SE 6 e MVC support method writeTo of TemplateProcessor https jersey java net apidocs
309. ization flow requests for performance and or resource management reasons using OAuth Builder https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth1 OAuth1Builder html methods 15 3 1 2 1 Public Private Keys for RSA SHA1 signature method Follow the steps below in case the outgoing requests sent from client to server have to be signed with RSA SHAI signature method instead of the default one HMAC SHA1 Example 15 12 Creating Public Private RSA SHA1 keys Create the private key openssl genrsa out private key 2048 Convert the key into PKCS8 format openssl pkcs8 topk8 in private key nocrypt Extract the public key openssl rsa in private key pubout DOP WN EF The output of the second command can be used as a consumer secret to sign the outgoing request new ConsumerCredentials consumer key CONSUMER_PRIVATE_KEY Public key obtained from the third command can be then used on the service provider to verify the signed data For more advanced cases i e other formats of keys a custom OAuth1SignatureMethod should be implemented and used 15 3 2 OAuth 2 Support At the moment Jersey supports OAuth 2 only on the client side 15 3 2 1 Client Note Note It is suggested to read the section Section 15 3 1 2 Client before this section Support for OAuth on the client is very similar for both OAuth 1 and OAuth 2 and general principles are valid for bot
310. 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 resource is a sub resource is returned more times during the matching In this situation only on instance will server the requests Per PerLookuyrg glassfish hk2 api RdnLiwkispope the resource instance 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 43 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 a
311. jersey java net apidocs 2 10 jersey org glassfish jersey server filter RolesAllowedDynamicFeature html as a provider The following example shows how to register the feature if your deployment is based on a ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html Example 15 4 Registering RolesAllowedDynamicFeature using ResourceConfig 1 final ResourceConfig resourceConfig new ResourceConfig MyResource class 2 resourceConfig register RolesAllowedDynamicFeature class 3 Alternatively typically when deploying your application to a Servlet container you can implement your JAX RS Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Application html subclass by extending from the Jersey ResourceConfig and registering the RolesAllowedDynamicFeature in the constructor 178 Security 15 2 Example 15 5 Registering RolesAllowedDynamicFeature by extending ResourceConfig 1 public class MyApplication extends ResourceConfig 2 public MyApplication 3 super MyResource class 4 5 6 register RolesAllowedDynamicFeature class Once the feature is registered you can use annotations from package javax annotation security defined by JSR 250 See the following example Example 15 6 Applying javax annotation security to JAX RS resource methods 1 Path 2 PermitAll 3 public class Resource 4 RolesA
312. jersey media sse SseFeature html DISABLE SSE property to true The behavior can also be selectively suppressed in either client or server runtime by setting the DISABLE_SSE_CLIENT https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseFeature htmI DISABLE_SSE_CLIENT or DISABLE_SSE_SERVER https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseFeature html DISABLE_SSE_SERVER property respectively Deprecated getDestroyTime method has been removed from ApplicationStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ApplicationS tatistics html To get the application shutdown information a ContainerLifecycleListener https jersey java net apidocs 2 10 jersey org glassfish jersey server spi ContainerLifecycleListener html should be registered and its onShut down method implemented to listen to and process the application shutdown event Method triggerEvent RequestEvent Type has been removed from the public ContainerRequest https jersey java net apidocs 2 10 jersey org glassfish jersey server ContainerRequest html API This method has never been intended for public application level use 272 Migration Guide In Jersey 2 7 and earlier it was under certain conditions possible to supply custom TestContainerFactory https jersey java net apidocs 2 10 jersey org glassfish jersey test spi TestContainerFactory html as part of the t
313. kie gt 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 the messag 37 JAX RS Application Resources and Sub Resources I e 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
314. ks of response should be handled 18 finally 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 getNextString 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 getNext St ring 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 expl
315. lass validation errors gt lt div class validation error gt lt 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 T lt span class invalid value gt lt strong gt invalidValue lt strong gt null lt span gt lt div gt lt div gt Example 17 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 lt 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 ggt lt path gt lt validationError gt lt validationErrors gt 210 Bean Validation Support Example 17 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 17 8 Example To see a complete working example of using Bean Validati
316. le 26 Modules and dependencies Jersey Examples client webapp dependencies html monitoring webapp https jersey java net project info 2 10 jersey project webapp example parent monitoring webapp dependencies html Jersey Web Application Servlet examples parent POM multipart webapp https jersey java net project info 2 10 jersey project webapp example parent multipart webapp dependencies html Jersey Multipart example oauth client twitter https jersey java net project info 2 10 jersey project oauth client twitter dependencies html Twitter client using OAuth 1 support for Jersey that retrieves Tweets from the home timeline of a registered Twitter account oauth2 client google webapp https jersey java net project info 2 10 jersey project oauth2 client google webapp dependencies html Google API data retrieving example using OAuth2 for authentication and authorization osgi helloworld webapp https jersey java net project info 2 10 jersey project osgi helloworld webapp dependencies html Jersey examples osgi http service https jersey java net project info 2 10 jersey project osgi http service dependencies html OSGi HttpService example reload https jersey java net project info 2 10 jersey project reload dependencies html Jersey resource configuration reload example server async https
317. le console application therefore we print the URL to console and ask the user to open the URL ina browser to approve the authorization of our application Then the user gets a verifier and enters it back to 183 Security the console However if our application would be a web application we would need to return a redirection response to the user in order to redirect the user automatically to the authorizationUri For more information about server deployment check our OAuth 2 Google Client WebApp example https github com jersey jersey tree 2 10 examples oauth2 client google webapp OAuth 2 example where the client is part of the web application the client API for OAuth 2 is similar to OAuth 1 Once we have a verifier we invoke the method finish on our OAuthlAuthorizationFlow instance which internally sends a request to an access token service URI http api twitter com oauth access_token and exchanges the supplied verifier for a new valid Access Token At this point the authorization flow is finished and we can start using the retrieved AccessToken to make authenticated requests We can now create an instance of an OAuth 1 client Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature htm using OAuth1ClientSupport and pass it our accessToken Another way is to use authFlow that already contains the information about access token to create the feature instance for us Example 15 9 Authenticated req
318. le name gt 15 lt auth constraint gt 16 lt security constraint gt 17 lt login config gt 18 lt auth method gt BASIC lt auth method gt 19 lt realm name gt my default realm lt realm name gt 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 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 15 1 2 2 Securing JAX RS resources with standard javax annotation security 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 https
319. lection type E g InjectLinks InjectLink resource WidgetsResource class rel self List lt Link gt links 155 Declarative Hyperlinking 12 6 Link Headers 12 7 HTTP Link headers http tools ietf org html rfc5988 section 5 can also be added to responses using annotations Instead of annotating the fields of an entity class with In ject Link you instead annotate the entity class itself with InjectLinks E g InjectLinks value InjectLink widgets S resource nextId rel next The above would insert a HTTP Link header into any response whose entity was thus annotated The Inject Link annotation contains properties that map to the parameters of the HTTP Link header The above specifies the link relation as next All properties of the Inject Link annotation may be used as described above Multiple link headers can be added by use of the Inject Links annotation which can contain multiple Inject Link annotations Configure and register In order to add the Declarative Linking feature register DeclarativeLinkingFeature https jersey java net apidocs 2 10 jersey org glassfish jersey linking DeclarativeLinkingFeature html Example 12 1 Creating JAX RS application with Declarative Linking feature enabled Create JAX RS application final Application application new ResourceConfig packages org glassfish jersey examples linking register DeclarativeLinkingFeature class
320. led default value e ON_DEMAND tracing support is in a stand by mode it is enabled selectively per request via a special X Jersey Tracing Accept HTTP request header e ALL tracing support is enabled for all request The level of detail of the information provided by Jersey tracing facility the tracing threshold can be customized The tracing threshold can be set at the application level via jersey config server tracing threshold application configuration property or at a request level via X Jersey Tracing Threshold HTTP request header The request level configuration overrides any application level setting There are 3 supported levels of detail for Jersey tracing e SUMMARY very basic summary information about the main request processing stages e TRACE detailed information about activities in all the main request processing stages default threshold value e VERBOSE most verbose mode that provides extended information similar to TRACE level however with details on entity providers MBR MBW that were skipped during the provider selection phase for any 248 Monitoring and Diagnostics reason lower priority pattern matching etc Additionally in this mode all received request headers are echoed as part of the tracing information 20 2 2 Tracing Log As mentioned earlier all tracing information is also logged using a dedicated Java Logger The individual tracing messages are logged immedi
321. les declare dependencies on other bundles at the OSGi level and those dependencies are version sensitive If you use example bundle from let s say version 2 5 but Glassfish has Jersey 2 3 1 dependencies will not be satisfied and bundle will not start If this happens the error will look something like this 1 gogo lb 2 67 Application Deployment and Runtime Environments 3 303 Installed 1 jersey examples osgi http service bundle 2 5 0 SNAPS 4 gogoS start 303 5 6 org osgi framework BundleException Unresolved constraint in bundle 7 org glassfish jersey examples osgi http service bundle 303 Unable to resolv 8 303 0 osgi wiring package amp osgi wiring package org glassfish jersey servl 9 version gt 2 5 0 version gt 3 0 0 10 11 gogo s In the opposite scenario example bundle version 2 3 1 and Glassfish Jersey version higher everything should work fine Also if you build GlassFish from the main trunk sources and use the example from most recent Jersey release you will most likely be able to run the examples from the latest Jersey release as Jersey team typically integrates all newly released versions of Jersey immediately into GlassFish As a final step start the bundle 1 gogo start 303 Again the Bundle ID in our case 303 has to be replaced by the correct one returned from the install command The example app should now be up and running You can access it on http localhost 8
322. lic void setPlanet Planet planet 4 System out println setPlanet planet oF 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 xjc 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 Xm RootElement html annotation on Planet class Example 8 35 Resource class JAXBElement 1 Path planet 2 public class Resource 3 4 GET 5 Produces MediaType APPLICATION_XML 6 public JAXBElement lt Planet gt getPlanet 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
323. lication 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 17 Field f Color class getField s 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 String argument 3 Have a static method named valueOf or fromString that accepts a single String argument see for example Integer valueOf String and java util UUID fromString String 4 Have a registered implementation of javax ws rs ext ParamConverterProviderJAX RS extension SPI that returns a javax ws rs ext ParamConverter instance capable of a from string conversion for the type or 5 Be List lt T gt Set lt T gt or SortedSet lt T gt where T satisfies 2 or 3 above The resulting collection is read only Sometimes parameters may contain more than one value for the same name If this is the case then types in 5 may be used to obtain
324. lient 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 can manipulate resource method matching process 134 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 manipulat
325. llowed user 5 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 override 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 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 RolesA11owed annotation present on other methods defines arole 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 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 403 Forbidden error response is returned Client Security For
326. low true 1 OAuth2CodeGrantFlow Builder builder 2 OAuth2ClientSupport authorizationCodeGrantFlowBuilder clientId 3 https example com oauth authorization 4 https example com oauth token 5 OAuth2CodeGrantFlow flow builder 6 property OAuth2CodeGrantFlow Phase AUTHORIZATION readOnly 7 scope contact 8 build 9 String authorizationUri flow start 10 11 Here we must redirect the user to the authorizationUri 12 and let the user approve an access for our app 13 14 15 16 We must handle redirection back to our web resource 17 and extract code and state from the request 18 final TokenResult result flow finish code state 19 System out printin Access Token result get In the code above we create an OAuth2CodeGrantFlow from an authorization URI and an access token URI We have additionally set a readOnly parameter to true and assigned the parameter to the authorization phase This is the way how you can extend the standard flow with additional service provider specific parameters In this case the readOnly true parameter will be added as a query parameter to the authorization uri returned from the method flow start If we would specify ACCESS_TOKEN_REQUEST as a phase then the parameter would have been added to the request when flow finish is invoked See javadocs for more information The parameter readOn1y is not part of the OAuth 2 specification and is
327. lt lt method gt lt method name OPTIONS id apply gt lt request gt lt representation mediaType gt lt request gt lt response gt lt representation mediaType text plain gt lt response gt lt jersey extended xmlns jersey http jersey java net gt true lt lt method gt lt method name OPTIONS id apply gt lt request gt lt representation mediaType gt lt request gt lt response gt lt representation mediaType gt lt response gt lt jersey extended xmlns jersey http jersey java net gt true lt lt method gt lt resource path path gt lt param xmlns xs http www w3 org 2001 XMLSchema type xs st lt method name GET id geExternalGrammar gt lt response gt lt representation mediaType application xml gt lt response gt lt jersey extended xmlns jersey http jersey java net gt tr lt method gt lt method name OPTIONS id apply gt lt request gt lt representation mediaType gt lt request gt lt response gt lt representation mediaType text plain gt lt response gt lt jersey extended xmlns jersey http jersey java net gt tr lt method gt lt method name OPTIONS id apply gt lt request gt lt representation mediaType gt lt request gt lt response gt lt representation mediaType gt lt response gt lt jersey extended xmlns jersey http jersey java n
328. m a read only generic representation of a domain object model graph to be processed into an entity filtering object model your provider understands and can act on The implementations can extend AbstractObjectProvider https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering spi AbstractObjectProvider html Example 18 20 Entity Data Filtering support in MOXy JSON binding provider Singleton public class FilteringMoxyJsonProvider ex 1 2 3 4 2 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2l 22 23 24 25 26 27 28 29 30 31 32 33 34 39 36 37 38 Inject private Override Provider lt ObjectProvider lt ObjectGraph gt gt provider tends ConfigurableMoxyJsonProvider protected void preWriteTo final Object object final Class lt gt type final it final MediaType mediaType fina 1 MultivaluedMap lt final Marshaller marshaller throws JAXBExceptio super preWriteTo object type genericType annotations mediaType ht Entity Filtering marshaller getProperty MarshallerProperties OBJECT_GRAPH null final Object objectGraph provider get getFilt if objectGraph null ringObject gener marshaller setProperty MarshallerProperties OBJECT_GRAPH obje Override protected void preReadFrom final Class lt Object gt type if final Type genericTyp final MediaType mediaType final MultivaluedMap fi
329. m javaee 5 47 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 48 Chapter 4 Application Deployment and Runtime Environments 4 1 Introduction This chapter is an overview of various server side environments currently capable of running JAX RS applications on top of Jersey server runtime Jersey supports wide range of server environments from lightweight http containers up to full fledged Java EE servers Jersey applications can also run in an OSGi runtime The way how the application is published depends on whether the application shall run in a Java SE environment or within a container Note This chapter is focused on server side Jersey deployment models The Jersey client runtime does not have any specific container requirements and runs in plain Java SE 6 or higher runtime 4 2 JAX RS Application Model JAX RS provides a deployment agnostic abstract class Application http jax rs spec java net nonav 2 0 apidocs javax ws rs core Applic
330. made up response with an appropriate code and message in the entity body This will cause that the original request will not be effectively 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 the 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 acommon 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 manip
331. 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 25 11 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 284 Migration Guide Table 25 2 Mapping of Jersey 1 x to JAX RS 2 0 client classes WNattay RS EThss Class dro ajatice faaporglimetiddsnind constructors http jexsey java net monav apedgas d 1ici jeonay 2 0 apid cs fandx jessey npi client Clienthtmder html Ebiette instance methods http jax TS spec java net nonav 2 0 apidocs javax ws rs client Client html Wab Tangetrsey api client WebResource http jexsey java net monav apedgas d rici jeonay 2 0 apid cs fandx jessey api client WebResgetbtmhthml Munh tangetsess qsyvohontrsioys OW teReymrcenethods by calling fhtipVArget request async jexsey java net menav apedgas d rici jeynay 2 0 apidocs jandx jes ey npi 285 Migration Guide Nattny RS EThss Class client Wea bilavehtRtsoljrce html The
332. mes MethodTimes contains statistics measured on on resource methods duration of execution of a code of the a resource method whereas Request Times contains statistics of an entire request execution not only a time of the execution of the resource method but the overall time of the execution of whole request by Jersey runtime Another useful information is that statistics directly under resource not under the methods sub group contains summary of statistics for all resource methods grouped in the resource entry Additional useful details that about statistics e Global gt Configuration gt Registered Classes Instances registered resource classes and instances by the user i e not added by ModelProcessor https jersey java net apidocs 2 10 jersey org glassfish jersey server model ModelProcessor html during deployment for example e Global gt ExceptionMapper gt ExceptionMapperCount map that contains exception mapper classes as keys and number of their execution as values e Global gt Responses gt ResponseCodesToCountMap map that contains response codes as keys and their total occurrence in responses as values e Resource groups contain also entries for resources that were added by Jersey at deployment time using ModelProcessor for example all OPTIONS methods WADL HEAD methods are not present in the MXBeans view even HEAD methods are in resources e Execution statistics for different time win
333. n 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 2 10 examples json jackson on how to use Jackson to consume produce JSON 110 Support for Common Media Type Representations 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 https jersey java net apidocs 2 10 jersey org glassfish jersey jettison JettisonConfig html instance The instance could be then further used to create a JettisonJaxbContext https jersey java net apidocs 2 10 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 apido
334. n code comments and JUnit imports have been excluded for brevity FPOMWMOATA OB WN EF ere packag import import import import public com xample javax ws rs 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 15 16 Before 17 public void setUp throws Exception 18 server Main startServer T9 20 Client c ClientBuilder newClient 21 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 37 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
335. n entity providers support module jersey media json processing https jersey java net project info 2 10 jersey project jersey media json processing dependencies html Jersey JSON P JSR 353 entity providers support proxy module jersey media moxy https jersey java net project info 2 10 jersey project jersey media moxy dependencies html jersey media multipart https jersey java net project info 2 10 jersey project jersey media multipart dependencies html Jersey JSON entity providers support module based on EclipseLink MOXy Jersey Multipart entity providers support module jersey media sse https jersey java net project info 2 10 jersey project jersey media sse dependencies html Jersey Server Sent Events entity providers support module 17 Modules and dependencies Table 2 5 Jersey Extensions Jersey Extensions jersey bean validation https jersey java net project info 2 10 jersey project jersey bean validation dependencies html Jersey extension module providing support for Bean Validation JSR 349 API jersey declarative linking https jersey java net project info 2 10 jersey project jersey declarative linking dependencies html jersey entity filtering https jersey java net project info 2 10 jersey project jersey entity filtering dependencies html Jersey support for declarative hyperlinking Jersey
336. n 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 12 Type genericType 13 Annotation annotations MediaType mediaType 14 MultivaluedMap lt String String gt 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
337. n 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 the 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 conte
338. nCallback 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 143 Asynchronous Services and Clients Example 10 3 CompletionCallback example 1 Path resource 2 public class AsyncResource 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 LS numberOfSuccessResponses 16 k erse 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 355 34 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 Complet ionCallback is used to
339. nal Unmarshaller unmarshaller throws JAXBExc super preReadFrom type genericType annotations mediaType httpHeade Entity Filtering unmarshaller getProperty MarshallerProperties OBJ final Object objectGraph provider get getFilt ECT_GRAPH nul if objectGraph null unmarshaller setProperty MarshallerProperties ringObject gener OBJECT_GRAPH ob 224 Entity Data Filtering 18 8 Modules with support for Entity Data Filtering List of modules from Jersey workspace that support Entity Filtering e MOXy In order to use Entity Filtering in mentioned modules you need to explicitly register either EntityFilteringFeature https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering EntityFilteringFeature html or SecurityEntityFilteringFeature https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering SecurityEntityFilteringFeature html to activate Entity Filtering for particular module 18 9 Examples To see a complete working examples of entity filtering feature refer to the e Entity Filtering example https github com jersey jersey tree 2 10 examples entity filtering e Entity Filtering example with security annotations https github com jersey jersey tree 2 10 examples entity filtering security 225 Chapter 19 MVC Templates Jersey provides an extension to support the Model View Controller MVC design pattern In th
340. name as one of the init param entries as described in Section 4 7 1 Servlet 2 x Container 59 Application Deployment and Runtime Environments 4 7 2 3 Servlet Pluggability Mechanism Servlet framework pluggability mechanism is a feature introduced with Servlet 3 0 specification It simplifies the configuration of various frameworks built on top of Servlets Instead of having one web xml file working as a central point for all the configuration options it is possible to modularize the deployment descriptor by using the concept of so called web fragments several specific and focused web xml files A set of web fragments basically builds up the final deployment descriptor This mechanism also provides SPI hooks that enable web frameworks to register themselves in the Servlet container or customize the Servlet container deployment process in some other way This section describes how JAX RS and Jersey leverage the Servlet pluggability mechanism 4 7 2 3 1 JAX RS application without an Application subclass If no Application or ResourceConfig subclass is present Jersey will dynamically add a Jersey container Servlet and set its name to javax ws rs core Application The web application path will be scanned and all the root resource classes the classes annotated with Path http jax rs spec java net nonav 2 0 apidocs javax ws rs Path html annotation as well as any providers that are annotated with Provider http jax rs spec j
341. nd 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 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 htm Client filters ClientResponseFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientResponseFilter htm ClientResponseFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientResponseFilter htm 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 OP WN FE Ne Override public void filter ContainerReq
342. nd 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 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 wad1 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 16 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
343. ndary Boundary_1_511262261_1369143433608 Boundary_1_511262261_1369143433608 Content Type text plain Content Disposition form data name hello hello Boundary_1_511262261_1369143433608 Content Type application xml Content Disposition form data name xml1 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart file FileDataBodyPart html or StreamDataBodyPart https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart file StreamDataBodyPart html 125 Support for Common Media Type Representations Example 8 48 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 r
344. ndow defined by long value 0 which means unlimited time window This means we are retrieving the global request execution statistics measured since a start of the application Finally request count and average duration from the statistics are used to produce the String response When we invoke few GET requests on the StatisticsResource we get the following console output request count 1 average request processing ms 260 request count 2 average request processing ms 135 request count 3 average request processing ms 93 request count 4 average request processing ms 73 Let s look closer at MonitoringStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring MonitoringStatistics html interface MonitoringStatistics interface defines getters by which other nested statistics can be retrieved All statistics are in the same package and ends with Statistics postfix Statistics interfaces are the following MonitoringStatistics https main top level statistics jersey java net apidocs 2 10 243 Monitoring and Diagnostics jersey org glassfish jersey server monitoring MonitoringStatistics html ApplicationStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ApplicationStatistics html ResponseStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ResponseStatistics htm ResourceS
345. ner dependent features but it is a perfect choice for simple unit tests lt dependency gt lt groupid gt org glassfish jersey test framework providers lt groupId gt lt artifactId gt jersey test framework provider inmemory lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt e HttpServer from Oracle JDK is another supported test container lt dependency gt lt groupid gt org glassfish jersey test framework providers lt groupId gt 262 Jersey Test Framework lt artifactId gt jersey test framework provider jdk http lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt 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 lt groupid gt org glassfish jersey test framework providers lt groupId gt lt artifactId gt jersey test framework provider simple lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt e Jetty container org eclipse jetty is another high performance light weight HTTP server that integrates with Jersey and is supported by Jersey Test Framework lt dependency gt lt groupid gt org glassfish jersey test framework providers lt groupId gt lt artifactId gt jersey test framework provider jetty lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt 23 3
346. nfig gt jsonConfigResolver moxyJsonConfig resolver 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 106 Support for Common Media Type Representations core Configurable html instance see an example below These are overwritten by properties set into the MoxyJsonConfig https jersey java net apidocs 2 10 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 ResourceConfig property MarshallerProperties JSON_NAMESPACE_SEPARATO further configuration There are some properties for which Jersey sets the default value when 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 from MOXy is used and they are Table 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 MessageBody Writer html javax xml bind Marshaller JAXB_FORMA amp TEB_ OUTPUT
347. ng String gt e Plain text text plain e java lang Boolean e java lang Character e 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 83 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 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
348. ng and execution statistics including application configuration exception mappers execution minimum maximum average execution times for individual resource methods as well as entire request processing etc Calculating the monitoring statistics has obviously a performance impact therefore this feature is disabled by default To enable the feature set the following configuration property to t rue jersey config server monitoring statistics enabled true The property description can be found in ServerProperties MONITORING_STATISTICS_ENABLED https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html4MONITORING_STATISTICS_ENABLED This will calculate the statistics The easiest way how to get statistics is to let Jersey to inject them See the following example 242 Monitoring and Diagnostics Example 20 4 Injecting MonitoringStatistics 1 Path resource 2 public static class StatisticsResource 3 Inject 4 Provider lt MonitoringStatistics gt monitoringStatisticsProvider 5 6 GET 7 public String getSomething 8 final MonitoringStatistics snapshot 9 monitoringStatisticsProvider get snapshot 10 11 final TimeWindowStatistics timeWindowStatistics 12 snapshot getRequestStatistics 13 getTimeWindowStatistics get 01 14 15 return request count timeWindowStatistics getRequestCount 16 average request processing ms 17 timeWindowStatistics
349. nitoringStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring MonitoringStatistics html into resource and providers and also the registered listeners implementing MonitoringStatisticsListener https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring MonitoringStatisticsListener html will be called when statistics are available for processing Note that enabling statistics may have a negative performance impact and therefore should be enabled only 290 bled Configuration Properties Constant Value Description when needed Default value is false ServerProperties MONITORING S AS 5T Sn MBEANS VENA BGR tramen g thenat Jersay s wile https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html MONITORING_STATISTICS_MBEANS_H expose MBeans for the collected monitoring statistics Exposed JMX MBeans are based INABMbbiforingStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring MonitoringStatistics html data and therefore when enabled the calculation of monitoring statistics gets automatically enabled too the same result as setting the property pans enabled ServerProperties MONITORING_STATISTICS_EN https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html 4MONITORING_STATISTIC to tr
350. nnotations on resource methods in order to define entity filtering scopes for RolesAllowed that is applied to the domain model components as all the available roles for the current user are automatically determined using the information from the provided SecurityContext server side only 18 5 E Note Instances of security annotations to be used for programmatically defined scopes either on client or server can be created using one of the methods in the SecurityAnnotations _ https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering SecurityAnnotations html factory class that is part of the Jersey Entity Filtering API ntity Filtering based on dynamic and configurable query parameters Filtering the content sent to the client or server dynamically based on query parameters is another commonly required use case By registering SelectableEntityFilteringFeature https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering SelectableEntityFilteringFeature html you can leverage the Jersey Entity Filtering facility in connection with query parameters exactly the same way as you would with custom entity filtering annotations described in previous chapters Example 18 17 Sever Query Parameter driven entity filtering 1 2 3 LC OANA OB Query parameters are supported in comma delimited dot notation style similar to BeanInfo objects and Spring path expressions As an example the
351. nonav 2 0 apidocs javax ws rs Path html annotation with empty path Path or Path which means that the sub resource locator is matched for the path of the enclosing resource without sub resource path Example 3 19 Sub resource locators with empty path 1 Path item 2 public class ItemResource 3 4 Path 5 public ItemContentResource getItemContentResource 6 return new ItemContentResource ah 8 In the example above the sub resource locator method get ItemContentResource is matched for example for request path item locator or even for only item 41 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 Path item 2 public class ItemResource 3 4 Path 5 public Object getItemContentResource 6 return new AnyResource F 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 becaus
352. not have any duration In such case duration values are not set literal The tracing event TEXT is a free form detailed text information about the current diagnostic event Tip For better identification by class name identity of code JAX RS and instances hash components Priority value are if represented set e g org glassfish jersey tests integration tracing ContainerResponseFilter5001 494a8227 5001 Ls 20 2 5 Tracing Examples Example of SUMMARY level messages from tests integration tracing support module Example 20 5 Summary level messages 1 curl i http localhost 9998 ALL root sub resou 2 3 X Jersey Tracing 000 START e of SS yM 4 X Jersey Tracing 001 PRE MATCH 0 01 0 68 m 5 X Jersey Tracing 002 MATCH 8 44 9 15 m 6 X Jersey Tracing 003 REQ FILTER 0 01 9 20 m 7 X Jersey Tracing 004 RI 86 14 95 49 m 8 X Jersey Tracing 005 INVOKE 0 04 95 70 m 9 X Jersey Tracing 006 RESP FILTER 0 01 96 55 m 10 X Jersey Tracing 007 WI 85 95 183 69 11 X Jersey Tracing 008 FINISHED saan f 183 79 rce locator sub resource met s baseUri http S 0 01 PreMatchRequest s 4 59 RequestMatching s 0 00 Request summary S 46 87 ReadFrom summar S 0 02 Resource org g S 0 00 Response summar ms 46 77 WriteTo summar ms Response statu Example TRACE level messages of jers
353. nse resume result 19 20 21 private String veryExpensiveOperation 22 very expensive operation that typically finishes within 20 23 24 start 20 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 TimeoutHandler and setTimeout long TimeUnit methods The setTimeoutHandler 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 e 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 e Connectio
354. nstead 278 Migration Guide 25 7 2 Public constructor has been removed from the JettyConnector https jersey java net apidocs 2 10 jersey org glassfish jersey jetty connector JettyConnector html API JettyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey jetty connector JettyConnectorProvider html should be used to provide Jetty HTTP Client connector instances instead Renamed property CACHING_TEMPLATES_ENABLED in MustacheMvcFeature _ https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc mustache MustacheMvcFeature html from jersey config server mvc caching mustache enabled to jersey config server mvc caching mustache Authentication filters org glassfish jersey client filter HttpBasicAuthFilter and org glassfish jersey client filter HttpDigestAuthFilter were deprecated and replaced by HttpAuthenticationFeature https jersey java net apidocs 2 10 jersey org glassfish jersey client authentication HttpAuthenticationFeature html Other changes The ContainerLifecycleListener https jersey java net apidocs 2 10 jersey org glassfish jersey server spi ContainerLifecycleListener html invokes event onStartup and onShutdown also when application is being started or stopped because of application redeploy The interface was marked as a Beta now The monitoring statistics method ApplicationStatistics getDestroyTime is deprecated and returns
355. nsumes 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 17 9 Entity validation 2 Example 17 9 Entity validation 2 Path class MyResourceClass POST Consumes application xml public void registerUser PremiumUser User user In the example above PremiumUser rather than St andardUser 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 17 10 Response entity validation 205 Bean Validation Support Example 17 10 Response entity validation Path class MyResourceClass GET Path id Produces application xml Valid PremiumUser public
356. nt that contains the value sent in the request greet ing query parameter Now we can observe the returned response 74 GI Client API 5 3 6 1 System out printlin response getStatus 2 System out printin 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 configured a 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 he lloworldWebTarget instance created earlier and call the post instead of get 1 Response postResponse 2 helloworldWebTarget request MediaType TEXT_PLAIN_TYPE 3 post Entity entity A string entity to be POSTed
357. nterceptor 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 Compress and resource class Hel loWorldResource would be annotated from with GZIP This would also trigger the interceptor as annotations of resource 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 138 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 Path 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
358. o register it s providers In order to restore this functionality the org glassfish jersey ext jersey metainf services has to be added on the classpath Otherwise such providers has to be registered manually The Jackson JSON Jersey module has been updated to use Jackson 2 x instead of Jackson 1 x This means that all the code that has been using Jackson 1 x for JSON de serialization has to be migrated to Jackson 2 x 25 3 Migrating from Jersey 2 7 to 2 8 25 3 1 Changes Because of a bug fix for issue JERSEY 2458 https java net jira browse JERSEY 2458 there has been a slight change in the behavior of Urilnfo http jax rs spec java net nonav 2 0 apidocs javax ws rs core UriInfo html get Path and get PathSegments methods The get Path methods no longer return a path prefixed with a slash instead they now correctly return a request path relative to the base request URI Also the Uri Info now correctly handles requests which URI contains empty path segments e g http localhost a b c These empty path segments are now correctly included in the lists returned by the UriInfo getPathSegments methods SseFeature https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseFeature html now gets automatically discovered and enabled if the SSE module is present on the class path This behavior can be suppressed by setting DISABLE_SSE https jersey java net apidocs 2 10 jersey org glassfish
359. o 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 Hello world 9 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 14 5 2 Asynchronous SSE processing with EventSource 3333833838388 n n n n n n n n n n ee The main Jersey SSE client API component used to read SSE events asynchronously is EventSource https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventSource html The usage of the Event Source is shown on the following example Example 14 4 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 EventSource target target build 5 EventListener listener new EventListener 6 Override th public void onEvent InboundEvent inboundEvent 8 System out println inboundEvent getName 9 inboundEvent readData String class 10 11 f 12 eventSource register listener message to client 13 eventSource open LA ey 15 eventSource close In this example the client code again connects to the server where the SseResource from the Ex
360. ocessor 14 import org glassfish jersey server model Resource T5 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 29 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 lt 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 xtended true extended means 40 41 we add to the model new resource which is a 42 by the OPTIONS method 43 newResourceModelBuilder addResource resourceBu 44 45 46 final ResourceModel newResourceModel newResourc 47 and we return new model 48 return newResourceModel 49 50 51 Override 52 public ResourceModel processSubResource ResourceModel 53 we just return the original subResourceModel wh 54 return subResourceModel 55 56 57 162 Programmatic API for Bu
361. ocs 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 e java lang String e java io Reader inbound only e java io File e javax activation DataSource e javax ws rs core StreamingOutput outbound only e XML media types text xml application xml and application xml e javax xml transform Source e 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 Xm1 RootElement htm or XmlType http docs oracle com javase 6 docs api javax xml bind annotation XmlType html e Form content application x www form urlencoded e MultivaluedMap lt Stri
362. odel is now represented by the return value of annotated resource method 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 https jersey java net apidocs 2 10 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 from the Viewable instance take precedence over those defined in the annotation Producible media types are for both cases Viewable and Template determined by the method or class level P roduces annotation 19 2 2 Annotating Resource classes A resource class can have templates implicitly associated with it via Template https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Template html annotation For example take a look at the resource class listing in Example 19 3 Using Template on a resource class Example 19 3 Using Template on a resource class Path foo Template public class Foo public String getFoo return FOO The example relies on Jersey MVC conventions a lot and requires more explanation as such First of all you may have noticed that there is no resource method defined in this JAX RS resource Also there is no 227 MVC Templates template reference defined In this case since the Template annotation placed on the resource class does not contain any information
363. oduces 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 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 Allow header that will contain list of methods as a String The last OPTIONS method producing application vnd sun wadl xml1 returns a WADL description of the resource country 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 All resource that were added in this sec
364. om xm1 file lt dependency gt lt grouplid gt org glassfish jersey media lt groupId gt lt artifactId gt jersey media json processing lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt If you re not using Maven make sure to have all needed dependencies see jersey media json processing _ https jersey java net project info 2 10 jersey project jersey media json processing dependencies html on the class path 8 1 3 2 Configure and register As stated in Section 4 3 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 nonav 2 0 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 https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html FEATURE_AUTO_DISCOVERY_DISABLE and the like CommonProperties JSON_PROCESSING_FEATURE_DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html JSON_PROCESSING_FEATURE_DISABLE ServerProperties JSON_PROCESSING
365. om the Event Source and override the empty listener method to handle the incoming events This programming model is shown in the following example Example 14 5 Overriding Event Source 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 th if message to client equals inboundEvent getName 8 System out println inboundEvent getName 9 inboundEvent readData String class 10 11 Ley ye 13 14 eventSource close The code above is very similar to the code in Example 14 4 Registering EventListener with EventSource In this example however the Event Source is constructed directly using a single parameter constructor This way the connection to the SSE endpoint is by default automatically opened at the event source creation The implementation of the EventListener has been moved into the overridden 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 overr
366. on JSR 349 with Jersey refer to the Bean Validation example https github com jersey jersey tree 2 10 examples bean validation webapp 211 Chapter 18 Entity Data Filtering Support for Entity Filtering in Jersey introduces a convenient facility for reducing the amount of data exchanged over the wire between client and server without a need to create specialized data view components The main idea behind this feature is to give you APIs that will let you to selectively filter out any non relevant data from the marshalled object model before sending the data to the other party based on the context of the particular message exchange This way only the necessary or relevant portion of the data is transferred over the network with each client request or server response without a need to create special facade models for transferring these limited subsets of the model data Entity filtering feature allows you to define your own entity filtering rules for your entity classes based on the current context e g matched resource method and keep these rules in one place directly in your domain model With Jersey entity filtering facility it is also possible to assign security access rules to entity classes properties and property accessors We will first explain the main concepts and then we will explore the entity filtering feature topics from a perspective of basic use cases e Section 18 3 Using custom annotations to filter entities
367. 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 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 142 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 asyncRespo
368. on json application xml deal public WebResourceList getListOfPrinters T2 13 GET Path jMakiTable 14 Produces application json 15 public PrinterTableModel getTable 16 17 GET Path jMakiTree 18 Produces application json 19 public TreeModel getTr O 20 21 GET Path ids printerid 22 Produces application json application xml 23 public Printer getPrinter PathParam printerid String printerId 24 25 PUT Path ids printerid 26 Consumes application json application xml 27 public void putPrinter PathParam printerid String printerId Printer p 28 29 DELETE Path ids printerid 30 public void deletePrinter PathParam 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 GET http jax rs
369. 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 application xml with generic type lt Object gt 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 othe
370. 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 container factories supported in Jersey Test Framework e Jersey provides 2 different test container factories based on Grizzly The GrizzlyTestContainerFactory creates a container that can run as a light weight plain HTTP container Almost all Jersey tests are using Grizzly HTTP test container factory Second factory is GrizzlyWebTestContainerFactory that is Servlet based and supports Servlet deployment context for tested applications This factory can be useful when testing more complex Servlet based application deployments lt dependency gt lt groupid gt org glassfish jersey test framework providers lt groupId gt lt artifactId gt jersey test framework provider grizzly2 lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt e In 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 contai
371. ond example into the WADL contains element ext ended This means that this resource is not a part of a core RESTful API and is rather a helper resource If you need to mark any your own resource are extended annotate is with ExtendedResource https jersey java net apidocs 2 10 jersey org glassfish jersey server model ExtendedResource html Note that there might be methods visible in the default simple WADL even the user has not added them This is for example the case of MVC added methods which were added by ModelProcessor https jersey java net apidocs 2 10 jersey org glassfish jersey server model ModelProcessor html but are still intended to be used by the client to achieve their primary use case of getting formatted data 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 xml v http localhost 9998 country 15 We should see a WADL returned similar to this one 191 WADL Support Example 16 3 OPTIONS method returning WADL 1 lt xml version 1 0 encoding UTF 8 standalone yes gt 2 lt application xmlns http wadl dev java net 2009 02 gt 3 lt 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
372. onfigurable http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configurable html client server 114 Support for Common Media Type Representations Example 8 25 ContextResolver lt ObjectMapper gt Provider 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 DEFAULT cTypes Override public JAXBContext getContext Class lt gt objectType return types contains objectType context null Example 8 26 Building client with Jettison JSON feature enabled final Client client ClientBuilder newBuilder cregister JaxbContextResolver class No need to register this provider register JettisonFeature class build Example 8 27 Creating JAX RS application with Jettison JSON feature enabled Create JAX RS application final Application application new ResourceConfig packages org glassfish jersey examples jettison cregister JaxbContextResolver class No need to register this provider register JettisonFeature class 8 1 5 4 Examples 8 1 6 Jersey provides an JSON Jettison exam
373. onfiguration of the JAX RS application Configuration statistics about ExceptionMapper lt E extends Throwable gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext ExceptionMapper html execution ExceptionMapper and Statistics about produced responses Responses Resources and Uris groups contains monitoring statistics specific to individual resources Statistics in Resources are bound to the JAX RS resource Java classes loaded by the application Uris contains statistics of resources based on the matched application Uris one URI entry represents all methods bound to the particular URI e g resource exception As Jersey provides programmatic resource builders described in the chapter Programmatic API for Building Resources one Java resource class can be an endpoint for resource methods on many different URIs And also one URI can be served by method from many different Java classes Therefore both views are not to be compared 1 1 Instead they provide different loggical views on your JAX RS application This monitoring feature can also help when designing the JAX RS APIs as it provides nice view on available root application URIs Both logical views on the resources exposed by application share few common principles A single resource entry is always a set of resource methods which are available under the methods sub group 246 Monitoring and Diagnostics Statistics can be found in MBeans MethodTimes and RequestTi
374. onfiguration 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 https jersey java net apidocs 2 10 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 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 196 WADL Sup
375. onnector SET_ METHOD _WORKAROUND 6 https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnectorProvider html SET_METHOD_WORKAROUND The name of the property remains the same jersey config client httpUrlConnection setMethodWorkaround ClientProperties HITP_URL_CONNECTOR_FIX_LENGTH_STREAMING property that class as this property is specific to the connector instances created by HttpUrlConnectorProvider only The property has been also renamed to HttpUrlConnectorProvider USE_FIXED_LENGTH_STREAMING https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnectorProvider html USE_FIXED_LENGTH_STREAMING and the new property name is Jersey config client httpUrlConnector useFixedLengthStreaming org glassfish jersey grizzly connector GrizzlyConnector has been removed from the public API GrizzlyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey grizzly connector GrizzlyConnectorProvider html should be used to produce Grizzly Asynchronous HTTP Client connector instances instead Public constructor has been removed from the ApacheConnector https jersey java net apidocs 2 10 jersey org glassfish jersey apache connector ApacheConnector html API ApacheConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey apache connector ApacheConnectorProvider html should be used to provide Apache HTTP Client connector instances i
376. onpCallback public JaxbBean getSimpleJSONP return new JaxbBean jsonp And make two requests 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 2 10 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 SA XSource 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 pa
377. ons of the named body parts with the same name or nu11 if such a named body part is not present e 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 the 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 0 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 50 Use of FormDataParam annotation POST Consumes MediaType MULTIPART_FORM_DATA_TYP public String postForm DefaultValue
378. ontext 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 Context 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 tS To summarize 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 45 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 GET POST can contain parameters that can be injected when the resource method is executed Can be used in any scope Sub resource
379. or 64 Application Deployment and Runtime Environments 4 9 OSGi 4 9 1 OSGi support has been added to the Jersey version 1 2 Since then you should be able to utilize standard OSGi means to run Jersey based web applications in OSGi runtime as described in the OSGi Service Platform Enterprise Specification Jersey is currently compatible with OSGi 4 2 0 the specification could be downloaded from here http www osgi org Download Release4V42 The two supported ways of running an OSGi web application are e WAB Web Application Bundle e HTTP Service WAB is in fact just an OSGified WAR archive HTTP Service feature allows you to publish Java EE Servlets in the OSGi runtime Two examples were added to the Jersey distribution to depict the above mentioned features and show how to use them with Jersey e WAB Example https github com jersey jersey tree 2 10 examples osgi helloworld webapp e HTTP Service example https github com jersey jersey tree 2 10 examples osgi http service Both examples are multi module maven projects and both consist of an application OSGi bundle module and a test module The tests are based on PAX Exam http ops4j1 jira com wiki display PAXEXAM3 Pax Exam framework Both OSGi examples also include a readme file containing instructions how to manually run the example applications using Apache Felix http felix apache org site index html framework The rest of the chapter describes how to r
380. os 239 20 2 Request event listener venies ee ie E ed eee ela E A EA T ERO ES EAEE 240 20 3 Event listener Test TESOULCE ranno e E paN AE E E EEEa EAN R ER 240 20 4 Injecting MonitoringStatistics ssssnsssssorisir ensesine enia E E S 243 20 5 Summary level Messages rinnet ann ae an E a E e EEA ERER 250 20 6 On demand request snippet of MVC JSP forwarding seesseseieseesresrsrrerrsrrerreresreersrreres 251 25 1 Jersey 1 reloader implementation 0 0 0 0 eee cece cece eee ceeeceeeceeeca ceca sean EEP En a Epe 283 25 2 Jersey 1 reloader repistration se scc ees oe ech oe tb dennech van seek ese eg besten geah OE A RO S 283 25 3 Jersey 2 reloader implementation sones esere A E cece sean eeae eens EEAS 284 25 4 Jersey 2 reloader registration saine cece cece ce ee Ee ence E E ri E seas esas N ESS 284 xiii Preface This is user guide for Jersey 2 10 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 https jersey java net apidocs 2 10 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 htt
381. ot initialize the Oauth providers with a single fixed AccessToken https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth1 AccessToken html instance In such case you would need to specify a token for every single request in the request properties Key names and API documentation of these properties can be found in OAuthiClientSupport Using this approach you can have a single OAuth enabled instance of a JAX RS Client or WebTarget http jax rs spec java net nonav 2 0 apidocs javax ws rs client WebTarget html and use it to make authenticated requests on behalf of multiple users Note that you can use the aforementioned request properties even if the feature has been initialized with an AccessToken to override the default access token information for particular requests even though it is probably not a common use case 184 Security The following code shows how to set an access token on a single request using the Jersey OAuth properties Example 15 11 Specifying Access Token on a Request 1 Response resp 2 client target http my serviceprovider org rest foo bar 3 request 4 property OAuth1ClientSupport OAUTH_PROPERTY_ACCESS_TOKEN storedToken 5 get OAuthlAuthorizationF1ow internally uses a Client instance to communicate with the OAuth server For this a new client instance is automatically created by default You can supply your instance of a Client to be used for the author
382. oupid gt org glassfish jersey connectors lt groupId gt lt artifactId gt jersey apache connector lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt lt dependency gt lt groupiId gt org glassfish jersey connectors lt groupId gt lt artifactId gt jersey jetty connector lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt Server side application on supported containers Apart for a standard JAX RS Servlet based deployment that works with any Servlet container that supports Servlet 2 5 and higher Jersey provides support for programmatic deployment to the following containers Grizzly 2 HTTP and Servlet JDK Http server Simple Http server and Jetty Http server This chapter presents only required maven dependencies more information can be found in Chapter 4 Application Deployment and Runtime Environments lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container grizzly2 http lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container grizzly2 servlet lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt lt dependency gt lt groupiId gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container jdk http lt artifactId gt lt version gt
383. ource 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 https jersey java net apidocs 2 10 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 http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientBuilder html factory methods Here s the most simple example
384. ource resource resourceBuilder build 30 registerResources resource w w w WN EF wa 158 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 htm1 or dire
385. ovider ina Jersey client instance 1 ClientConfig clientConfig new ClientConfig 2 clientConfig connectorProvider new GrizzlyConnectorProvider 3 Client client ClientBuilder newClient clientConfig 78 System setProperty sun net http allowRestricte Response response client target yourUri path header Access Control Request Method POST Client API Client accepts as as a constructor argument a Configurable instance Jersey implementation of the Configurable provider for the client is ClientConfig By using the Jersey ClientConfig you can configure the custom ConnectorProvider into the ClientConfig The GrizzlyConnectorProvider is used as a custom connector provider in the example above Please note that the connector provider cannot be registered as a provider using Configurable register Also please note that in this API has changed in Jersey 2 5 where the ConnectorProvider SPI has been introduced in order to decouple client initialization from the connector instantiation Starting with Jersey 2 5 it is therefore not possible to directly register Connector instances in the Jersey ClientConfig https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientConfig html The new ConnectorProvider SPI must be used instead to configure a custom client side transport connector 5 6 Using client request and response filters Filtering requests and responses can provide useful lower level con
386. ows to broadcast individual events to multiple clients A simple broadcasting implementation is shown in the following example 169 Server Sent Events SSE Support Example 14 3 Broadcasting SSE messages Tie oh ie 2 import org glassfish jersey media sse SseBroadcaster 3 4 5 Singleton 6 Path broadcast 7 public static 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 message has been 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
387. oyed application lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt if your container implements Servlet API older than 3 0 use jersey cont lt artifactId gt jersey container servlet lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt lt Required only when you are using JAX RS Client gt lt dependency gt lt grouplid gt org glassfish jersey core lt grouplId gt lt artifactId gt jersey client lt artifactId gt lt version gt 2 10 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 or jetty 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 lt grouplid gt org glassfish jersey core lt grouplId gt lt artifactId gt jersey client lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt Currently available connectors lt dependency gt lt groupid gt org glassfish jersey connectors lt groupId gt lt artifactId gt jersey grizzly connector lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt 13 Modules and dependencies 2 3 4 lt dependency gt lt gr
388. p java net jira browse JERSEY under docs component Please make sure to specify the version of the Jersey User Guide where the error has been spotted by selecting the proper value for the Affected Version field Text formatting conventions First mention of any Jersey and JAX RS API component in a section links to the API documentation of the referenced component Any sub sequent mentions of the component in the same chapter are rendered using a monospace font Emphasised font is used to a call attention to a newly introduce concept when it first occurs in the text In some of the code listings certain lines are too long to be displayed on one line for the available page width In such case the lines that exceed the available page width are broken up into multiple lines using a at the end of each line to indicate that a break has been introduced to fit the line in the page For example This is an overly long line that might not fit the available page width and had to be broken into multiple lines This line fits the page width Should read as This is an overly long line that might not fit the available page width and had to This line fits the page width xiv 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 implem
389. p 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 non 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
390. pabilities 25 5 2 New deprecated APIs internal classes Following APIs were deprecated e org glassfish jersey message internal HttpDateFormat method getPreferedDateFormat has been marked as deprecated due to typo in the name New method getPreferredDateFormat should be used instead 25 5 3 Removed deprecated APIs Following already deprecated APIs were removed e org glassfish jersey client filter HttpBasicAuthFilter and org glassfish jersey client filter HttpDigestAuthFilter use HttpAuthenticationFeature https jersey java net apidocs 2 10 jersey org glassfish jersey client authentication HttpAuthenticationFeature html instead param 1 e org glassfish jersey apache connector ApacheClientProperties HTTP_PARAMS use org glassfish jersey apache connector ApacheClientProperties REQUEST_CONFIG instead org glassfish org glassfish org glassfish use corresponding ClientProperties https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html instead jersey apache connector ApacheClientProperties PROXY_US jersey apache connector ApacheClientProperties PROXY_URI ERNAME jersey apache connector ApacheClientProperties PROXY_PASSWOR org glassfish jersey server validation ValidationConfig setMessageInterpolator org glassfish jersey server validation ValidationConfig setTraversableResol
391. pe 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 to 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 0 apidocs javax ws rs ext MessageBodyWriter 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
392. pidocs 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 Injection 1 Path id d 2 public class InjectedResource 3 Injection onto field 4 DefaultValue q QueryParam p 9 private String p 6 7 Injection onto constructor parameter 8 public InjectedResource PathParam 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 17 public String get PathParam sub id String id 18 19 Injection onto sub resource locator method parameter 20 Path sub id 2I public SubResource getSubResource PathParam sub id String id 22 23 Injection using bean setter method 24 HeaderParam X header 29 public void setHeader String header 26 There are some restrictions when injecting on to resource cla
393. plain public static class Resource private int i 1 GET public int get return itt Override protected Application configure return new ResourceConfig Resource class Test public void first throws Exception test 1 Test public void second throws Exception test 1 private void test final Integer expected final Response response target request get assertEquals response getStatus 200 assertEquals response readEntity Integer class expected If you need more complex setup of your test you can achieve this by directly extending the JerseyTestNg https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTestNg html class create setup teardown methods suited to your needs and provide a strategy for storing and handling a test container client instance see JerseyTestNg configureStrategy TestNgStrategy method 265 xtends JerseyTestNg ContainerPerMethodT Jersey Test Framework 23 4 Advanced features 23 4 1 JerseyTest Features JerseyTest provide enable _ https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html enable java lang String forceEnable _ https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html forceEnable java lang String and disable https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html disable java lan
394. ple https github com jersey jersey tree 2 10 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 e Resource method which should return wrapped JSON needs to be annotated with JSONP https jersey java net apidocs 2 10 jersey org glassfish jersey server JSONP html annotation e MessageBodyWriter lt T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html for appl ication json media type which also accepts the return type of the resource method needs to be registered see JSON section of this chapter e User s request has to contain Accept header with one of the JavaScript media types defined see below 115 Support for Common Media Type Representations 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 28 Simplest case of using JSONP 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 Example 8 29 JaxbBean for JSO
395. plication new ResourceConfig The line below 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 2 10 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 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 10 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 10 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 2 3 2 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
396. port 16 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 the APIs of WadlGenerator https jersey java net apidocs 2 10 jersey org glassfish jersey server wadl W adlGenerator html Wad GeneratorConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server wad1 config Wad GeneratorConfig html as well as any related classes The API changes may impact your code if you are using a custom Wad1Generator or plan to implement one 197 Ch
397. posure of monitoring MXBeans causes that also the calculation of MonitoringStatistics is automatically enabled as the exposed MXBean statistics are extracted from MonitoringStatistics The easiest way is to browse the MXBeans in the JConsole Open the JConsole JAVA_HOME bin jconsole Then connect to the process where JAX RS application is running server on which the application is running Switch to a MBean tab and in the MBean tree on the left side find a group org glassfish jersey All deployed Jersey applications are located under this group If you don t see such this group then MBeans are not exposed check the configuration property and logs if they not contain any exceptions or errors The following figure is an example of an output from the JConsole 245 Monitoring and Diagnostics Java Monitoring amp Management Console es pid 4599 com intellif rt execution application AppMain com intellij rt execution junit JUnitStarter ide Overview Memory Threads Classes VMSummary MBeans gt JMimplementation Attribute values gt com sun management gt java lang gt java util logging AverageTime ms 15m v org glassfish jersey AverageTime ms 15s v myApplication AverageTime ms _ 1h v Global AverageTime ms _ 1m gt AllRequestTimes AverageTime ms 1s gt Configuration AverageTime ms total gt ExceptionMapper MaxTime ms 15m gt Responses MaxTime ms 15s Resources MaxTime ms 1h gt
398. pp 237 Chapter 20 Monitoring and Diagnostics 20 1 Monitoring Jersey Applications 20 1 1 Introduction Important Jersey monitoring support has been released as a beta release in Jersey 2 1 version As such the exposed monitoring public APIs and functionality described in this section may change in the future Jersey releases Jersey provides functionality for monitoring JAX RS Jersey applications Application monitoring is useful in cases when you need to identify the performance hot spots in your JAX RS application observe execution statistics of particular resources or listen to application or request lifecycle events Note that this functionality is Jersey specific extension to JAX RS API Jersey monitoring support is divided into three functional areas Event Listeners Monitoring Statistics JMX MBeans with statistics All monitoring related APIs Event listeners allow users to receive and process a predefined set of events that occur during a application lifecycle such as application initialization application destroy as well as request processing lifecycle events request started resource method finished exception thrown etc This feature is always enabled in Jersey server runtime and is leveraged by the other monitoring features Jersey can be configured to process lifecycle events in order to expose a wide range of runtime monitoring statistics to the end user The statistics are accessible tro
399. print model ps print viewable getModel toString ps printin Example 19 14 Registering custom TemplateProcessor https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc spi TemplateProcessor html new ResourceConfig register MyTemplateProcessor class Further configuration of ResourceConfig register 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 provided by Jersey you will need to add the base jersey mvc https jersey java net project info 2 10 jersey project jersey mvc dependencies html module into the list of your dependencies lt dependency gt 236 MVC Templates lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey mvc lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt 19 8 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 2 10 examples bookstore weba
400. ps jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring RequestEventListener html for listening to events of request processing Only the first type App icationEvent Listener can be directly registered as an application wide provider The Request returned from the Appli Event Listener is designed to be specific to every request and can be only cationEventListener as such Let s start with an example The following examples show simple implementations of Jersey event listeners as well as a test JAX RS resource that will be monitored Example 20 1 Application event listener 1 public class MyApplicationEventListener 2 implements ApplicationEventListener 3 private volatile int requestCnt 0 4 5 Override 6 public void onEvent ApplicationEvent event 7 switch event getType 8 case INITIALIZATION_FINISHED 9 System out printlin Application 10 event getResourceConfig getApplicationName FI was initialized 12 break 13 case DESTROY_FINISHED 14 System out println Application 15 event getResourceConfig getApplicationName destroyed 16 break 1S7 18 19 20 Override 2t public RequestEventListener onRequest RequestEvent requestEvent 22 requestCntt 23 System out println Request requestCnt started 24 return the listener instance that will handle this re
401. quest 25 return new MyRequestEventListener requestCnt 26 ZF 239 Monitoring and Diagnostics Example 20 2 Request event listener 1 public class MyRequestEventListener implements RequestEventListener 2 private final int requestNumber 3 private final long startTime 4 5 public MyRequestEventListener int requestNumber 6 this requestNumber requestNumber 7 startTime System currentTimeMillis 8 9 10 Override 11 public void onEvent RequestEvent event 12 switch event getType 13 case RESOURCE_METHOD_START 14 System out println Resource method 15 event getUriInfo getMatchedResourceMethod 16 getHttpMethod T7 started for request requestNumber 18 break 19 case FINISHED 20 System out println Request requestNumber 21 finished Processing time 22 System currentTimeMillis startTime ms 23 break 24 25 26 Example 20 3 Event listener test resource 1 Path resource 2 public class TestResource 3 GET 4 public String getSomething 5 return get 6 7 8 POST 9 public String postSomething String entity 10 return post 11 12 Once the listeners and the monitored resource is defined it s time to initialize our application The following piece of code shows a ResourceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html
402. r example to set a different class loader Example 8 37 Planet JA XBContextProvider 1 Provider 2 public class PlanetJAXBContextProvider implements ContextResolver lt JAXBContext gt 3 private JAXBContext context null 4 5 public JAXBContext getContext Class lt gt type 6 if type Planet class 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 P 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 121 Support for Common Media Type Representations Example 8 38 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
403. r 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 MessageBodyWriter 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 secondary 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 r
404. rameter Lets say we want to test this feature and we have helloworld example https github com jersey jersey tree 2 10 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 117 Support for Common Media Type Representations 8 2 2 Example 8 31 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 Ly 18 19 POST 20 Path Document 21 public Document getDocument Document document 22 return document 23 OAarATNA OB WN EF Ne 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 lt test gt You can create JAX RS client to do that or use some other tool for example curl curl v http localhost 8080 base helloworld StreamSource d lt test gt You should get exactly the same XML from our service as is present in the request in this case XML headers
405. rceConfig https jersey java net apidocs 2 10 jersey org glassfish jersey server ResourceConfig html as input parameter should be used instead Typical use cases should not be affected by this change Method registerAdditionalBinders on _ ApplicationHandler _ https jersey java net apidocs 2 10 jersey org glassfish jersey server ApplicationHandler html has been removed from the public API Please use the specific ApplicationHandler constructor that accepts custom HK2 binders instead Several configuration properties were renamed especially those having client and server versions along with the common version in CommonProperties Please see following table for complete reference 273 Migration Guide Table 25 1 List of changed configuration properties Constant Old value Jersey 2 7 and before New value Jersey 2 8 https jersey java net apidocs 2 10 jersey org glassfish jersey client ServerProperties FEATURE_AU https jersey java net apidocs 2 10 jersey org glassfish jersey server ClientProperties FEATURE_AUT BISCOMERY gDESABDbE eAbrtsotsiesc cocantyLoe dierent ClientProperties html FEATURE_AUTO_DISCOVER Y_DISABI Ferd SCORER Yg DASABBEe AttteotsicsccomnyL epcrenere r ServerProperties html FEATURE_AUTO_DISCOVERY_DISABLE di LE di ClientProperties JSON_PROCES https jersey java net apidocs 2 10 jersey org glassfish jersey client SING REA BUREGDESABbE e J
406. representations using the In ject Link annotation on entity class fields The Jersey runtime is responsible for injecting the appropriate URI into the field prior to serialization by a message body writer E g consider the following resource and entity classes Path widgets public class WidgetsResource GET public Widgets get return new Widgets public class Widgets InjectLink resource WidgetsResource class URI uj After a call toWidgetsResource get the Jersey runtime will inject the value context widgets 1 into the returned Wi dgets instance If an absolute URI is desired instead of an absolute path then the annotation can be changed to Inject Link resource WidgetsResource class style ABSOLUTE lt The above usage works nicely when there s already a URI template on a class that you want to reuse If there s no such template available then you can use a literal value instead of a reference E g the following is equivalent to the earlier example Inject Link value widgets style ABSOLUTE l Where context is the application deployment context 154 Declarative Hyperlinking 12 3 12 4 12 5 Binding Template Parameters Referenced or literal templates may contain parameters Two forms of parameters are supported e URI template parameters e g widgets id where id represents a variable part of the URI e EL expressions e g widgets instance id
407. rg glassfish jersey CommonProperties html METAINF_SERVICES_LOOKUP_DISABLE property There is a client server counter part that only disables the feature on the client or server respectively ClientProperties METAINF_SERVICES_LOOKUP_DISABLE _ https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html METAINF_SERVICES_LOOKUP_DISABLE ServerProperties METAINF_SERVICES_LOOKUP_DISABLE _ https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html4METAINF_SERVICES_LOOKUP_DISABLE As in all other cases the client server specific properties overrides the value of the related common property when set For example following code snippet disables service provider lookup and manually registers implementations of different JAX RS and Jersey provider types ContainerRequestFilter _ http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerRequestFilter html Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature html _ ComponentProvider __ https jersey java net apidocs 2 10 jersey org glassfish jersey server spi ComponentProvider html and ContainerProvider https jersey java net apidocs 2 10 jersey org glassfish jersey server spi ContainerProvider html Example 4 3 Registering SPI implementations using ResourceConfig ResourceConfig resourceConfig new ResourceConfig MyResource class resourceConfig register org glas
408. rincipal getName 11 12 176 Security 15 1 1 1 Initializing Security Context with Servlets As described above the SecurityContext by default if not overwritten by a request filter only exposes security information from the underlying container In the case you deploy a Jersey application in a Servlet container you need to configure the Servlet container security aspects lt security constraint gt lt auth constraint gt and user to roles mappings in order to be able to secure requests via calls to to the JAX RS SecurityContext 15 1 1 2 Using Security Context in Container Request Filters The SecurityContext can be directly retrieved from ContainerRequestContext http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerRequestContext html via get SecurityContext method You can also replace the default SecurityContext ina request context with a custom one using the set SecurityContext SecurityContext method If you set a custom SecurityContext instance in your ContainerRequestFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs container ContainerRequestFilter html this security context instance will be used for injection into JAX RS resource class fields This way you can implement a custom authentication filter that may setup your own SecurityContext to be used To ensure the early execution of your custom authentication request filter set the filter priority to AUTHENTI
409. rmation about host and port during the test execution mvn test Djersey test host myhost org Djersey config test container port 8080 23 4 3 Test Client configuration Tests might require some advanced client configuration This is possible by overriding configureClient ClientConfig clientConfig https jersey java net apidocs 2 10 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 MessageBody Writer lt T gt 266 Jersey Test Framework http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter html s or enabling additional features 23 4 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 _ https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html getLastLoggedRecord and JerseyTest getLoggedRecords https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html getLoggedRecords methods Note that this feature is not enabled by default see TestProperties RECORD_LOG_LEVEL https jers
410. roblem 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 lt 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 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 wad1 resource is deployed too To override this default behavior and disable WADL generation in Jersey setup the c
411. ronous Services and Clients ce cececceecceece ence sossa seca EENE e a NEE p RS SS 141 10 1 Asynchronous Server APE sirean tiie asst ee ince haa OS eee a E S 141 10 1 1 Asynchronous Server side Callbacks 20 0 0 cece ieee cee cee ceeeceeeeneeeueena sean eeues 143 101 2 Chunked Output iic cdots de a sched ieyten thn seine iv opee E ioeeds N a sevens 145 10 2 Chent AR erse n es vee sueny setters debates ph E yates geebs AAO on uedeu ss Sunde EE E ESENES 147 10 2 1 Asynchronous Client Callbacks 2 0 0 0 ee cece eee nece eee eeeeeeseeeeeeeeneeeaes 147 1022 2 Chunked inputs oerni eeen td cas Pou sasweueeed a e aI E I toads a 149 Te UR Us sand Laks osc saute cin eee StS tee A T See I REE ISLS a Sac te oe 151 PLAS Building URIS 505 dncn ves esisqutetoessiees dsssb ses tnst boman sens iebey ome N E EERE E 151 11 2 Resolve and RelativiZe mep moset deve cs fee das oe E eben vx doe Gan ce N OE sweets 152 WU Se WEI 2205 casvou pees dean kote a a baduecaess eel es Meee taue a ETNE 152 12 Declarative Hy perl kins cecenii e tered E E pects E SES EOE S R E EE ts 154 12 A De penden yne o a a E Bhs EE NEE A E E ee hols 154 12 2 Exnks in Representations s Hisis e a E dk eine ee be R eh ee E 154 12 3 Binding Template Parameters iin ea acess yenewtyeu E a ern ea 155 12 4 Conditional Link Injection rse cece een cece ee cece cece een E RS ANE 155 12 5 Eist of Link Inj CCH OD merry a EE A EER gbapteun dst EEEE E 155 12 6 Link
412. rreerereeereees 78 35 Closing COMMECHIONS neser ers o or secede E E EEEE EEE rE E EE EE EEEE EVE STEES 79 5 6 ServiceLocatorClientProvider example sisi irsicsoss rrii ss cece eee ece eee eeceeeceeeseeeeaeeeaeeea eeu eeueeegs 80 1X Jersey 2 10 User Guide 6 1 Using File with a specific media type to produce a response cee cece eeeeeeceeeceeeeeeeeeeees 84 6 2 Returning 201 status code and adding Location header in response to POST request 85 6 3 Adding an entity body to a custom response 0 1 0 cece eee ee eee cece cece cence neeeeeeeeeeeeeeeeeaees 85 6 4 Throwing exceptions to control response eee eee cece cee ce ee ceeeea ceca cena een eeaeeeneeeeneeenes 85 6 5 Application specific exception implementation 0 cece eece ee ce ee ceeece ence eeeeeeeeeeeeeeaees 86 6 6 Mapping generic exceptions tO responses ee eect ce ee ce ee ce ee ce eeceeeceeeceeeeaeeeaeeea seas eene cogs 86 6 7 Conditional GET SUuppOlt 4 s23 lt odese loss edwes tov e toeg tee a dada Seb suans yeh A E E 87 7l Example resource class rn ae ki i beec oe oie ced phen eh ec SiS ees Mires E a eects hens 90 1 2 My Bean Entity Class o3 sos sees seaesestoes EREE E EER dhs pwangeatwsd geen ENE 90 7 3 MessageBodyWriter example ir inne an cece ence ence E aE R sess seas eeu ceueeeneeeneees 91 7 4 Example of assignment of annotations to a response entity eee eee cee eee eens ce eeee neon ees 92 7
413. rs 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 WriterInterceptor 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 client request filters 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 c
414. rsey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html JSON_PROCESSING_FEATURE_DISABLE When set disables configuration of Json Processing JSR 353 feature CommonProperties MOXY_JSON_FEATURE_ DISABLE https jersey java net apidocs 2 10 jersey org glassfish jersey CommonProperties html HMOXY_JSON_FEATURE_DISABLE When set disables configuration of MOXy Json feature For each of these properties there is a client server counter part that is only honored by the Jersey client or server runtime respectively see ClientProperties https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html ServerProperties _ https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html When set each of these client server specific auto discovery related properties overrides the value of the related common property Note In case an auto discoverable mechanism in general or for a specific feature is disabled then all the features components and or properties registered by default using the auto discovery mechanism have to be registered manually 4 4 Configuring the Classpath Scanning Jersey uses a common Java Service Provider mechanism to obtain all service implementations It means that Jersey scans the whole class path to find appropriate META INF services files The class path scanning may be time consuming The more jar or war files on the classpath t
415. rvlet mapping gt ES lt servlet name gt org example MyApplication lt servlet name gt 16 lt url pattern gt myresources lt url pattern gt 17 lt servlet mapping gt 18 lt web app gt Note If your custom Application subclass is packaged in the war it defines which resources will be taken into account e Ifboth getClasses and getSingletons methods return an empty collection then ALL the root resource classes and providers packaged in the web application archive will be used Jersey will automatically discover them by scanning the war file e If any of the two mentioned methods getClasses or getSingletons returns a non empty collection only those classes and or singletons will be published in the JAX RS application Table 4 1 Servlet 3 Pluggability Overview Condition Jersey action Servlet Name web xml No Application Adds Servlet javax ws rs core Appserdettmapping is required subclass Application subclass No action Already defined Not required handled by existing Servlet Application subclass Adds Servlet FQN of the if no NOT handled by existing Application subclass ApplicationPath Servlet on the Application subclass then Servlet mapping is required 61 Application Deployment and Runtime Environments 4 7 3 Jersey Serviet container modules Jersey uses its own ServletContainer https jersey java net apidocs 2 10 jersey org glassfish jersey ser
416. s jersey java net project info 2 10 jersey project assemblies dependencies html Jersey examples shared assembly types bean validation webapp https jersey java net project info 2 10 jersey project webapp example parent bean validation webapp dependencies html Jersey Bean Validation JSR 349 example bookmark https jersey java net project info 2 10 jersey project webapp example parent bookmark dependencies html Jersey Bookmark example bookmark em https jersey java net project info 2 10 jersey project webapp example parent bookmark em dependencies html Jersey Bookmark example using EntityManager bookstore webapp https jersey java net project info 2 10 jersey project webapp example parent bookstore webapp dependencies html Jersey MVC Bookstore example cdi webapp https jersey java net project info 2 10 jersey project webapp example parent cdi webapp dependencies html Jersey CDI example clipboard https jersey java net project info 2 10 jersey project clipboard dependencies html Jersey clipboard example clipboard programmatic https jersey java net project info 2 10 jersey project clipboard Jersey programmatic resource API clipboard example 22 Modules and dependencies Jersey Examples programmatic dependencies html declarative linking https jersey java ne
417. s 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 282 Migration Guide Example 25 1 Jersey 1 reloader implementation 1 public class Reloader implements ContainerNotifier 2 List lt ContainerListener gt 1s 3 4 public Reloader 5 ls new ArrayList lt ContainerListener gt 6 7 8 public void addListener ContainerListener 1 9 ls add 1 10 de 12 public void reload 13 for ContainerListener 1 1s 14 l onReload 15 16 Tek 3 Example 25 2 Jersey 1 reloader registration 1 Reloader reloader new Reloader 2 resourceConfig getProperties put ResourceConfig PROPERTY_CONTAIN In Jersey 2 two interfaces are involved again but these have been re designed 1 org glassfish jersey server spi1 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 Prov
418. s 231 19 6 Supported templating engines 2 0 0 0 eee cece cence eecaeeca ceca eeea cena eeu eeneeenneeenees 232 19 6 12 Mustache sists techies tet bie auld eae ad ed a Stee 232 1956 2 Freem rk r 3 0 scaesisnawes gosy seus ass pedegdiensswanssdyee sated vemrtese beatae SEES SEERE 233 192673 JSR 2 ciy A E dana vor E E eset Na Pal aay Mi patna rota Meee eee 234 19 7 Writing Custom Templating Engines 0 cece cece eeceeeceeeceeeceeeeneeea esau eens eeaee 235 19 8 Other Examples ec2is vice iri eee hatte st EE E E E E eee a e e E tne sect 237 20 Monitoring and Dia SnOstics gespes deseesvansss E tune ss pyeeldeete sete suds veateen eeaese ESE ees 238 20 1 Monitoring Jersey Applications 2 0 0 0 0 cece cece c cence neces ceeeseeeeaeeeaeeea essa sean eeaes 238 20 VU Introduction ssi eian whe dovaiee caoune ver desaawel E ove shart sees E ANERE RARS 238 20432 Event Jeisteners sin fie teenie Riis eee ali Riso te ea eee ay 239 20 2 Tracing SUPPOLt orrore ar EREE ERS E E E EEE VRE AER ITE see EER unde beds 248 20 2 1 Configuration Options sesessseseseseeeessrestresrresterstterttertteretereresreeereeereeee 248 2022 2 Trame LOS peen e a aa E a ast e idee o A SEANAR 249 20 2 3 Configuring tracing support via HTTP request headers s ceeeceecceceereee 249 20 2 4 Format of the HTTP response headers eeeeeeeeseiesressressrrerrrsrrrerrrerres 249 20 23 Tracing Examples n enn a ena av sade E E R E ER EO
419. s active in any given context in order to process the model data in a certain way e g expose the detailed view We need to tell the server client runtime which entity filtering scopes we want to apply There are 2 ways how to do this for client side and 3 ways for server side e Out bound client request or server response programmatically created with entity filtering annotations that identify the scopes to be applied available on both client and server e Property identifying the applied scopes passed through Configuration http jax rs spec java net nonav 2 0 apidocs javax ws rs core Configuration html available on both client and server 218 Entity Data Filtering e Entity filtering annotations identifying the applied scopes attached to a resource method or class server side only When the multiple approaches are combined the priorities of calculating the applied scopes are as follows Entity annotations in request or response gt Property passed through Configuration gt Annotations applied to a resource method or class In a graph of domain model objects the entity filtering scopes are applied to the root node as well as transitively to all the child nodes Fields and child nodes that do not match at least a single active scope are filtered out When the scope matching is performed annotations applied to the domain model classes and fields are used to compute the scope for each particular component of the model If th
420. s 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 POST 2 public void post BeanParam 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 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 39 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 Produces applicati
421. s not part of a public API anymore and is is registered by a Jersey OAuth Feature http jax rs spec java net nonav 2 0 apidocs javax ws rs core Feature html The most important parts of the Jersey client OAuth API and SPI are explained here e OAuthIClientSupport _ https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth 1 OAuth1ClientSupport html The main class which contains builder methods to build features that enable the OAuth 1 support Start with this class every time you need to add any OAuth 1 support to the Jersey Client build an Authorization flow or initialize client to perform authenticated requests The class contains static method that returns instance of OAuth Builder https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth1 OAuth1Builder html and also the class defines request properties to influence behaviour of the authenticated request support e OAuth1AuthorizationFlow https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth1 OAuth1AuthorizationFlow html API that allows to perform the Authorization flow against 182 Security service provider Implementation of this interface is a class that is used as a standalone utility and is not part of the JAX RS client In other words this is not a feature that should be registered into the client e AccessToken https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth 1 Access
422. s 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 34 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 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 Pa
423. se 4 extensions to languages The property is used by UriConnegFilter https jersey java net apidocs 2 10 jersey org glassfish jersey server filter UriConnegFilter html https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties MEDIA_TYPE ServerProperties html MEDIA_T YPE_MAPPINGS IMAPPENGSonfig server ma PefifiesoeMmappings of URI extensions to media types The property is used by UriConnegFilter https jersey java net apidocs 2 10 jersey org glassfish jersey server filter UriConnegFilter html https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties METAINF_SERVKES LOOKUPIDICABEE di ServerProperties html METAINK_SERVICES_LOOKUP_DISABLE D asabkNe t a ME BAiNRisesticesk up lookup on server Default value is false https jersey java net apidocs 2 10 jersey org glassfish jersey server https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties MOXY_JSON_FEAA4 RE das ABLES erver di ServerProperties html4MOXY_JSON_FEATURE_DISABLE ServerProperties MONITORING S AS 5T1 Sn ENA BIGHD r n ServerProperties htmI MONITORING_STATISTICS_ENABLED Basabkewicconfigumtion of MOXy Json feature Default value is false thitouengthst adalcatation cof will be enable monitoring statistics enabled This will the possibility of injecting Mo
424. 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 mediaType MediaType method on the event Builder The media type together with the data type set by the data Class Object gt 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 headers 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 is serialized 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 annot
425. sed Entity Filtering using javax annotation security annotations 221 18 5 Entity Filtering based on dynamic and configurable query parameters 04 222 18 6 Defining custom handling for entity filtering annotations ceceeeeeeeeeeeeeeeee eee ee 223 18 7 Supporting Entity Data Filtering in custom entity providers or frameworks 223 18 8 Modules with support for Entity Data Filtering cece ceeecccseeeeeeeeeeeeeenneeeeees 225 18 9 Examples ooer aw Meet ane easel E E E Man Sunes sb NE A E denn Ee 225 193 MVC Templates n rnesa E EN R E sect ucstead ates cond E E TE ES 226 19 1 Viewable eony as a E e a a N NE ty Sea ge R N EE AN RN 226 19 2 Templates n e E E E A E E NEAN 227 19 2 1 Annotating Resource methods cece cece eee cn eee ee ce eeae cen eeneeeneeeeeeeees 227 19 2 2 Annotating Resource Classes cee ceee cece cece cneece cece cena cena eens eeneeeneeeeeeeeees 227 19 3 Absolute vs Relative template reference cece cece ence cece cece nce nee neeeneeeeneeeees 228 19 3 1 Relative template reference scsi i n r i a Ea E E a E 228 19 3 2 Absolute template referenc n ssis inosente enno AEEA Ee NEEE ERINA 229 19 4 Handling errors with MVC 000 i E E EEE EERE EENE ESS 229 19 4 1 MVC amp Bean Validation seh sen E e OEEO E EAE RER 230 19 5 Registration and Configuration essseessseesesreesrrrrsrrerrsrrerrrresrrressrerrsrrerrereerreee
426. server SSE API also contains a SseBroadcaster https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseBroadcaster html utility that provides a convenient way of grouping multiple Event Output 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 https jersey java net apidocs 2 10 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 EventSource https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventSource html and EventListener https jersey java net apidocs 2 10 jersey org glassfish jersey media sse EventListener html classes that further improve convenience of processing new inbound SSE events 14 4 Implementing SSE support in a JAX RS resource 14 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media 166 Server Sent Events SSE Support 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
427. server runtime as a standard provider The implementation will be used to create request and access token get consumer by consumer key etc You can either implement your provider or use default implementation provided by Jersey by DefaultOAuth1Provider https jersey java net apidocs 2 10 jersey org glassfish jersey server oauth 1 DefaultOAuth1Provider html e OAuth1ServerProperties https jersey java net apidocs 2 10 jersey org glassfish jersey server oauth1 OAuth1ServerProperties html properties that can be used to configure the OAuth 1 support 181 Security OAuth1Consumer https jersey java net apidocs 2 10 jersey org glassfish jersey server oauth 1 OAuth1Consumer html OAuth1Token _ https jersey java net apidocs 2 10 jersey org glassfish jersey server oauth 1 OAuth1Token html classes that contain consumer key request and access tokens You need to implement them only if you implement also interface OAuth1Provider First step in enabling Jersey OAuth 1 support is to register a OAuth1ServerFeature instance initialized with an instance of OAuth1Provider Additionally you may configure the Request Token URI and Access Token URI the endpoints accessible on the OAuth server that issue Request and Access Tokens These endpoints are defined in the OAuth 1 specification and are contacted as part of the OAuth authorization flow Next when a client initiates the OAuth authorization flow the provided implementation of OAu
428. sesinessck cess Eoo EE PESER EEEE RES VIES EEE 56 4 10 Hooking up Jersey as a Servlet Filter 0 eee cece ee ceeeceeeea seca eena seas eeaneeneeennees 56 4 11 Configuring Jersey container Servlet or Filter to use custom Application subclass 57 4 12 Configuring Jersey container Servlet or Filter to use package scanning cess 57 4 13 Configuring Jersey container Servlet or Filter to use a list of classes cece eeee eee eens 58 4 14 Deployment of a JAX RS application using ApplicationPath with Servlet 3 0 58 4 15 Configuration of maven war plugin to ignore missing web XM eee ee ee eeee 59 4 16 Deployment of a JAX RS application using web xm1 with Servlet 3 0 00 eee 59 4 17 web xml of a JAX RS application without an Application subclass ee 60 ANB EE wosk a ieeeces a beth vies bes ost ia les dd eee sig tee On st lect iailon Mies Sa ANS 61 AMO es ochcteatorty ses vatvulsesuettasea phina ds sancaa sos E E AE 66 5 1 POST request with form parameters cee cee cece c cece ence ee ceeeeeeeca seca seca seas eeaeeeaeeeneeeneees 70 5 2 Using JAX RS Client APD cess c255 es sscas sysaagsshotacsesyotac ssa Suauss sestevsnesdevdasvetssssaedasedearneendeys 75 5 3 Using JAX RS Client API fluently oaeneeeeseneeseeseerersrerssrererererereresrerersreresrererererceseesee 76 5 4 Sending restricted headers with HttpUrlConnecCtor sessessreserrrsrrerrrrererressreres
429. sey org glassfish jersey server ServerProperties html MOXY_JSON_FEATURE_DISABLE ClientProperties MOXY_JSON_FEATURE_DISABLE __ https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html MOXY_JSON_FEATURE_DISABLE 105 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 https jersey java net apidocs 2 10 jersey org glassfish jersey moxy json MoxyJsonConfig html 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 https jersey java net apidocs 2 10 jersey org glassfish jersey moxy json MoxyJsonConfig html property java lang String java lang Object sets a property value for both Marshaller and Unmarshaller e MoxyJsonConfig marshallerProperty java lang String java lang Object https jersey java ne
430. sey client oauth2 ClientIdentifier html Identifier of the client issued by the Service Provider for the client Similar to ConsumerCredentials https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth 1 ConsumerCredentials html from OAuth 1 client support e OAuth2Parameters https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth2 OAuth2Parameters html Defines parameters that are used in requests during the authorization flow These parameters can be used to override some of the parameters used in different authorization phases e TokenResult https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth2 TokenResult html Contains result of the authorization flow One of the result values is the Access Token It can additionally contain the expiration time of the Access Token and Refresh Token that can be used to get new Access Token The principle of performing the authorization flow with Jersey is similar to OAuth 1 Check the example OAuth 1 Twitter Client example https github com jersey jersey tree 2 10 examples oauth client twitter 186 Security which utilizes Jersey client support for OAuth 2 to get Google Tasks of the user The application is a web application that uses redirection to forward the user to the authorization URI The following code is an example of how to build and use OAuth 2 authorization flow Example 15 13 Building OAuth 2 Authorization F
431. sey java net Defidesr catepathathat contains application specific resources and apidocs 2 10 jersey org providers If the property is set the 291 Configuration Properties Constant Value Description glassfish jersey server ServerProperties html PRO VIDE R_CLASSPATH specified packages will be scanned for JAX RS root resources and providers ServerProperties PROVIDER_PA https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html PRO VIDE GKAGHES config server pu R_PACKAGES Defidesr onactagaare packages that contain application specific resources and providers If the property is set the specified packages will be scanned for JAX RS root resources and providers ServerProperties PROVIDER_SC https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html PRO VIDE ANNING RE URSIVErver R_SCANNING_RECURSIVE package scanning Default value is true ServerProperties RESOURCE_V AJ d bad YOO DIS ABEErver https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html RESOURC eN E_VALIDATION_DISABLE Bssables eReadudae i validation Default value is false ServerProperties RESOURCE_V AJ d bag TOAD IGNORE BRRORG https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html RESOURC E_VALIDATIO
432. sey java net apidocs 2 10 jersey org glassfish jersey media multipart package summary html and others 101 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 below 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 e MOXy JSON binding support via MOXy is 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 3 Auto Discoverable Features e Java API for JSON Processing JSON P e Jackson e 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
433. sey monitoring is exposing quite a lot of information about the monitored application which might be viewed as problematic in some cases e g in production server deployments Tracing Support Apart from monitoring and collecting application statistics described in Section 20 1 Monitoring Jersey Applications Jersey can also provide tracing or diagnostic information about server side processing of individual requests This facility may provide vital information when troubleshooting your misbehaving Jersey or JAX RS application When enabled Jersey tracing facility collects useful information from all parts of JAX RS server side request processing pipeline PreMatchRequestFilter ResourceMatching RequestFilter ReadIntercept MBR Invoke ResponseFilter WritelIntercept MBW as well as ExceptionHandling 20 2 The collected tracing information related to a single request is returned to the requesting client in the HTTP headers of a response for the request The information is also logged on the server side using a dedicated Java Logger instance 20 2 1 Configuration options Tracing support is disabled by default You can enable it either globally for all application requests or selectively per request The tracing support activation is controlled by setting the jersey config server tracing type application configuration property The property value is expected to be one of the following e OFF tracing support is disab
434. sey org value is false glassfish jersey server ServerProperties html B V_SEND_ERROR_IN_RESPONSE ServerProperties FEATURE_AUT PAS OVERY DISABIds di Dasabkea fieatire antovkscpvery on https jersey java net server Default value is false apidocs 2 10 jersey org glassfish jersey server ServerProperties html FEATURH_ AUTO_DISCOVERY_DISABLE ServerProperties HTTP_METHOI j VERRHIK fig server ht Defacsh odOvenfigichtion of https jersey java net HTTP method overriding apidocs 2 10 jersey org This property is used glassfish jersey server by HttpMethodOverrideFilter ServerProperties html HTTP_MHRTHOD_OVERRIDE https jersey java net apidocs 2 10 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 289 Configuration Properties apidocs 2 10 jersey org glassfish jersey server https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html JSON_PROCESSING_FEATURE_ DISABLE ServerProperties LANGUAGE_MA PESGS config server laDefingeMamappns of URI ServerProperties html LANGUAGE_MAPPINGS Constant Value Description ServerProperties JSON_PROCESSIN s FEATURE DISABid gt di Disables s ooftfigneatmanirmg Json https jersey java net Processing JSR 353 feature Default value is fal
435. sfish jersey server filter UriConnegFilter cla resourceConfig register org glassfish jersey server validation ValidationFeatu resourceConfig register org glassfish jersey server spring SpringComponentProv resourceConfig register org glassfish jersey grizzly2 httpserver GrizzlyHttpCo resourceConfig property ServerProperties METAINF_SERVICES_LOOKUP_DISABLE true DOP WN EH Similarly in scenarios where the deployment model requires extending the Application subclass e g in all Servlet container deployments the following code could be used to achieve the same application configuration 52 Application Deployment and Runtime Environments Example 4 4 Registering SPI implementations using ResourceConfig subclass 1 public class MyApplication extends ResourceConfig 2 public MyApplication 3 register org glassfish jersey server filter UriConnegFilter class 4 register org glassfish jersey server validation ValidationFeature clas 5 register org glassfish jersey server spring SpringComponentProvider cl 6 register org glassfish jersey grizzly2 httpserver GrizzlyHttpContainer 7 property ServerProperties METAINF_SERVICES_LOOKUP_DISABLE true 8 9 4 5 Java SE Deployment Environments 4 5 1 HTTP servers Java based HTTP servers represent a minimalistic and flexible way of deploying Jersey application The HTTP servers are usually embedded in the application and conf
436. sh jersey media sse SseFeature html in your application The SseFeature 165 Server Sent Events SSE Support is a feature that can be registered for both the client and the server Since Jersey 2 8 the feature gets automatically discovered and registered when Jersey SSE module is put on the application s classpath The automatic discovery and registration of SSE feature can be suppressed by setting DISABLE_SSE https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseFeature html DISABLE_SSE property to true The behavior can also be selectively suppressed in either client or server runtime by setting DISABLE_SSE_ CLIENT https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseFeature html DISABLE_SSE_CLIENT or DISABLE_SSE_SERVER https jersey java net apidocs 2 10 jersey org glassfish jersey media sse SseFeature html DISABLE_SSE_SERVER property respectively SseFeature adds new supported entity representation Java types namely OutboundEvent https jersey java net apidocs 2 10 jersey org glassfish jersey media sse OutboundEvent html for the outbound server events and InboundEvent https jersey java net apidocs 2 10 jersey org glassfish jersey media sse InboundEvent html for inbound client events These types are serialized by OutboundEventWriter and de serialized by InboundEventReader There is no restriction for a media type used in individual event messages however the me
437. sists of a stateless EJB and a local interface used in Jersey 1 Local 2 public interface LocalEjb 3 GET 4 Produces text plain 5 6 7 8 public String getIt Stateless 63 Application Deployment and Runtime Environments 9 Path stateless 10 public class StatelessEjbResource implements LocalEjb algal Override 12 public String getIt 13 return Hi Stateless 14 15 Note Please note that Jersey currently does not support deployment of JAX RS applications packaged as standalone EJB modules ejb jars To use EJBs as JAX RS resources the EJBs need to be packaged either directly in a WAR or in an EAR that contains at least one WAR This is to ensure Servlet container initialization that is necessary for bootstrapping of the Jersey runtime 4 8 4 Java EE Servers 4 8 4 1 GlassFish Application Server As explained in 2 3 1 you don t need to add any specific dependencies on GlassFish Jersey is already packaged within GlassFish You only need to add the provided scoped dependencies to you project to be able to compile it At runtime GlassFish will make sure that your application has access to the Jersey libraries Started with version 2 7 Jersey allows injecting Jersey specific types into CDI enabled JAX RS components using the javax inject Inject annotation This covers also custom HK2 bindings that are configured as part of Jersey application The feature specifically en
438. solute template reference com fo00 Foo bar 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 where the model is still an instance of the same JAX RS resource class Foo 19 3 Absolute vs Relative template reference As discussed in the previous section both Template https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Template html and Viewable https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Viewable html provide means to define a reference to a template We will now discuss how these values are interpreted and how the concrete template is found 19 3 1 Relative template reference Relative reference is any path that does not start with a leading slash character i e index foo This kind of references is resolved into absolute ones by pre pending a given value with a fully qualified name of the last matched resource Consider the Example 19 3 Using Template on a resource class from the previous section the template name reference index is arelative value that Jersey will resolve to its absolute template reference 228 MVC Templates using a fully qualified class name of Foo more on resolving relative template name to the absolute one can be found in t
439. 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 adda Accept text plain HTTP header to our request The invocat ionBuilder 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 custom ClientRequestFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientRequestFilter html you can call get Property method o
440. source 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 395 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 PUT public Customer put Customer customer return customerService updateCustomer customer Path address public CustomerAddressSubResource getCustomerAddress PathParam id int return new CustomerAddressSubResource id Path additional info public Object getAdditionalInfoSubResource PathParam id int id return new CustomerAddressSubResource id public static class CustomerAddressSubResource private final int customerId private CustomerService customerService public CustomerAddressSubResource int customerId this customerId customerld 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 193 WADL Support The GET reque
441. sp https jersey java net project info 2 10 jersey project jersey mvc jsp dependencies html Writing Custom Templating Engines To add support for other custom templating engines into Jersey MVC Templating facility you need to implement the TemplateProcessor https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc spi 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 which case it is then possible to easily support mixing of multiple templating engines in a single application without conflicts 235 MVC Templates Example 19 13 Custom TemplateProcessor https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc spi 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 Override public void writeTo String templateReference Viewable viewable MediaType mediaType OutputStream out throws IOException final PrintStream ps new PrintStream out ps print path ps print templateReference ps printin ps
442. spec java net nonav 2 0 apidocs javax ws rs GET html or POST http jax rs spec java net nonav 2 0 apidocs javax ws rs POST html Such methods are referred to as sub resource locators The following example shows the method signatures for a root resource class and a resource class from the optimistic concurrency sample 40 JAX RS Application Resources and Sub Resources Example 3 18 Sub resource locators 1 Path item 2 public class ItemResource 3 Context UrilInfo urilnfo 4 5 Path content 6 public ItemContentResource 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
443. ss 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 GI 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 76 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 providers to group together multiple different extension providers and or configuration properties in order to simplify the registration
444. ssageBodyWriter 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 0 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 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
445. sserrsrerrrrrsrrerrsrrerrrrerereeen 36 3 10 Processing POSTed HTML form 0 00 0 cece ec cece cece cece ence en eeneeeeeceeesaeeeaeeea essa seas eeges 37 3 11 Obtaining general map of URI path and or query parameters cece cee cece eeee teen es 37 3 12 Obtaining general map of header parameters cece cece cece eee ceeeceeecaeeeaeeea sean eeueeeas 37 3 13 Obtaining general map of form parameters cece cee cece eee ce eecaeeca cena eens eeu eeneeeenees 37 3 14 Example of the bean which will be used as BeanParam 0 0 ceceec eee eeceeeeeeeee nese es 38 3 15 Injection of MyBeanParam as a method parameter 0 cece cc eecc ence eeceeeceeeeeeeeaeeenes 38 3 16 Injection of more beans into one resource methods 0 cece ce ee ce eeceeeee ence eeeeeeeeeeeaees 39 3 1 7 Sub resource methods 332 cscsicsste satborteus seisae seas estat E a E a atta see E dates E eaS 40 3 18 Sub resource locators sisa osien e ea AOE eee lok es costes desk ee esc todos Souci TEASE 41 3 19 Sub resource locators with empty path 2 0 0 0 cece cence cece eee e cen eeneeeeeeeeeeeeeeeeaees 41 3 20 Sub resource locators returning SUD tYPe 2 2 0 0 ce eee cece tec c ence ence ence eeceeeeeeeaeeea esau sean eeaes 42 3 21 Sub resource locators created from Classes cc cee eeseceeece ence ence eeeeeeceeeeaeeeaeeeaeeeu sean eeaes 42 3 22 Sub resource locators returning resource model
446. sses 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 44 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 9 GET 10 public String get 11 return query param param 12 13 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 C
447. ssionFactory class to HttpSession class 253 Custom Injection and Lifecycle Management 21 2 Note that we did not define any explicit injection scope for the new injection binding By default HK2 factories are bound in a HK2 PerLookup https hk2 java net apidocs org glassfish hk2 api PerLookup html scope which is in most cases a good choice and it is suitable also in our example To summarize the approach described above here is a list of steps to follow when implementing custom injection provider in your Jersey application e Implement your own HK2 Factory to provide the injectable instances e Use the HK2 Factory to define an injection binding for the injected instance via custom HK2 Binder e Register the custom HK2 Binder in your application ResourceConfig While the Fact ory based approach is quite straight forward and should help you to quickly prototype or even implement final solutions you should bear in mind that your implementation does not need to be based on factories You can for instance bind your own types directly while still taking advantage of HK2 provided dependency injection Also in your implementation you may want to pay more attention to defining or managing injection binding scopes for the sake of performance or correctness of your custom injection extension Important While the individual injection binding implementations vary and depend on your use case to enable your custom inje
448. st to http localhost 9998 application wadl will return the following WADL document 194 49 lt method gt 50 lt method name PUT id updateAddress gt 51 lt resource path sub gt 52 lt WADIdSnpport GET id getDeliveryAddress gt 53 lt response gt 54 lt method gt Example 16 5 More comptes WADL example WADL content 56 lt resource gt 57 lt resource gt 58 lt resource path application wadl gt 59 lt method name GET id getWadl gt 60 lt response gt 61 lt representation mediaType application vnd sun wadl xml gt 62 lt representation mediaType application xml gt 63 lt response gt 64 lt method gt 65 lt method name OPTIONS id apply gt 66 lt request gt 67 lt representation mediaType gt 68 lt request gt 69 lt response gt 70 lt representation mediaType text plain gt 71 lt response gt 72 lt method gt 73 lt method name OPTIONS id apply gt 74 lt request gt 75 lt representation mediaType gt 76 lt request gt 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 lt method name GET id geExternalGrammar gt 85 lt response gt 86 lt representation mediaType application xml gt 87 lt response gt 88 lt me
449. stName Email FormParam email String email The annotations NotNull and Email impose additional constraints on the form parameters firstName lastName and email The NotNu11 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 17 4 Constraint annotations on fields 202 Bean Validation Support Example 17 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 d
450. stache Property used to pass user configured MustacheFactory e MustacheMvcFeature ENCODING jersey config server mvc encoding mustache Property used to configure a default encoding that will be used if none is specified in Produces http jax rs spec java net nonav 2 0 apidocs javax ws rs Produces html annotation If property is not defined the UTF 8 encoding will be used as a default value Maven users can find this module at coordinates lt dependency gt lt grouplid gt org glassfish jersey ext lt grouplId gt lt artifactId gt jersey mvc mustache lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt and for non Maven users the list of dependencies is available at jersey mvc mustache https jersey java net project info 2 10 jersey project jersey mvc mustache dependencies html 19 6 2 Freemarker An integration module for Freemarker http freemarker org based templating engine Freemarker template processor resolves absolute template references to processable template references represented as Freemarker templates as follows Procedure 19 2 Resolving Freemarker template reference 1 if the absolute template reference does not end in ft 1 append this suffix to the reference and 2 if ServletContext getResource Class getResource or File existsreturns a non null value for the reference then return the reference as the processable template reference otherwise return nu11 to in
451. t 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 https jersey java net apidocs 2 10 jersey org glassfish jersey 167 Server Sent Events SSE Support media sse EventOutput html an extension of generic Jersey ChunkedOutput https jersey java net apidocs 2 10 jersey org glassfish jersey server ChunkedOutput html API for output chunked message processing Note If you are not familiar with ChunkedOutput and ChunkedInput see the Async 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 14 2 Simple SSE resource method the resource method creates a new thread that sends a sequence of 10 events There is a 1
452. t apidocs 2 10 jersey org glassfish jersey moxy json MoxyJsonConfig html marshallerProperty java lang String java lang Object sets a property value for Marshaller e MoxyJsonConfig unmarshallerProperty java lang String java lang Object https jersey java net apidocs 2 10 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 https jersey java net apidocs 2 10 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 setNamespaceSeparator In order to make MoxyJsonConfig visible for MOXy you need to create and register ContextResolver lt T gt in your client server code Example 8 8 Creating ContextResolver lt MoxyJsonConfig gt 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 moxyJsonConfig MoxyJsonConfig setNamespacePrefixMapper namespacePrefixMapper setNamespaceSeparator final ContextResolver lt MoxyJsonCo
453. t project info 2 10 jersey project declarative linking dependencies html Declarative Hyperlinking Jersey Sample entity filtering https jersey java net project info 2 10 jersey project entity filtering dependencies html Jersey Entity Data Filtering Example entity filtering security https jersey java net project info 2 10 jersey project entity filtering security dependencies html Jersey Entity Data Filtering Security Example entity filtering selectable https jersey java net project info 2 10 jersey project entity filtering selectable dependencies html Jersey Entity Data Filtering Selectable Example exception mapping https jersey java net project info 2 10 jersey project exception mapping dependencies html Jersey example showing exception mappers in action extended wad l webapp https jersey java net project info 2 10 jersey project webapp example parent extended wadl webapp dependencies html Extended WADL example flight management webapp https jersey java net project info 2 10 jersey project webapp example parent flight management webapp dependencies html Jersey Flight Management Demo Web Application Example freemarker webapp https jersey java net Jersey Freemarker example 23 Modules and dependencies Jersey Examples project info 2 10 jersey project webapp example parent
454. t T gt http jax rs spec java net nonav 2 0 apidocs javax ws rs ext MessageBodyWriter 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 response 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 145 Asynchronous Services and Clients Example 10 4 ChunkedOutput example 1 Path resource 2 public class AsyncResource 3 GET 4 public ChunkedOutput lt String gt 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 15 catch IOException e 16 IOException thrown when writing the V7 chun
455. t dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container grizzly2 http lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt Note Jersey uses Grizzly extensively in the project unit and end to end tests via test framework 4 5 1 3 Simple server Simple http www simpleframework org is a framework which allows developers to create a HTTP server instance and embed it within an application Again creating the server instance is achieved by calling a factory method from the jersey container simple http container extension module Simple framework HTTP container supports injection of Simple framework specific org simpleframework http Request and org simpleframework http Response instances into JAX RS and Jersey application resources and providers Example 4 7 Using Jersey with the Simple framework 1 URI baseUri UriBuilder fromUri http localhost port 9998 build 2 ResourceConfig config new ResourceConfig MyResource class 3 SimpleContainer server SimpleContainerFactory create baseUri config The necessary container extension module dependency in this case is lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container simple http lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt 54 Application Deployment and Runtime Environments
456. t options In this section we will focus on the basic deployment models available in any Servlet 2 5 or higher container In Servlet 2 5 environment you have to explicitly declare the Jersey container Servlet in your Web application s web xm1 deployment descriptor file Example 4 9 Hooking up Jersey as a Servlet 1 2 3 4 5 6 7 8 9 10 11 LZ 13 14 lt web app gt lt servlet gt lt servlet name gt MyApplication lt servlet name gt lt servlet class gt org glassfish jersey servlet ServletContainer lt servlet lt init param gt lt init param gt lt servlet gt lt servlet mapping gt lt servlet name gt MyApplication lt servlet name gt lt url pattern gt myApp lt url pattern gt lt servlet mapping gt 15 lt web app gt Alternatively you can register Jersey container as a filter Example 4 10 Hooking up Jersey as a Servlet Filter 1 2 3 4 5 6 7 8 9 10 11 12 13 14 lt web app gt lt filter gt lt filter name gt MyApplication lt filter name gt lt filter class gt org glassfish jersey servlet ServletContainer lt filter cl lt init param gt lt init param gt lt filter gt lt filter mapping gt lt filter name gt MyApplication lt filter name gt lt url pattern gt myApp lt url pattern gt lt filter mapping gt 15 lt web app gt The content of the lt init param gt element will vary depending on the way you decide to
457. t 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 17 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 200 Bean Validation Support Example 17 2 Using ValidationConfig to configure Validator Custom configuration of validation This configuration defines custom lt ul gt lt li gt 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 lt li gt lt ul gt public class ValidationConfigurationContextResolver implements ContextResolver lt Val Context private ResourceContext resourceContext Override 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 fin
458. t ry field values set by the endpoint and adjusts the reconnect delay accordingly using the last received ret ry field value as the new reconnect delay 174 Server Sent Events SSE Support In addition to handling the standard connection losses Jersey Event Source automatically deals with any HTTP 503 Service Unavailable responses received from the SSE endpoint that include a Ret ry After HTTP header with a valid value The HTTP 503 Retry After technique is often used by HTTP endpoints as a means of connection and traffic throttling Incasea HTTP 503 Retry After response is received in return to a connection request from SSE endpoint Jersey Event Source will automatically schedule a reconnect attempt and use the received Ret ry After HTTP header value as a one time override of the reconnect delay 175 Chapter 15 Security 15 1 Securing server 15 1 1 SecurityContext Security information of a request is available by injecting a JAX RS 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 javax ws rs core Context html annotation The injected security context instance provides the equivalent of the functionality available on HttpServletRequest http docs oracle com javaee 6 api javax servlet http HttpServletRequest html API The injected security context depends on the actual Jersey applic
459. tache templates Jersey extension module providing support for proxy based high level client API jersey servlet portability https jersey java net project info 2 10 jersey project jersey servlet portability dependencies html Library that enables writing web applications that run with both Jersey 1 x and Jersey 2 x servlet containers jersey spring3 https jersey java net project info 2 10 jersey project jersey spring3 dependencies html Jersey extension module providing support for Spring 3 integration jersey wadl doclet https jersey java net project info 2 10 jersey project jersey wad doclet 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 dependencies html Table 2 6 Jersey Test Framework Jersey Test Framework jersey test framework core https jersey java net project info 2 10 jersey project jersey test framework core dependencies html Jersey Test Framework Core Table 2 7 Jersey Test Framework Providers Jersey Test Framework Providers jersey test framework provider bundle https jersey java net project info 2 10 jersey project project jersey test framework Jersey Test Framework Providers Bundle 19 Modules and dependencies Jersey Test Framework
460. tatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ResourceStatistics html ResourceMethodStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ResourceMethodStatistics html ExecutionS tatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ExecutionStatistics html TimeWindowStatistics https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring TimeWindowStatistics html mostly configuration of the application response statistics eg response status codes and their count statistics of execution of resources resource classes or resource URIs statistics of execution of resource methods statistic of execution of a target resource request resource method statistics of execution time in specific interval eg executions in last 5 minutes Each time monitored target contains ExecutionStatistics So for example resource method contains execution Statistics of its execution Each ExecutionStatistics contains multiple TimeWindowStatistics Currently each ExecutionStatistics contains TimeWindowStatistics for these time windows e 0 unlimited gt all execution since start of the application e 1000 1s gt stats measured in last 1 second 15000 15s gt stats measured in last 15 seconds 60000 1min gt stats measured in last 1 minut
461. te Long id 4 3 private String name 6 7 private String description 8 9 ProjectDetailedView 10 private List lt Task gt tasks 11 12 ProjectDetailedView 13 private List lt User gt users 14 15 getters and setters 16 217 Entity Data Filtering Example 18 11 Annotated User 1 public class User 2 3 private Long id 4 5 private String name 6 7 private String email 8 9 UserDetailedView 10 private List lt Project gt projects 11 12 UserDetailedView 13 private List lt Task gt tasks 14 T5 getters and setters 16 Example 18 12 Annotated Task 1 public class Task 2 3 private Long id 4 5 private String name 6 7 private String description 8 9 TaskDetailedView 10 private Project project 11 T2 TaskDetailedView 13 private User user 14 15 getters and setters 16 As you can see in the examples above we have defined 3 separate scopes using ProjectDetailedView UserDetailedView and TaskDetailedView annotations and we have applied these scopes selectively to certain fields in the domain model classes Once the entity filtering scopes are applied to the parts of a domain model the entity filtering facility when enabled will check the active scopes when the model is being sent over the wire and filter out all parts from the model for which there is no active scope set in the given context Therefore we need a way how to control the scope
462. ted Once the project generation from a Jersey maven archetype is successfully finished you should see the new simple heroku webapp 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 Project resources are located under src main resources Project web application files are located under src main webapp Project test sources based on JerseyTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html are located under src test java Heroku system properties OpenJDK version are defined in system properties Lists of the process types in an application for Heroku is in Procfile The project contains one JAX RS resource class MyResouce and one resource method which returns simple text message To make sure the resource is properly tested there is also a end to end test case in MyResourceTest the test is based on JerseyTest https jersey java net apidocs 2 10 jersey org glassfish jersey test JerseyTest html from our Chapter 23 Jersey Test Framework Similarly to simple service webapp the project contains the standard Java EE web application web xml deployment descriptor under src main webapp WEB INF since the goal is to deploy the application in a Servlet container the appl
463. ted 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 printin response getStatus 6 String myBeanXml response readEntity String class 7 System out printin myBeanXm1 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 93 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 MyBea
464. th 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 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 3 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 35 JAX RS App
465. th1Provider will be invoked as to create new tokens get tokens and finally to store issued Access Token If a consumer already has a valid Access Token and makes Authenticated Requests with OAuth 1 Authorization information in the HTTP header the provider will be invoked to provide the OAuth1Token for the Access Token information in the header 15 3 1 2 Client Note OAuth client support in Jersey is almost identical for OAuth 1 and OAuth 2 As such this chapter provides useful information even even for users that use OAuth 2 client support To add support for OAuth into your Jersey client application add the following dependency to your pom xml lt dependency gt lt grouplid gt org glassfish jersey security lt grouplId gt lt artifactId gt oauthl client lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt As mentioned earlier there is no need to add a direct dependency to the signature module it will be transitively included OAuth 1 client support initially started as a code migration from Jersey 1 x During the migration however the API of was significantly revised The high level difference compared to Jersey 1 x OAuth client API is that the authorization flow is no longer part of a client OAuth filter Authorization flow is now a standalone utility and can be used without a support for subsequent authenticated requests The support for authenticated requests stays in the in the ClientRequestFilter but i
466. that is used to initialize the application please note that only Application Event Listener is registered as provider 1 ResourceConfig resourceConfig 2 3 new ResourceConfig TestResource class MyApplicationEventListener setApplicationName my monitored application Our example application now contains a simple resource Test Resource that defines resource methods for GET and POST and a custom MyApplicationEventListener event listener 240 Monitoring and Diagnostics The registered MyApplicationEventListener implements two methods defined by the ApplicationEventListener interface A method onEvent handles all application lifecycle events In our case the method handles only 2 application events initialization and destroy Other event types are ignored All application event types are defined in ApplicationEvent https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ApplicationEvent html Type The second method onRequest is invoked by Jersey runtime every time a new request is received The request event type passed to the method is always START If you want to listen to any other request lifecycle events for the new request you are expected to return an instance of RequestEventListener that will handle the request It is important to understand that the instance will handle only the request for which it has been returned from an ApplicationEventListener onRequest met
467. 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 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 it is 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 mod
468. ther 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 Fi lterForExampleCon filter is not part of 5 3 4 Identifying resource on WebTarget Let s assume we have awebTarget 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 as ithas been created from webTarget This mechanism allows you to share the common configuration of related resources typically hosted under the same URI root in our case represented by the webTarget instance while allowing for further configuration specialization based on the specific requirements of each in
469. thod gt 89 lt method name OPTIONS id apply gt 90 lt request gt 91 lt representation mediaType gt 92 lt request gt 93 lt response gt 94 lt representation mediaType text plain gt 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 195 WADL Support 16 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 returns 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 p
470. thods Injections into client providers filters interceptor are possible as long as the provider is registered as a class If the provider is registered as an instance then runtime will not inject the provider The reason is that this provider instance might be registered into multiple client configurations For example one instance of ClientRequestFilter http jax rs spec java net nonav 2 0 apidocs javax ws rs client ClientRequestFilter html can be registered to two Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html s To solve injection of a custom type into a _ client provider instance use ServiceLocatorClientProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client ServiceLocatorClientProvider html to extract ServiceLocator https hk2 java net apidocs org glassfish hk2 api ServiceLocator html which can return the required injection The following example shows how to utilize ServiceLocatorClientProvider Example 5 6 ServiceLocatorClientProvider example 1 public static class MyRequestFilter implements ClientRequestFilter 2 this injection does not work as filter is registered as an instance 3 Inject 4 private MyInjectedService service 5 6 Override th public void filter ClientRequestContext requestContext throws IOException 8 use ServiceLocatorClientProvider to extract HK2 ServiceLocator from 9 final ServiceLocator locator S
471. though it is less flexible and may require more resource methods to be created to cover all the alternative use case scenarios For example 219 Entity Data Filtering Example 18 14 ProjectsResource Entity filtering annotations on methods 1 Path projects 2 Produces application json 3 public class ProjectsResource orn auw ss 9 10 11 12 13 14 15 16 GI ET E public List lt Project gt getProjects GI return getDetailedProjects ET E Path detailed ProjectDetailedView public List lt Project gt getDetailedProjects return EntityStore getProjects To see how entity filtering scopes can be applied using a Configuration property see the Example 18 1 Registering and configuring entity filtering feature on server example When a Project model from the example above is requested in a scope represented by ProjectDetailedView entity filtering annotation the Project model data sent over the wire would contain e Project id name description tasks users e Task id name description e User id name email Or to illustrate this in JSON format a OANA OB WN FE Ne 10 11 12 13 14 15 16 17 18 LOT description Jersey is the open source under dual CDDL GPL license JA migm s Iz name Jersey tasks sii of description Entity Data Filtering wigah s al name ENT_FLT descript
472. tifactId gt jersey spring3 lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt The above module does not add any transitive dependency to Spring modules so you will need to add Spring 3 dependencies explicitly into your dependency list 22 2 Registration and Configuration To use capabilities of Jersey Spring 3 DI support in your JAX RS Jersey application you need to have the above mentioned module on your class path 22 3 Example To see an example of Spring DI support in Jersey refer to the Spring DI example https github com jersey jersey tree 2 10 examples helloworld spring webapp 260 Chapter 23 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 e pre configured client to access deployed application e support for multiple containers grizzly in memory jdk simple jetty e able to run against any external container e automated configurable traffic logging Jersey Test Framework is primarily based on JUnit but you can run tests usin
473. time tries to preemptively authenticate against this URI with latest successful authentication method To initialize the feature use static methods and builder of this feature Example of building the feature in Basic authentication mode 1 HttpAuthenticationFeature feature HttpAuthenticationFeature basic user s Example of building the feature in basic non preemptive mode 1 HttpAuthenticationFeature feature HttpAuthenticationFeature basicBuilder 2 nonPreemptive credentials user superSecretPassword build You can also build the feature without any default credentials 1 HttpAuthenticationFeature feature HttpAuthenticationFeature basicBuilder b In this case you need to supply username and password for each request using request properties 1 Response response client target http localhost 8080 rest homer contact 2 property HTTP_AUTHENTICATION_BASIC_USERNAME homer 3 property HTTP_AUTHENTICATION_BASIC_PASSWORD plswd745 get This allows you to reuse the same client for authenticating with many different credentials See javadoc of the HttpAuthenticationFeature https jersey java net apidocs 2 10 jersey org glassfish jersey client authentication HttpAuthenticationFeature html for more details 82 Chapter 6 Representations and Responses 6 1 Representations and Java Types Previous sections on Produces http jax rs spec java net nonav 2 0 apid
474. tion 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 86 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 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 UriInfo ui if dat
475. tly created and might not update since that time 20 1 2 2 1 Listening to statistics changes Statistics are not calculated for each request or each change Statistics are calculated only from the collected data in regular intervals for performance reasons for example once per second If you want to be notified about new statistics register an implementation of MonitoringStatisticsListener https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring MonitoringStatisticsListener html as one of your custom application providers Your listener will be called every time the new statistics are calculated and the updated statistics data will be passed to the listener method This is another way of receiving statistics See the linked listener API documentation for more information 20 1 2 3 Monitoring Statistics as MBeans Note Jersey examples contains Monitoring webapp example https github com jersey jersey tree 2 10 examples monitoring webapp which demonstrates usage of MBean statistics Jersey provides feature to expose monitoring statistics as JMX MXBeans In order to enable monitoring statistics MXBeans exposure the ServerProperties MONITORING_STATISTICS_MBEANS_ ENABLED __ https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html4MONITORING_STATISTICS_MBEANS_ENABLED must be set to true jersey config server monitoring statistics mbeans enabled tru Note that enabling ex
476. tml 152 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 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
477. to be handled using available response error ING_RESPONSE_ERRORS_ENAbjiiojs A 3 Client configuration properties List of client configuration properties that can be found in ClientProperties https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html class Table A 3 List of client configuration properties Constant Value Description ClientProperties AS YNC_THREADPOGly SIZHfig client asgysynchhonous Pthrehd i peol size https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html AS YNC_T HREADPOOL_ SIZE Default value is not set Supported with GrizzlyConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey grizzly connector GrizzlyConnectorProvider html only 293 Configuration Properties Constant Value Description https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html CHUNKEI ClientProperties CONNECT_TI https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientProperties html CONNECT ENCODING_SIZE TIMEOUT Betdey config client caReatt T timeoutt milliseconds Default value is 0 infinity ClientProperties CHUNKED_ENCQ DENG SIZRfig client cH hiektdn emadilimgs size Default value is not set interval in ClientProperties FEATURE_AUT https jers
478. to filter entities Entity filtering via annotations is based on an EntityFiltering https jersey java net apidocs 2 10 jersey org glassfish jersey message filtering EntityFiltering html meta annotation This meta annotation is used to identify entity filtering annotations that can be then attached to e domain model classes supported on both server and client sides and e resource methods resource classes only on server side An example of entity filtering annotation applicable to a class field or method can be seen in Example 18 9 ProjectDetailed View below Example 18 9 ProjectDetailed View pa 1 Target ElementType TYPE ElementType METHOD 2 Retention RetentionPolicy RUNTIME 3 Documented 4 EntityFiltering 5 6 7 8 public interface ProjectDetailedView ElementType FIELD Factory class for creating instances of code ProjectDetailedView ann 9 aif 10 public static class Factory 11 extends AnnotationLiteral lt ProjectDetailedView gt 12 implements ProjectDetailedView t3 14 private Factory 15 16 17 public static ProjectDetailedView get 18 return new Factory 19 20 21i 216 Entity Data Filtering Since creating annotation instances directly in Java code is not trivial it is a good practice to provide an inner annotation Factory class in each custom filtering annotation through which new instances of t
479. tor ResourceConfig rc new ResourceConfig rc addClasses rc addBinders new MyBinder j Jersey 2 0 dynamic binding public static class MyApplication extends Application 281 Migration Guide 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 dc request scope binding with specified custom annotation Injections addBinding Injections newBinder MyInjectablePerRequest class to MyInjectablePerRequest class qualifiedBy new MyAnnotationImpl in RequestScoped class dc commits changes dc commit Override public Set lt Class lt gt gt getClasses return 25 11 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 Container
480. tors and other useful methods See the following example of usage of MessageBodyWorkers 99 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 15 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 24 MyBean class MyBean class new Annotation 25 MediaType APPLICATION_XML_TYPE new MultivaluedHashMap lt String 26 baos 21 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 3
481. tters to avoid experiencing undefined behavior Events listeners should use the information for read only purposes only Use different techniques like filters interceptors or other providers to modify the processing of requests and applications Even though modification might be possible and might work as desired now your code is in risk of producing intermittent failures or unexpected behaviour for example after migrating to new Jersey version e If you do not want to listen to request events do not return an empty listener in the onRequest method Return nu11 instead Returning empty listener might have a negative performance impact Do not rely on JIT optimizing out the empty listener invocation code e If you miss any event type or any detail in the events let us know via Jersey user mailing list 20 1 2 2 Monitoring Statistics Event listeners described in the previous section are all purpose facility For example you may decide to use them to measure various execution statistics of your application While this might be an easy task for simple statistics like how much time was spent on execution of each Java method nevertheless if you want to measure statistics based on URIs and individual resources the implementation might get rather complex soon especially when considering sub resources and sub resource locators To save you the trouble Jersey provides feature for collecting events and calculating a pre defined set of monitori
482. type 148 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 Chunked input In an earlier section the ChunkedOutput was described It was shown how to use a chunked output on the server In order to read chunks on the client the ChunkedInput https jersey java net apidocs 2 10 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
483. u webapp target dependen INFO Copying osgi resource locator 1 0 1l jar to simple heroku webapp tar INFO Copying hk2 utils 2 2 0 b21 jar to simple heroku webapp target depe INFO Copying hk2 api 2 2 0 b21 jar to simple heroku webapp target depend INFO Copying jetty io 9 0 6 v20130930 jar to simple heroku webapp target Getting Started 1 5 1 INFO Copying jetty server 9 0 6 v20130930 jar to simple heroku webapp ta INFO Copying jetty util 9 0 6 v20130930 jar to simple heroku webapp targ INFO Copying jersey client 2 5 jar to simple heroku webapp target depend INFO Copying jetty http 9 0 6 v20130930 jar to simple heroku webapp targ INFO Copying guava 14 0 1 jar to simple heroku webapp target dependency INFO Copying jetty xml1 9 0 6 v20130930 jar to simple heroku webapp targe INFO Copying jersey server 2 5 jar to simple heroku webapp target depend INFO Copying jersey container servlet core 2 5 jar to simple heroku weba INFO Copying javax ws rs api 2 0 jar to simple heroku webapp target depe INFO Copying jetty servlet 9 0 6 v20130930 jar to simple heroku webapp t INFO Copying javax inject 2 2 0 b21 jar to simple heroku webapp target d INFO Copying javax servlet 3 0 0 v201112011016 jar to simple heroku weba INFO Copying javax annotation api 1 2 jar to simple heroku webapp target INFO INFO BUILD SUCCESS INFO INFO Total tim
484. ue 97 JAX RS Entity Providers 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 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 keys 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 https jersey java net apidocs 2 10 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
485. ue Note that enabling MBeans for monitoring statistics may have a negative performance impact and therefore should be enabled only when needed Default value is false ServerProperties MONITORING S AS 5T1 Sn REFRESH ENTER Miftkyali Gig rst Htindicatg hew1 https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html MONITORING_STATISTICS_REFRESH_ I Jersey 2 10 or later often will be monitoring statistics refreshed onStatistics method called Default value is NSDERV AL resh interval ServerProperties OUTBOUND_CONTEAW amp 4 NG TH cd FERR Le Agtinteger value bhat fdefines the https jersey java net apidocs 2 10 jersey org glassfish jersey server buffer size used to buffer the outbound message entity in order to determine its size and set ServerProperties html OUTBOUND_CONTENT_LENGTH_BUFFIEIR value of HTTP Content Jersey 2 2 or later Length header Default value is 8192 ServerProperties PROVIDER_CUASSNAMESnfig server puz https jersey java net apidocs 2 10 jersey org glassfish jersey server ServerProperties html PROVIDER_CLASSNAMES Definesr ofassnammacre class names that implement application specific resources and providers If the property is set the specified classes will be instantiated and registered as either application JAX RS root resources or providers ServerProperties PROVIDER_CLASSRAFHconfig server py https jer
486. uestContext requestContext ContainerRespon throws IOException PRP NRO bh w responseContext getHeaders add X Powered By Jersey ere ous ae ds 129 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 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
487. uests 1 Feature feature authFlow getOAuth1lFeature 2 Client client ClientBuilder newBuilder 3 register feature 4 build Once the feature is configured in the JAX RS Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html or WebTarget http jax rs spec java net nonav 2 0 apidocs javax ws rs client WebTarget html all requests invoked from such Client or WebTarget instance will automatically include an OAuth Authorization HTTP header that contains also the OAuth signature Note that if you already have a valid Access Token for example stored in the database for each of your users then you can skip the authorization flow steps and directly create the OAuth Feature configured to use your Access Token Example 15 10 Build feature from Access Token 1 AccessToken storedToken 2 Feature filterFeature OAuth1lClientSupport builder consumerCredentials 3 feature 4 accessToken storedToken 5 but Ld 3 Here the storedToken represents an AccessToken https jersey java net apidocs 2 10 jersey org glassfish jersey client oauth1 AccessToken html that your client application keeps stored e g in a database Note that the OAuth feature builder API does not require the access token to be set The reason for it is that you might want to build a feature which would register the internal Jersey OAuth ClientRequestFilter and other related providers but which would n
488. ugh an injectable MonitoringStatistics _ https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring MonitoringStatistics html interface The statistics provide general information about the application as well as fine grained execution statistics on particular resources and sub resources and exposed URIs For performance reasons this functionality must be explicitly enabled prior using In addition to the injectable MonitoringStatistics data Jersey is able to expose the statistics as JMX MBeans for example ApplicationMXBean _ https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ApplicationMXBean html Jersey monitoring MXBeans can be accessed programmatically using JMX APIs or browsed via JMX enabled tool JConsole for example This functionality is too by default disabled for performance reasons and must be enabled if needed beta can be found in the jersey server module in org glassfish jersey server monitoring package Monitoring in Jersey is currently supported on the server side 238 Monitoring and Diagnostics 20 1 2 Event Liste ners Jersey defines two types of event listeners that you can implement and register with your application e ApplicationEventListener https jersey java net apidocs 2 10 jersey org glassfish jersey server monitoring ApplicationEventListener htm for listening to application events and e RequestEventListener htt
489. uilder add childResource addMethod GET handledBy new GetInflector final Resource resource resourceBuilder build OANA OB WN FE 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
490. ulating 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 2 0 apidocs javax ws rs ext WriterInterceptor html Reader interceptors are used to manipulate inbound 132 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
491. ultipart package summary html 8 3 1 1 Dependency To use multipart features you need to add jersey media multipart module to your pom xml file lt dependency gt lt grouplid gt org glassfish jersey media lt groupId gt lt artifactId gt jersey media multipart lt artifactId gt lt version gt 2 10 lt version gt lt dependency gt If you re not using Maven make sure to have all needed dependencies see jersey media multipart https jersey java net project info 2 10 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 https jersey java net apidocs 2 10 jersey org glassfish jersey media multipart MultiPartFeature html Example 8 42 Building client with MultiPart feature enabled final Client client ClientBuilder newBuilder register MultiPartFeature class build 123 Support for Common Media Type Representations Example 8 43 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 2 10 examples multipart webapp
492. un the above mentioned examples on GlassFish 4 application server Enabling the OSGi shell in Glassfish Since GlassFish utilizes Apache Felix an OSGi runtime comes out of the box with GlassFish However for security reasons the OSGi shell has been turned off You can however explicitly enable it either by starting GlassFish the asadmin console and creating a Java system property glassfish osgi start level final and setting its value to 3 65 Application Deployment and Runtime Environments 4 9 2 Example 4 19 Start the admin console 1 2 glassfish bin asadmin 3 Use exit to exit and help for online help 4 asadmin gt You can check the actual value of the java property loaded from the configuration file 26 27 asadmin gt list jvm options 28 29 Dglassfish osgi start level final 2 30 And change the value by typing 26 27 asadmin gt create jvm options target server Dglassfish osgi start level fina The second option is to change the value in the osgi properties configuration file Final start level of OSGi framework This is used by GlassFish launcher code to set the start level of the OSGi framework once server is up and running s optional services can start The initial start level of framework is control the standard framework property called org osgi framework startlevel beginni glassfish osgi start level final 3 Ao BwWNE Se oH He He You can then execute the Felix sh
493. un the test client and then stop the application the console output for the deployed server side application would contain the following output Application my monitored application was initialized Request 1 started 241 Monitoring and Diagnostics Resource method POST started for request 1 Request 1 finished Processing time 330 ms Request 2 started Resource method GET started for request 2 Request 2 finished Processing time 4 ms Application my monitored application destroyed 20 1 2 1 Guidelines for implementing Jersey event listeners Implement event listeners as thread safe While individual events will be arriving serially individual listener invocations may occur from different threads Thus make sure that your listeners are processing data safely with respect to their Java Memory Model http en wikipedia org wiki Java_Memory_Model visibility in the example above the fields requestNumber startTime of MyRequestEventListener are final and therefore the same value is visible for all threads executing the onEvent method e Do not block the thread executing the event listeners by performing long running tasks Execution of event listeners is a part of the standard application and request processing and as such needs to finish as quickly as possible to avoid negative impact on overall application performance e Do not try to modify mutable objects returned from ApplicationEvent and RequestEvent ge
494. urceModel Configuration configuration method is executed for each sub resource returned from the sub resource locator The example is simplified and does not do any manipulation but probably in such a case you would want to enhance all sub resources with anew OPTIONS method handlers too It is important to remember that any model processor must always return valid resource model As you might have already noticed in the example above this important rule is not followed If any of the resources in the original resource model would already have an OPTIONS method handler defined adding another handler would cause the application fail 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 163 Chapter 14 Server Sent Events SSE Support 14 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
495. urces gt 15 lt application gt The returned WADL is a XML that contains element resource with path country id This resource has one inner method element with http method as attribute name of java method and its produced representation This description corresponds to defined java resource Now let s look at more complex example The previous WADL does not actually contain all resources exposed in our API There are other resources that are available and are hidden in the previous WADL The previous WADL shows only resources that are provided by the user In the following example the WADL is generated using query parameter detail http localhost 9998 application wadl detail Note that usage of http localhost 9998 application wadl detail true is also valid This will produce the WADL with all resource available in the application 189 41 lt resource gt 42 lt resource path application wadl gt 43 lt method name GET id getWadl gt 44 lt respWAB L Support 45 lt representation mediaType application vnd sun wadl xml gt 46 lt representation mediaType application xml gt Example 16 2 A simple WA io example WADL content je 50 51 52 53 54 59 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 lt jersey extended xmlns jersey http jersey java net gt true
496. urned from the readEntity It is 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 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 135 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 ot
497. urther configurable and either contain a Properties e g FreemarkerMvcProperties class describing all the available properties which could be set in a JAX RS Application ResourceConfig Alternatively the properties are listed directly in the module Feature class Example 19 10 Setting MvcFeature TEMPLATE BASE PATH value in ResourceConfig new ResourceConfig property MvcFeature TEMPLATE BASE PATH templates register MvcFeature class Further configuration of ResourceConfig register 231 MVC Templates Example 19 11 Setting FreemarkerMvcProperties TEMPLATE BASE PATH value in web xml lt servlet gt lt servlet name gt org glassfish jersey examples freemarker MyApplication lt servlet lt servlet class gt org glassfish jersey servlet ServletContainer lt servlet class gt lt init param gt lt param name gt javax ws rs Application lt param name gt lt param value gt org glassfish jersey examples freemarker MyApplication lt param lt init param gt lt init param gt lt param name gt jersey config server mvc templateBasePath freemarker lt param na lt param value gt freemarker lt param value gt lt init param gt lt load on startup gt 1 lt load on startup gt lt servlet gt 19 6 Supported templating engines Jersey provides extension modules that enable support for several templating engines This section lists all the supported engines and
498. uth terminology a Resource Owner Adam has an account on the Twitter Twitter represents the second party This party is called a Service Provider Twitter offers web interface that Adam uses to create new tweets read tweets of others etc Now Adam uses our new web site HelloWorldWeb which is very simple web that says Hello World but it additionally displays the last tweet of the logged user To do so our Web site needs to have an access to the Twitter account of Adam Our Web site is a 3rd party application that wants to connect to the Twitter and get tweets In OAuth such party is called Consumer Consumer would like to use Twitter RESTful APIs to get some data associated with Adam s Twitter account In order to solve this situation Adam could directly give his password to the HelloWorldWeb This would however be rather unsafe especially if we do not know much about authors of the application If Adam would give his password to HelloWorldWeb he would have to deal with the associated security risks First of all Adam would have to fully trust HelloWorldWeb that it will not misuse the full access to his Twitter account Next if Adam would change his password he would need to remember to give the new password also to the HelloWorldWeb application And at last if Adam would like to revoke the HelloWorldWeb access to his Twitter account he would need to change his password again The OAuth protocol has been devised to address all these challenges
499. va 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 request 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
500. ver org glassfish jersey server validation ValidationConfig setConstraintValidatorFa org glassfish jersey server validation ValidationConfig setParameterNameProvider use corresponding methods of the same class without set prefix in the method names 276 Migration Guide e org glassfish jersey server mvc MvcProperties use properties of org glassfish jersey server mvc MvcFeature instead e MVC does not allow to specify the resolving class Resolving class is used to create a path of the template Changes are Annotation attribute Class lt gt org glassfish jersey server mvc Template resolvingClass the attribute was obsolete and therefore removed Resolving class now always the resource class in which the MVC resource method is defined resolvingClass was removed from Viewable https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc Viewable html The constructor no longer accepts this argument and there is no getter for this field e org glassfish jersey server mvc freemarker FreemarkerProperties use FreemarkerMvcFeature _ https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc freemarker FreemarkerMvcFeature html instead e org glassfish jersey server mvc jsp JspProperties use JspMvcFeature https jersey java net apidocs 2 10 jersey org glassfish jersey server mvc jsp JspMvcFeature html instead e org glassfish jersey server model
501. vlet ServletContainer html implementation of Servlet and Servlet Filter API to intebrate with Servlet containers As any JAX RS runtime Jersey provides support for Servlet containers that support Servlet specification version 2 5 and higher To support JAX RS 2 0 asynchronous resources on top of a Servlet container support for Servlet specification version 3 0 or higher is required When deploying to a Servlet container Jersey application is typically packaged as a war file As with any other Servlet application JAX RS application classes are packaged in WEB INF classes or WEB INF 1ib and required application libraries are located in WEB INF lib For more details please refer to the Servlet Specification JSR 315 http jcp org en jsr detail id 3 15 Jersey provides two Servlet modules The first module is the Jersey core Servlet module that provides the core Servlet integration support and is required in any Servlet 2 5 or higher container lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container servlet core lt artifactId gt lt dependency gt To support additional Servlet 3 x deployment modes and asynchronous JAX RS resource programming model an additional Jersey module is required lt dependency gt lt groupid gt org glassfish jersey containers lt groupId gt lt artifactId gt jersey container servlet lt artifactId gt lt dependency gt
502. voking 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 131 Filters and Interceptors 9 2 2 Client filters Client filters are similar to container filters The response can also be aborted in the ClientRequestFilter 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
503. where instance id is an EL expression Parameter values can be extracted from three implicit beans instance Represents the instance of the class that contains the annotated field entity Represents the entity class instance returned by the resource method resource Represents the resource class instance that returned the entity By default URI template parameter values are extracted from the implicit instance bean i e the following two annotations are equivalent InjectLink widgets id InjectLink widgets S instance id The source for URI template parameter values can be changed using the Binding annotation E g the following three annotations are equivalent InjectLink value widgets id bindings Binding name id value resource id InjectLink value widgets value bindings Binding S resource id InjectLink widgets resource id Conditional Link Injection Link value injection can be made conditional by use of the condition property The value of this property is a boolean EL expression and a link will only be injected if the condition expression evaluates to true E g InjectLink value widgets S instance id offers condition S instance offers URI offers In the above a URI will only be injected into the of fers field if the of fers property of the instance is true List of Link Injection You can inject multiple links into an array of a List col
504. wing 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 repository 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 eZe directory You can run tests related to a particular area using the following command 269 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 24 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 270 Chapter 25 Migration Guide 25 1 Migrating from Jersey 2 9 to 2 10 25 1 1 Removed deprecated APIs Following alread
505. 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 entered their username as Galileo the web service will respond to the following URL http example com users Galileo To obtain the value of the username variable the PathParam http jax rs spec java net nonav 2 0 apidocs javax ws rs PathParam html may be used on method parameter of a request method for example Example 3 2 Specifying URI path parameter 1 Path users username 2 public class UserResource 3 4 GET 5 Produces text xml 6 public String getUser PathParam 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 Z2_0 9 In this type of example the username variable will only match user names that begin with one
506. x servlet http HttpSession import org glassfish hk2 api InjectionResolver import org glassfish hk2 api ServiceHandle public class SessionInjectResolver implements InjectionResolver lt SessionInject gt Inject Named InjectionResolver SYSTEM_RESOLVER_NAME InjectionResolver lt Inject gt systemInjectionResolver Override public Object resolve Inject injectee ServiceHandle lt gt handle if HttpSession class injectee getRequiredType return systemInjectionResolver resolve injectee handle return null Override public boolean isConstructorParameterIndicator return false Override public boolean isMethodParameteriIndicator return false 255 Custom Injection and Lifecycle Management The SessionInjectResolver above just delegates to the default HK2 system injection resolver to do the actual work You again need to register your injection resolver with your Jersey application and you can do it the same was as in the previous case Following listing includes HK2 binder that registers both the injection provider from the previous step as well as the new HK2 inject resolver with Jersey application ResourceConfig Note that in this case we re explicitly binding the SessionInjectResolver to a Singleton http docs oracle com javaee 6 api javax inject Singleton html scope to avoid the unnecessary proliferation of SessionInjectResolver instances
507. y client spi ConnectorProvider html SPI has been introduced to decouple Connector https jersey java net apidocs 2 10 jersey org glassfish jersey client spi Connector html instantiation from Client http jax rs spec java net nonav 2 0 apidocs javax ws rs client Client html instance boot strapping As such the connector Connector method has been removed from ClientConfig https jersey java net apidocs 2 10 jersey org glassfish jersey client ClientConfig html API It has been replaced with a newly introduced connectorProvider ConnectorProvider method org glassfish jersey client HttpUrlConnector has been removed from the public API HttpUrlConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnector html should be used to produce HttpURLConnection http docs oracle com javase 6 docs api java net HttpURLConnection html connector instances instead ClientProperties HTTP_URL_CONNECTION_SET_METHOD_WORKAROUND property has been moved to the new HttpUrlConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnector html has been introduced in Jersey 2 4 has been moved to the new HttpUrlConnectorProvider https jersey java net apidocs 2 10 jersey org glassfish jersey client HttpUrlConnector html class as this property is specific to the connector instances created by HttpUrlConnectorProvider only The property has been also renamed to HttpUrlC
508. y deprecated APIs were removed e org glassfish jersey server model ResourceModelContext not used e org glassfish jersey server model ResourceModelListener not used 25 2 Migrating from Jersey 2 8 to 2 9 25 2 1 Release 2 9 Highlights 25 2 1 1 Declarative Linking Gerard updated the Declarative Linking extension module which has been ported to Jersey 2 in version 2 6 You can read more about what Declarative Linking does and what it s capable of in the following blog posts e Declarative Linking in Jersey 2 9 and up http kingsfleet blogspot co uk 2014 05 declarative linking in jersey 29 html e Reading and writing JAX RS Link objects http kingsfleet blogspot co uk 2014 05 reading and writing jax rs link objects html 25 2 1 2 Jackson 2 Our media module that supports working with JSON via Jackson library has been updated to use Jackson 2 x 2 3 2 All samples and tests have been rewritten to use Jackson 2 as well In order to use Jackson 2 in your application you need to add jersey media json jackson it s Jackson dependencies to your class path and register JacksonFeature in your application 25 2 1 3 META INF services We dropped automatic registration of message body providers MessageBodyWriter MessageBodyReader and exception mappers via META INF services mechanism This functionality can be restored by adding jersey metainf services module to the class path of your application Not
509. y suitable for 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 and later 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 used in the definition of a lt servlet name gt element as part of your application s web xm1 deployment descriptor Following example illustrates this approach Example 4 16 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 Ta 6 lt servlet mapping gt 7 lt servlet name gt org foo rest MyApplication lt servlet name gt 8 lt url pattern gt resources lt url pattern gt 9 lt servlet mapping gt 10 11 lt web app gt Note that the lt servlet class gt element is omitted from the Servlet declaration This is a correct declaration utilizing the Servlet 3 0 extension mechanism described in detail in the Section 4 7 2 3 Servlet Pluggability Mechanism section Also note that lt servlet mapping gt is used in the example to define the base resource URI Tip When running in a Servlet 2 x it would instead be necessary to declare the Jersey container Servlet or Filter and pass the Application implementation class

Download Pdf Manuals

Related Search

Related Contents

GE JBP24 QuickClean Electric Kitchen Range    Instruction Manual for 4-Stroke DIO (AF62) Bar Handle Full Kit      cdte mode d`emploi enseignant  Sunix UTS1009B  Handleiding    POSTEINGANGSSYSTEM IM-35 (LE  

Copyright © All rights reserved. Failed to retrieve file